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