Appendix D. Editing guidelines for the pkgsrc guide

Table of Contents

D.1. Targets
D.2. Procedure

This section contains information on editing the pkgsrc guide itself.

D.1. Targets

The pkgsrc guide's source code is stored in pkgsrc/doc/guide/files, and several files are created from it:

  • pkgsrc/doc/pkgsrc.txt

  • pkgsrc/doc/pkgsrc.html

  • http://www.NetBSD.org/Documentation/pkgsrc/: the documentation on the NetBSD website will be built from pkgsrc and kept up to date on the web server itself. This means you must make sure that your changes haven't broken the build!

  • http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.pdf: PDF version of the pkgsrc guide.

  • http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.ps: PostScript version of the pkgsrc guide.

D.2. Procedure

The procedure to edit the pkgsrc guide is:

  • Make sure you have the packages needed to re-generate the pkgsrc guide (and other XML-based NetBSD documentation) installed. These are “netbsd-doc” for creating the ASCII and HTML versions, and “netbsd-doc-print” for the PostScript and PDF versions. You will need both packages installed, to make sure documentation is consistent across all formats. The packages can be found in pkgsrc/meta-pkgs/netbsd-doc and pkgsrc/meta-pkgs/netbsd-doc-print.

  • Edit the XML file(s) in pkgsrc/doc/guide/files.

  • Run make extract && make do-lint in pkgsrc/doc/guide to check the XML syntax, and fix it if needed.

  • Run make in pkgsrc/doc/guide to build the HTML and ASCII version.

  • If all is well, run make install-doc to put the generated files into pkgsrc/doc.

  • cvs commit pkgsrc/doc/guide/files

  • cvs commit -m re-generate pkgsrc/doc/pkgsrc.{html,txt}

  • Until the webserver on www.NetBSD.org is really updated automatically to pick up changes to the pkgsrc guide automatically, also run make install-htdocs HTDOCSDIR=../../../htdocs (or similar, adjust HTDOCSDIR!).

  • cvs commit htdocs/Documentation/pkgsrc