[PATCH inputproto] Add minimal asciidoc syntax

[Peter Hutterer]

On Thu, Mar 17, 2011 at 03:39:40PM -0600, Matt Dew wrote:
> On 03/16/2011 06:50 PM, Peter Hutterer wrote:
> >On Wed, Mar 16, 2011 at 03:29:09AM -0600, Matt Dew wrote:
> >>On 03/15/2011 07:01 PM, Gaetan Nadon wrote:
> >>>On Wed, 2011-03-16 at 09:12 +1000, Peter Hutterer wrote:
> >>>>asciidoc also converts to docbook. so while there would be some
> >>>>inconsistency, it wouldn't be that bad.
> >>>>
> >>>I thought about that. The strategy would that before it matures,
> >>>asciidoc provides
> >>>a "rapid development process". At one point a more formal docbook
> >>>version is produced
> >>>with all the bells and whistles and integration with the rest of the
> >>>documentation.
> >>
> >>No arguing writing in docbook can be a bit 'challenging' for some things.
> >>
> >>I'm all for keeping it easy for the devs to edit and review patches.
> >>I have a nervous twitch in my stomach about format proliferation
> >>though. I do not want to end up back where we were a year ago.
> >
> >I think the best protection against format proliferation is active
> >maintainership and guidelines. write down what format doc has to be in
> >and people will use it. we have freedom of choice, give us freedom from
> >choice ;)
> >
> 
> I think that first one is the tough part. Active maintainership.
> But the second is easily doable.

might not even be too hard. adding protocol changes kind-of requires active
maintainership because, well, presumably there's _someone_ writing them :)
so all you need is reviewers to shout when the protocol format is
incompatible with what we have.

> >best proof this works: people are still writing roff
> >
> >>The doc will never be considered 'done' though, docs never are.
> >>Someone will have to make the call at some point and say 'close
> >>enough, convert to docbook.'
> >
> >given a reasonable asciidoc source, what is the benefit of converting to
> >docbook? just more highlighting or are there other features that we could
> >really need?
> 
> I went and dug a little more into asciidoc soas to not completely
> talk out of my rear.  I think the big benefit is that docbook
> handles 'collection' which are just that, collections of docs that
> fit together, a set.  The olink tag, for instance, lets us link
> between the docs without having to know the exact install path.  For
> example in the proto docs, you can reference error results that are
> written specifically about in the current doc, and when the docs get
> built, docbook figures out where the link should point to.  it also
> goes the other way, any other doc can reference, for example
> ADDMASTER, and the link will be guaranteed to resolve within the
> collection.
> 
> This makes it possible for distros to install the docs locally
> without any extra massaging. It also makes it easier Alan when
> creating the release docs that go on the website.
> 
> While X is ~240 separate modules, of which only a couple dozen have
> substantial documents,  the docbook lets us create a nice
> collection.
> 
> asciidoc seems to be geared towards individual, standalong
> documents, no concept of crosslinks.  Please correct me if I'm
> wrong.

I don't disagree and I certainly haven't use asciidoc in anything more
complex than a man page. just one comment that I found from a quick search,
suggesting that olink _may_ be possible in asciidoc.
http://groups.google.com/group/asciidoc/browse_thread/thread/4ff80242da4a3634

btw, git uses asciidoc and has some extensive asciidoc.conf. might be
worthwhile to get some tips and tricks from there.

Cheers,
  Peter