Thread: Manpage writing guidelines?
To be able to upload to official Debian, I need to have a manpage for each program uploaded in the package. I wrote a long time ago a small manpage for pgadmin3 and I am about to write one for pgagent. Here are some questions: - wouldn't it be a good thing that pgadmin3.1 is pushed out of pkg/debian to a more proper place and included in the make install process? - what tools should we use to write our manpages? Something like xml or whatever? I mean, if we are about to do something to automate html help generation and other thing I'm not aware of, maybe it would be a good thing to unify the way we work. Any ideas? Regards, Raph
Hi Raph, 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 improvingthe doc build just last week (it's perhaps the biggest task for me when packing pgInstaller or pgAdmin at the moment). Regards, Dave. -----Original Message----- From: Raphaël Enrici [mailto:blacknoz@club-internet.fr] Sent: Sun 11/6/2005 12:56 PM To: PgAdmin Hackers; Dave Page; Andreas Pflug Subject: Manpage writing guidelines? To be able to upload to official Debian, I need to have a manpage for each program uploaded in the package. I wrote a long time ago a small manpage for pgadmin3 and I am about to write one for pgagent. Here are some questions: - wouldn't it be a good thing that pgadmin3.1 is pushed out of pkg/debian to a more proper place and included in the make install process? - what tools should we use to write our manpages? Something like xml or whatever? I mean, if we are about to do something to automate html help generation and other thing I'm not aware of, maybe it would be a good thing to unify the way we work. Any ideas? Regards, Raph
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 ? 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 ? Regards. -- Guillaume. <!-- http://abs.traduc.org/ http://lfs.traduc.org/ http://traduc.postgresqlfr.org/ -->
On 6/11/05 6:52 pm, "Guillaume LELARGE" <gleu@wanadoo.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
Dave Page wrote: > <snip> > 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! I remember some discuss on the list where it was considered to be able to do this without MS Workshop. Some track to follow concerning this? <snip> > >>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? If we decide to provide separated language pack we should definetly take in consideration the impact on packaging stuff and/or the ability to install these packs in user mode and if so the support of indicents due to such user install. However, I think that may be a good idea if well thought and done. Regards, Raph