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

Reply via email to