RFC uboot-doc User's Manual Generation Tool

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