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

[John Schmoller <jschmoller@xes-inc.com>]

Hello all,
 
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.  
 
The thought was that everyone needs to develop User's Manuals for their
customers, and there's no reason for us all to reinvent the wheel for
each product we create.  I've written a Perl script, uboot-doc, which is
very loosely based on the kernel-doc documentation creator in Linux.
(Take it easy on my Perl, this is my first script.) The specific syntax
is described in uboot-doc, but the parser takes formatted comments with
@'s and converts the information into DocBook XML. The DocBook XML can be
used to generate HTML, XHTML, PDFs, and text, and can be extended to change
formatting and appearance. The static portions of the manual are taken
from .tmpl files in the doc/manual/ directory, which have basic
precompiler support (#ifdef, #else, #endif) and support for accessing
system environment variables (${TOPDIR}, for example) and any value
found in autoconf.mk, (@CONFIG_BAUDRATE, for example). All template
files in doc/manual/ can be over-ridden by a board specific file in
board/$BOARDDIR/manual. For example, doc/manual/manual.tmpl would be
over-ridden by board/$BOARDDIR/manual/manual.tmpl.

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

Steps to compile your very own manual (using Ubuntu package names):
1) Install xsltproc. I'm using version
1.1.24-2ubuntu2.  If you've got no desire to make text, html, xhtml, or
pdf you don't need this tool.

2) Install docbook-xsl. I'm using version
1.73.2.dfsg.1-5. If you've got no desire to make text, html, xhtml, or
pdf you don't need this tool.

3) FOP needs to be installed with hyphenation support, which is not
available from Synaptic or apt-get.  Use the instructions from 
http://www.linuxfromscratch.org/blfs/view/svn/pst/fop.html to install
your version of FOP (yes, you do need OFFO and JAI). You will need to
install ant if you don't already have it (1.7.1-0ubuntu2).
If you've got no desire to make a PDF, you don't need this tool.

4) If you follow the steps above, the default values of DOCBOOK_XSL_DIR,
XSLT_PROCESSOR, and FO_PROCESSOR should be correct. If you decided to
try to go it your own, set them accordingly. DOCBOOK_XSL_DIR points to
your Docbook stylesheet directory, XSLT_PROCESSOR points to the default
program which compiles XML into it's various forms, and FO_PROCESSOR
points the the default program for turning FO images into PDFs.

5) Once you have the tools installed, you should be able to compile a
manual. This documentation feature was tested on the X-ES's XPedite5370.
make XPEDITE5370_config
make {xml/html/xhtml/pdf/text}
Note: text doesn't work yet as I believe there is an issue with the
docbook style sheets (or possibly how I'm using them).  It's being looked
into. Something about varlistentries not belonging in varlists?  I dunno.

The doc/manual directory also includes a PDF style sheet (uboot_manual.xsl).
By creating your own book_info.tmpl, you can add a company logo
and an address to the cover page. By default these two are left out. It is also
possible to create a completely new style sheet to customize your manual look.
Similarly, HTML output can be customized using CSS. The results of this output
as well as the HTML output can be found on the X-ES website:
www.xes-inc.com/sources/u-boot/index.html
www.xes-inc.com/sources/u-boot/xpedite5370.pdf
Note that I've defined a "mediaobject" and "address" in my custom
board/xes/xpedite5370/book_info.tmpl to place the address and company logo
on the cover page.

I see several advantages to adopting this scheme.
 - Documentation should be easier to keep in sync with code
 - DocBook XML output can be used to generate webpages, PDFs, text, etc, 
   which are all extensible
 - People don't have to reinvent the wheel when writing documentation
 - 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?

Thanks,
John

John Schmoller (3):
  uboot-doc: Initial support of user documentation generator
  uboot-doc: Add example support for uboot-doc
  xpedite5370: Add uboot-doc support

 Makefile                                           |    2 +
 board/xes/xpedite5370/manual/book_info.tmpl        |   52 ++
 board/xes/xpedite5370/manual/booting_linux.tmpl    |  179 ++++
 board/xes/xpedite5370/manual/booting_vxworks.tmpl  |  166 ++++
 board/xes/xpedite5370/manual/manual.tmpl           |   30 +
 board/xes/xpedite5370/manual/redundant_images.tmpl |   50 ++
 board/xes/xpedite5370/manual/scripting.tmpl        |  168 ++++
 common/cmd_i2c.c                                   |   71 ++-
 common/cmd_mem.c                                   |   45 +-
 common/cmd_net.c                                   |   30 +-
 common/env_common.c                                |   35 +
 config.mk                                          |    1 +
 doc/manual/85xx_program_flow.tmpl                  |   74 ++
 doc/manual/book_info.tmpl                          |   35 +
 doc/manual/booting_linux.tmpl                      |  249 ++++++
 doc/manual/config.mk                               |   74 ++
 doc/manual/doc-stream.pl                           |   34 +
 doc/manual/introduction.tmpl                       |  136 +++
 doc/manual/manual.tmpl                             |   26 +
 doc/manual/scripting.tmpl                          |  154 ++++
 doc/manual/setup.tmpl                              |  294 +++++++
 doc/manual/uboot-doc                               |  866 ++++++++++++++++++++
 doc/manual/uboot_manual.xsl                        |  286 +++++++
 include/configs/XPEDITE5370.h                      |   47 ++
 post/tests.c                                       |   16 +
 rules.mk                                           |    7 +
 26 files changed, 3122 insertions(+), 5 deletions(-)
 create mode 100644 board/xes/xpedite5370/manual/book_info.tmpl
 create mode 100644 board/xes/xpedite5370/manual/booting_linux.tmpl
 create mode 100644 board/xes/xpedite5370/manual/booting_vxworks.tmpl
 create mode 100644 board/xes/xpedite5370/manual/manual.tmpl
 create mode 100644 board/xes/xpedite5370/manual/redundant_images.tmpl
 create mode 100644 board/xes/xpedite5370/manual/scripting.tmpl
 create mode 100644 doc/manual/85xx_program_flow.tmpl
 create mode 100644 doc/manual/book_info.tmpl
 create mode 100644 doc/manual/booting_linux.tmpl
 create mode 100644 doc/manual/config.mk
 create mode 100644 doc/manual/doc-stream.pl
 create mode 100644 doc/manual/introduction.tmpl
 create mode 100644 doc/manual/manual.tmpl
 create mode 100644 doc/manual/scripting.tmpl
 create mode 100644 doc/manual/setup.tmpl
 create mode 100644 doc/manual/uboot-doc
 create mode 100644 doc/manual/uboot_manual.xsl