Package: maint-guide Version: 1.2.11 Severity: wishlist Tags: patch -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
Section 5.8 of the guide contains some information about the creation of manpages. It currently misses information about the XML template. I added the necessary information and attached the patch. The patch also includes some small markup changes for a better overview. Pleaes check it and tell me, if you find issues or if you don't like something. Regards, Daniel - -- System Information: Debian Release: lenny/sid APT prefers unstable APT policy: (850, 'unstable'), (700, 'testing'), (550, 'stable'), (110, 'experimental') Architecture: i386 (i686) Kernel: Linux 2.6.21.5 (PREEMPT) Locale: LANG=de_DE, LC_CTYPE=de_DE (charmap=ISO-8859-1) Shell: /bin/sh linked to /bin/bash - -- no debconf information -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) iD8DBQFGwQvQm0bx+wiPa4wRAum1AJ4ibTQC2ZOx7r+snbhEFh0FlfROigCfTFXu tvF/8zJBlTn2NFn0OP8gDcA= =E5KW -----END PGP SIGNATURE-----
--- maint-guide.sgml~ 2007-01-12 12:35:33.000000000 +0100 +++ maint-guide.sgml 2007-08-14 03:50:50.000000000 +0200 @@ -1382,28 +1382,19 @@ <p>If you don't need this, remove the file. - <sect id="manpage">manpage.1.ex, manpage.sgml.ex + <sect id="manpage">manpage.1.ex, manpage.sgml.ex, manpage.xml.ex <p>Your program(s) should have a manual page. If they don't, each of these files is a template that you can fill out. - <p>Manual pages are normally written in <manref name="nroff" section="1">. + <taglist> + + <tag><file/manpage.1.ex/ + <item><p>Manual pages are normally written in <manref name="nroff" section="1">. The <tt/manpage.1.ex/ example is written in nroff, too. See the <manref name="man" section="7"> manual page for a brief description of how to edit such a file. - <p>If on the other hand you prefer writing SGML instead of nroff, you can - use the <tt/manpage.sgml.ex/ template. If you do this, you have to: - <list> - <item>install the <package/docbook-to-man/ package - <item>add <tt/docbook-to-man/ to the <tt/Build-Depends/ line in the - <tt/control/ file - <item>remove the comment from the docbook-to-man invocation in the - `build' rule of your <tt/rules/ file - </list> - - <p>And remember to rename the file to something like <tt/gentoo.sgml/! - <p>The final manual page file name should include the name of the program it is documenting, so we will rename it from "manpage" to "gentoo". The file name also includes ".1" as the first suffix, which means it's a @@ -1427,6 +1418,60 @@ can tack on another "x" to the section, i.e. <tt/gentoo.1x/. There was no gentoo.1 man page in the original source so I wrote it using information from the example and from upstream docs. + + <tag><file/manpage.sgml.ex/ + <item><p>If on the other hand you prefer writing SGML instead of nroff, you can + use the <tt/manpage.sgml.ex/ template. If you do this, you have to: + + <list> + <item>install the <package/docbook-to-man/ package + <item>add <tt/docbook-to-man/ to the <tt/Build-Depends/ line in the + <tt/control/ file + <item>remove the comment from the docbook-to-man invocation in the + `build' target of your <tt/rules/ file + </list> + + <p>And remember to rename the file to something like <tt/gentoo.sgml/! + + <tag><file/manpage.xml.ex/ + <item><p>If you prefer XML over SGML, you can use the <tt/manpage.xml.ex/ template. + If you do this, you have two choices: + + <list> + <item>install the <package/docbook-xsl/ package and an XSLT processor like + <package/xsltproc/ (recommended) + <item>add the <tt/docbook-xsl/, <tt/docbook-xml/ and <tt/xsltproc/ packages to the + <tt/Build-Depends/ line in the <tt/control/ file + <item>add a rule to the `build' target of your <tt/rules/ file: + <example> +xsltproc --nonet \ + --param make.year.ranges 1 \ + --param make.single.year.ranges 1 \ + --param man.charmap.use.subset 0 \ + -o debian/ \ + /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl \ + debian/manpage.xml + </example> + </item> + </list> + + <p>Alternatively: + + <list> + <item>install the <package/docbook2x/ package + <item>add the <tt/docbook2x/ package to the <tt/Build-Depends/ line in the + <tt/control/ file + <item>add a rule to the `build' target of your <tt/rules/ file: + <example> +docbook2man debian/manpage.xml + </example> + </item> + </list> + + <p>Rename the source file(s) to something like <tt/gentoo.1.xml/ or so and check + the package documentations for stylesheet parameters and output options. + + </taglist> <sect id="menu">menu.ex
