[PATCH inputproto] Add minimal asciidoc syntax

[Peter Hutterer]

On Tue, Mar 15, 2011 at 09:01:40AM -0400, Gaetan Nadon wrote:
> On Tue, 2011-03-15 at 15:29 +1000, Peter Hutterer wrote:
> 
> > Though this protocol description is mainly to be viewed as textfile, a
> > few
> > minor changes make it parsable for asciidoc to spit out reasonably
> > nicely-formatted html code.
> > 
> > Changes include:
> > - underline section headers with the matching lines
> > - add linebreaks before lists to parse them as lists
> > - change indentation level for normal text to be left-marging aligned
> > and
> >   for <pre> text to be indented
> > - comment out section dividers
> > 
> > It's possible to run asciidoc XI2proto.txt and get some nice html
> > output
> > now.
> > 
> 
> 
> Nothing wrong with the patch itself, but there is a conflict in
> documentation strategy. We have half the protos in docbook format and
> half in text format. The rest of X.Org is in docbook format. I am not
> trying to say it is better, but having all the docs in one format is
> better than having multiple formats like we used to have before the
> conversion.
> 
> I don't want to start a debate on docbook vs asciidoc but shouldn't all
> protos be documented with the same technology? I see them as the
> chapters of one book (conceptually speaking) rather than discrete
> entities. The driver to merge the protos is a hint that they form a
> cohesive whole and therefore should be documented in a likewise fashion.

the major difference between, say, the X11 protocol and XI is that the
second one is still being developed on. For reasonably static documents
docbook is a good choice but the xml makes it a pain to review. If you look
at libXi's git history, I converted the man pages to docbook but gave up
after a while and moved over to asciidoc because it was just too painful.
The harder you make the spec to review and read, the less errors people will
find. That's why I like asciidoc. it makes it easy to write something that
can be parsed and converted into pretty rendering - without messing up the
original source document.

asciidoc also converts to docbook. so while there would be some
inconsistency, it wouldn't be that bad.

Cheers,
  Peter