Re: Manpage writing guidelines?

On 6/11/05 6:52 pm, "Guillaume LELARGE" <gleu(at)wanadoo(dot)fr> wrote:

> Le Dimanche 06 Novembre 2005 19:24, Dave Page a écrit :
>> There are obviously no guidelines at the moment, so please write whatever
>> seems appropriate for now.
>>
>> I do plan to work on the docs this cycle, so please raise this again then
>> if I forget. Andreas and I were talking about improving the doc build just
>> last week (it's perhaps the biggest task for me when packing pgInstaller or
>> pgAdmin at the moment).
>>
>
> Can you explain a bit what is the daunting task for docs ?

OK, I'll try to remember everything!

1) In a postgresql source tree, run 'make htmlhelp'. This will most likely
crash in xsltproc after 10 minutes or so as seen by numerous people on
various OS's.

2) Tar up the doc/src/sgml directory and copy it to a Windows machine (fc4
64 bit has also worked for me, but not recently). Re-run the xsltproc step
on this box. I do this in 2 steps, because setting up docbook et al. on
Windows is non-trivial.

3) Repeat 1 & 2 for the Slony docs.

4) Manually merge both the PG and Slony help project, index and contents
files into the pgAdmin ones. Paths in each file will need to be prefixed
with pg/ or slony/ as appropriate.

5) Copy the the PG and Slony docs into the appropriate en_US subdirectory.

5) Load the project into Microsoft HTML Help Workshop. Check the index
structure, and move at least 1 item. If necessary, move it, then move it
back. This makes the IDE rewrite the index file and fixup an broken markup,
or markup it doesn't like for reasons you probably won't ever be able to
spot!

6) Repeat 5 for the contents file.

7) Save both files, as well as the project file.

8) Build the HMTL Help File.

9) Generate pgadmin3.hhp.cached file use on *nix, using hhp2cached. If this
crashes, try again a couple of times until it works. You might want to
prefix the filename with .\ .

10) Commit the updated docs and indexes etc. to SVN.

> I think I should include the PostgreSQL french manual in pgAdmin but I don't
> know if there is an automated way to do the conversion docbook sgml to chm.
> Can you explain how you did it ?

The idea always was to get full manuals for each language, but then
originally we didn't bundle the pgAdmin and Slony docs. The problem now is
that if we do so, the tarball is rapidly going to get huge. I think if we're
going to do this, we a) need some serious commitment form the translators
that it will be maintained, and b) need to look at packaging translations as
'language packs' that can be downloaded separately from the main package in
both the source and binary distributions.

Thoughts?

Regards, Dave