Re: [U-Boot] [RFC 0/3] uboot-doc User's Manual Generation Tool
On Tue, 2009-07-28 at 23:27 +0200, Wolfgang Denk wrote: Dear John, in message 1248813631.3915.102.ca...@johns you wrote: 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 Correct. And the DULG itself is a wiki (TWiki at the moment, to be converted to Foswiki ASAP) based framework which holds the static parts of the documentation. 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 You probably can export the DULG into XML, too - but what would that be good for? At the moment we export it into PDF, PostScript, HTML and plain text. Exporting to XML (and specifically DocBook XML, which is widely supported and accepted as a standard (at least that's what the tech writer next to me says :) ) is, I feel, a key to this whole process. Since XML doesn't specify a style, but rather what the content *means*, style sheets can be designed to turn the DocBook XML into anything, in any format, rearranged in any way, and with any style (fonts, colors, graphics). Again, I'm not familiar with the process you use to export HTML to PFD, PS, etc. but I'm guessing that the formatting and style end up being very similar. develop a system that's completely automated. I also noticed in a quick Hm... completely automated is a nice buzzword, but you still have to write the documentation in the first place. You're in luck, I've already volunteered to write it in the first place :) and much of it is already done. Take a look at the manual posted on the X-ES website and see for yourself. http://www.xes-inc.com/sources/u-boot/xpedite5370.pdf This manual was completely generated with my tool. The nice thing of the wiki based approach is that you can have a (even random) collection of pages which can be linearized and brought into arbitrary sets of linear doucumentation - this is what the WebOrder pages are good for - see http://www.denx.de/wiki/DULG/WebOrder So you can use the same set of wiki pages an genreate for example the full fledged manual, a short version including only the most significant topics and an extended version including other stuff that is normally not part of the manual - all from the same envrionment. This is definitely possible with DocBook XML. For those who care, I'm thinking the @role attribute available in standard DocBook, though there may be a better way. I'll talk this through with our tech writers. 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? Soemone still has to write the documentation - and this is not always done in sync with the code. Your approach of including the documentation with the source code makes it more likely that one remebers to update the docs as well, but just remember how many places there are where code and comments don't agree - it's no guarantee either. I would guess someone is several dozen times more likely to update a documentation snippet in the source over modifying a Wiki page. If you find such areas in the DULG that are out of sync or missing please feel free to add them - everybody can contribute and modify the pages or add new content. And everyboidy can modify and extend the DUTS test cases, too. 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. That's what the DULG does, so you are truely duplicating efforts. As I mentioned earlier, it seems to me that most vendors are creating their own manuals. That either means knowledge of the existence of DULG is limited, or the tool isn't meeting people's needs. In order to use it, you need to download a completely separate package (DUTS), learn to use it, then hand edit the output into a Wiki page. The advantage with a documentation engine distributed with the sources is that there is no learning curve. make pdf creates a perfectly suitable PDF manual, and with a little work (first time only) they can make it look like anything and chug out manuals for all their boards in minutes. 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
Re: [U-Boot] [RFC 0/3] uboot-doc User's Manual Generation Tool
On Tue, 2009-07-28 at 19:49 +0200, Wolfgang Denk wrote: Dear John Schmoller, In message cover.1248798202.git.jschmol...@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
Re: [U-Boot] [RFC 2/3] uboot-doc: Add example support for uboot-doc
On Tue, 2009-07-28 at 19:52 +0200, Wolfgang Denk wrote: Dear John Schmoller, In message 310e8398479f23a6bfaceccf6cc86631b7bff4dc.1248798202.git.jschmol...@xes-inc.com you wrote: Add support to a small subset of commands, environment variables, and POSTs. These are meant to show the syntax and capabilities of the uboot-doc parser. Signed-off-by: John Schmoller jschmol...@xes-inc.com --- common/cmd_i2c.c| 71 ++- common/cmd_mem.c| 45 +++- common/cmd_net.c| 30 - common/env_common.c | 35 + post/tests.c| 16 +++ 5 files changed, 192 insertions(+), 5 deletions(-) diff --git a/common/cmd_i2c.c b/common/cmd_i2c.c index 8f0fc9e..14d394c 100644 --- a/common/cmd_i2c.c +++ b/common/cmd_i2c.c @@ -1297,7 +1297,70 @@ int do_i2c(cmd_tbl_t * cmdtp, int flag, int argc, char *argv[]) } /***/ - +/** + * @cmd: i2c speed + * @sect: I2C + * @param[or]: speed - target I2C bus speed + * @desc: Show or set I2C bus speed + */ +/** + * @cmd: i2c dev + * @sect: I2C + * @param[or]: dev - I2C device to make current + * @desc: Show or set current I2C bus + */ +/** + * @cmd: i2c md + * @sect: I2C + * @param: chip - I2C address of desired device + * @param: address[.0, .1, .2] - Address into I2C device + * @param[or]: # of objects - Numer of bytes to read + * @desc: Read from I2C device + */ +/** + * @cmd: i2c mm + * @sect: I2C + * @param: chip - I2C address of desired device + * @param: address[.0, .1, .2] - Address into I2C device + * @desc: Write to I2C device (auto-incrementing) + */ +/** + * @cmd: i2c mw + * @sect: I2C + * @param: chip - I2C address of desired device + * @param: address[.0, .1, .2] - Address into I2C device + * @param: value - Value to write to I2C address + * @param[or]: count - Number of bytes to write + * @desc: Write to I2C device (fill) + */ +/** + * @cmd: i2c nm + * @sect: I2C + * @param: chip - I2C address of desired device + * @param: address[.0, .1, .2] - Address into I2C device + * @desc: Write to I2C device (constant address) + */ +/** + * @cmd: i2c crc32 + * @sect: I2C + * @param: chip - I2C address of desired device + * @param: address[.0, .1, .2] - Address into I2C device + * @param: count - Number of bytes to CRC + * @desc: Computes the CRC32 checksum of an address range + */ +/** + * @cmd: i2c probe + * @sect: I2C + * @desc: Shows all the devices on the I2C bus + */ +/** + * @cmd: i2c loop + * @sect: I2C + * @param: chip - I2C address of desired device + * @param: address[.0, .1, .2] - Address into I2C device + * @param: # of objects - Number of bytes to loop over + * @desc: Looping read of device. Never returns. + */ Hm... isn't this basicly duplicating the information you get when running the help command? Then why don't you simply include that output here, like we do in the DULG? To me this seems to be a mix of API documentation (which would be useful, but you do it for the wrong set of functions) and User's Manual (where it mostly seems to be a duplication of information, and maintaining redundant information has never been a good idea). It's true, I was a little lax on commenting the I2C commands. If I were to move forward with this documentation tool, I would comment these commands more thoroughly like I did with the Memory commands. Thanks, John ___ U-Boot mailing list U-Boot@lists.denx.de http://lists.denx.de/mailman/listinfo/u-boot
