Dear John,
in message 1248813631.3915.102.camel@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.
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.
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.
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.
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.
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 :)
Heh. Look at the DULG implementation... it's simple for the first 3 or 4 boards, especially when these are similar. But try supporting ARM and PowerPC and MIPS boards from N different vendors, with different kernel versions etc.
This would make DUTS/DULG more appealing. What is the process of generating DocBook XML from DUTS/DULG?
What would you need DocBook XML for?
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.
Ah, I see.
Well, we use htmldoc to generate .pdf and .ps files from HTML; you could for example use Tidy to convert HTML to DocBook (and I'm sure there are lots of other tools that can do that).
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.
Yes, I know. Sorry, patches arrived shortly after I started replying, and I didn;t notice.
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
Indeed there is a lot of manual labor involved in preparing and updating the documentation (the framework, that is; once a board has been configured and added to DUTS, generating the needed include files is mostly an automatic procedure - just the upload of the files to the web server has to be triggered manually, but even this is scripted).
But you have to spend at least the same amount of writing and updating the documentation, don't you?
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.
A very, very old version of the DULG was set up like this, using a set of Perl scripts and generating DokBoot output. We switched to the wiki based approach some 6 years ago, and I never had the slightest wish to switch back.
Best regards,
Wolfgang Denk