On 10/29/06, Stuart Rackham srackham-at-methods.co.nz |asciidoc| <...> wrote: > Yang wrote: > > 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.) > > As I mention previously this is not something that can't be > implemented via configuration files alone, you need to dig into the > source (the List class is a good place to start).
"not something that can't be" is a double negative. :) Yang > > > > > > > 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.) > > There's information in the AsciiDoc User Guide and the best examples are > the actual AsciiDoc .conf files. > > > > > > >> > >>> - 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 > > > > > Cheers, Stuart > -- > Stuart Rackham > _______________________________________________ Asciidoc-discuss mailing list Asciidoc-discuss@metaperl.com http://metaperl.com/cgi-bin/mailman/listinfo/asciidoc-discuss
