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

[Wolfgang Denk]

Dear John,

in message <1248813631.3915.102.camel at 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

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
I had the rare misfortune of being one of the first people to try and
implement a PL/1 compiler.                             -- T. Cheatham