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). > > 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
