[U-Boot] [RFC 0/3] uboot-doc User's Manual Generation Tool

[Wolfgang Denk]

Dear John Schmoller,

In message <cover.1248798202.git.jschmoller at xes-inc.com> you wrote:
>  
> I've been working on writing a User's Manual generation tool, and before
> I get too far I'd like to see if this is something the U-Boot community
> would be interested in.  

Anything wrong with the User's Manual generation tool we already have
in use (DUTS) for example to generate the DULG?

> General Control Flow:
> C pre-processor -> doc_stream.pl : pre-processed code gets everything but
> comments with an @ stripped away
> doc_stream.pl -> autoconf_doc.txt : "interesting" comments get sent to this
> file
> autoconf_doc.txt -> uboot-doc : file is parsed and comments are turned to XML
>  *.tmpl -> uboot-doc : template files are processed into XML
>  *.xml -> xsltproc : XML is converted into desired output format
>  *.fo -> fop : (PDFs only) fo files are translated to PDF

What you describe does not sound like a user's manual to me, but more
like some API documentation - whioch is a completely different  thing
(and something we really don't have yet).

Your approach may be suitable for standard  documents,  but  in  many
years  of  working  with U-Boot (and Linux) we found that it does not
work so well with the specific needs we have for a User's Manual. One
issue is that you have to support many different boards (well,  maybe
not  you  as  a user, but we as a community). And you have to include
examples. And examples must really fit the board. If you for  example
provide  a  manual entry for the "erase" command you better make sure
that your example does not erase a range of flash that on some  board
happens to hold the U-Boot image. etc.

That's how we came to the DULG we have today. I'm still convinced that
this is a really well-working approach.

It seems you don;t address this issue yet.


> I see several advantages to adopting this scheme.
>  - Documentation should be easier to keep in sync with code

Better than what we have with the DULG? I doubt it.

>  - DocBook XML output can be used to generate webpages, PDFs, text, etc, 
>    which are all extensible

We do the same with the DULG.

>  - People don't have to reinvent the wheel when writing documentation

Well, you just did that, it seems ;-)

>  - Source code ends up being thouroughly commented
> 
> These patches are just meant to be an example of how in-code documentation
> could be used. You'll also notice there are many warnings regarding variables
> the manual is referencing which aren't defined yet. I wanted to get some
> feedback before diving in too far. What do others think? Is this worth
> pursuing?

Hm... we cannot look at your patches, you just posted the patch
statistics, but no content.

The documentation itself seems to duplicate a lot of content we  have
in  the  DULG.  I  have  to  admit  that I'd prefer to see the effort
invested in improving the existing  manual,  than  to  come  up  with
something different (and, as it seems, less flexible).

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
Reader, suppose you were an idiot. And suppose you were a  member  of
Congress. But I repeat myself.                           - Mark Twain