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