[PATCH inputproto] Add minimal asciidoc syntax

[Matt Dew]

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.


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

Matt