On 10/25/06, Stuart Rackham srackham-at-methods.co.nz |asciidoc| <...> wrote: > Hi Yang > > Yang wrote: > > Hi, I'd like to share some ideas for enhancement to the author, with a > > focus on improving the source readability: > > > > - List continuations. Instead of +, asciidoc can treat subsequent > > paragraphs of the same indentation level as continuations (and only > > incrementally indented paragraphs as literal paragraphs). > > > > Like this! (AKA the off-side rule.) > > > > $ some literal text > > $ some more literal text > > > > Here's some more normal text. > > Yes, that does make sense. When I designed the list syntax I > deliberately steered clear of relying on indentation as a nesting > mechanism -- partly because I think it's to fussy to enter and partly > because it just seemed harder. This is not something that can't be > implemented via configuration files alone. Whether or not indentations > would introduce regression problems is another thing.
How would I go about implementing this via configuration files? At least some starting points (in terms of what variables to look at) would be good. BTW are there any tutorials or sets of examples on configuring AsciiDoc? A quick search turned up nothing. (The user guide sections on configuration seem to serve better as a reference.) While it may be marginally fussier to have indentation in the source (I don't think it is), it certainly makes things more readable. So this leads me to my next question: is source readability a primary goal of AsciiDoc? (If not...well, you've inadvertently done a terrific job of keeping it readable, at least much more so than ReST.) > > - URL links. Instead of the somewhat unreadable http://blah/[syntax] > > currently available, here are some suggestions (mostly my own ideas, > > though I recall liking Markdown's syntax quite a bit): > > > > - Adopt the near-universal <http://angle-bracket-syntax/> for simple > > URLs that aren't masked with display text. > > > > - Simply enclose [the link] in brackets, a la wiki markup, then look > > for resolutions in the form of foot- or end-notes (example below). > > IMO, brackets are primarily seen in listing text (code) or > > `monospaced font` (which IMO should be treated as listings, so > > things like `this --and --that` don't screw us over) or > > "[sometimes] quoted text," but in case someone thinks of a > > significant counterexample, the next-best thing is [[double > > brackets]]. > > > > [the link] <news://my-link/> > > > > - [In-line masked links] <http://like-this-one/> can look better. > > Downsides to the current asciidoc syntax include: (1) the URL > > precedes the link text, (2) the link text is parenthesized, when > > it should be the main focus, and (3) ugliness - no spacing between > > the URL and the text. > > > > - Bibliography [taoup] and [cross-referencing] <blockid> syntax > > could also look similar. Also, it doesn't make much sense to > > distinguish <<xref,cross references>> from http://blah[external > > references]. > > > > [blockid] > > Although the above proposals share a lot of the same syntax, it is > > often clear from (non-local) context how things should be dealt > > with. > > > > - Even if you don't agree with the above as the default, even the > > ability to configure things to behave as above would be awesome. > > I guess, in this case at least, beauty is in the eye of the beholder :-) > It always surprises me how, if you use them enough, weird syntaxes grow > on you to the point that you think they're perfectly normal. Though I do > concede that this can be a problem if you're having to chop and change > between apps that use different syntaxes for the the same semantics. If > it really bugs you the alternative syntaxes should be achievable by > editing the appropriate configuration file macros (just be careful to > refer to special character <> by their entity values). Again, any pointers here would be much appreciated. (The more details, the better, of course.) > > > > > > - Developers' documentation, to make it easier for others to > > understand (from a big-picture perspective) how the code is > > organized, such that we might be able to contribute more efficiently > > to the project. > > AsciiDoc is a small fairly straight-forward program (just a 4000 line > Python script), and while I agree that a nice overview will, well, give > you nice overview and maybe a leg up the learning curve, if you want to > modify the source code there's no substitute for a working knowledge of > the application and just reading the source code. While I've found that > it's always a psychological hurdle to open up someone else source, you > very quickly get a much better understanding of how things are put together. Hmm, you're right - it's not big at all (I didn't even bother sizing it up before). However, given your claim that the above requests can all be directly implemented via configuration files, modifying the engine seems unnecessary. Thanks, Yang > > > > > > The above things are really the bane of my daily use of the otherwise > > brilliant asciidoc. How much of the above can already be addressed > > (via configs, etc.)? How much work would the rest be to implement? > > Eager to hear your thoughts! > > Most open source projects are written to fulfill the author's personal > needs, AsciiDoc is no exception. I usually add features because I need > them (thankfully my needs are sufficiently general to make AsciiDoc > useful to others). I'm also constrained by the amount of time I can > devote to AsciiDoc. > > Having said that I'm always happy, given the time, to apply submitted > patches (provided they add something genuinely new, are widely > applicable, fit in nicely with the rest of the application, and don't > cause regression problems). The experimental LaTeX front-end developed > by Benjamin Klum is a recent example. > > I'm also happy to accept patches and erratum for the documentation plus > any additional pages or links for the website. > > > > > > Yang > > > > + [taoup] The Art Of UNIX Programming. Blah Blah. > > > > _______________________________________________ > > Asciidoc-discuss mailing list > > Asciidoc-discuss@metaperl.com > > http://metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss > > > > Cheers, Stuart > -- > Stuart Rackham _______________________________________________ Asciidoc-discuss mailing list Asciidoc-discuss@metaperl.com http://metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss
