Dear John Schmoller,
In message cover.1248798202.git.jschmoller@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