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

[jschmoller]

On Tue, 2009-07-28 at 19:49 +0200, Wolfgang Denk wrote:
> 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?

I have to admit, I'm not very familiar with DUTS, so read up a little on
it before responding.  So please correct me if I've misinterpreted
something.

It seems to me that DUTS is designed to test U-Boot and also automates
the running of commands whose output can be put online in the DULG. I
didn't notice any documented procedure on how to turn the DULG into XML,
extensible PDFs, etc. It also seems as if the DULG is a combination of
hand-edited wiki pages as well as the DUTS output? I was hoping to
develop a system that's completely automated. I also noticed in a quick
probe around that a few items in the DULG seem to be out of sync (imd
vs. i2c md, source vs. autoscr, etc.) and DHCP seems to be out of date
as well. Is the process for updating the DULG automatic? If so, how is
it done?

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

As I mentioned, I borrowed this idea from the kernel-doc script in
Linux, which does do API documentation.  But my hope for the uboot-doc
tool would be to create user documentation, or a manual we'd provide to
a customer when they purchased a product that would describe available
commands, environment variables, common operations, etc.

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

It's my hope that the documentation system I proposed can be made
flexible enough to support things such as this without too much
headache.  That's the hope at least :)

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

That's correct, I wanted to get feedback before spending too much time
digging into the details.

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

This would make DUTS/DULG more appealing.  What is the process of
generating DocBook XML from DUTS/DULG?

> >  - People don't have to reinvent the wheel when writing documentation
> 
> Well, you just did that, it seems ;-)
> 

It's true, I may have. :)  On the other hand, it seems that there are
still a lot of people who are in the same boat.  Most manuals I have
seen from other embedded companies (Freescale, Analog Devices, etc.)
seem to provide their own format/content. Additionally, most companies
will prefer to have their content formatted to match the rest of their
manuals, which is easily done from DocBook XML. Again, if you can do
that with DUTS/DULG, then that's great and probably eliminates the need
for this tool.

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

This is just the patch series introduction, the actual content appears
in 1-3.

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

As I mentioned, I'm not all that familiar with the abilities of
DUTS/DULG, but I got the impression that there was still a fair amount
of manual labor involved for each manual.  Thus most people (that I'm
familiar with) provide their own documentation and "reinvent the wheel".
I was hoping that creating documentation from comments in the source
would be easier to maintain and providing DocBook output would allow
others to more easily reuse the U-Boot manual contents.

Thanks for your time,
John