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

    [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

    Although the above proposals share a lot of the same syntax, it is
    often clear from (non-local) context how things should be dealt

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


+ [taoup] The Art Of UNIX Programming. Blah Blah.

Asciidoc-discuss mailing list

Reply via email to