Contributing to htdocs, NetBSD's websites and online documentation
From NetBSD Wiki
How to create and submit xml-based webpages and chapters for the NetBSD Documentation.
Contents |
Useful tools
Emacs with nxml-mode
Configuration:
Use:
Quanta Plus (part of KDE)
Getting started with htdocs
Fetching htdocs
The htdocs CVS repository can be obtained via anonymous CVS from anoncvs.netbsd.org or one of its mirrors. To get a working copy issue the following commands:
If you're using csh (or similar):
$ setenv CVSROOT anoncvs@anoncvs.netbsd.org:/cvsroot $ setenv CVS_RSH ssh
If you're using sh (or similar):
$ export CVSROOT="anoncvs@anoncvs.netbsd.org:/cvsroot" $ export CVS_RSH="ssh"
Checkout the sources: (htdocs requires 137 MB of free disk space)
$ cvs co htdocs
Installing the toolchain
You will need a number of tools in order to build and work with htdocs. All neccessary tools can be easily installed using pkgsrc:
# cd /usr/pkgsrc/meta-pkgs/netbsd-www # make install clean clean-depends # cd /usr/pkgsrc/meta-pkgs/netbsd-doc # make install clean clean-depends # cd /usr/pkgsrc/meta-pkgs/netbsd-doc-print # make install clean clean-depends
Webpage documents (FAQ or HOWTO)
Files to adjust
The following files need to be adjusted to add a new document:
- /htdocs/layout.xml
- /htdocs/.../Makefile
Creating a webpage document
Choose an existing webpage as a template, for example the "NetBSD Bootable CD ROM HOWTO" (/htdocs/Documentation/bootcd.xml). Edit your own brandnew.xml file (using the text editor of your choice).
Add an entry into the Makefile for your brandnew.xml:
XMLDOCS+= brandnew
If your document is finished run 'make' to build newfile.html and correct all eventually displayed errors. Re'run until no more errors occur
Although the html output from .xml files should be valid HTML 4.01, this is not always the case. To verify the new .html file is valid use the validator of the WWW Consortioum.
The NetBSD guide
Files to adjust
The following files need to be adjusted to add a new chapter:
- /htdocs/guide/en/Makefile
- /htdocs/guide/en/netbsd.xml
- /htdocs/guide/en/chapters.ent
Creating a chapter for the NetBSD Guide
Change into the guide subdirectory:
$ cd /htdocs/guide/en/
Choose an existing chapter as a template. Write your own chap-brandnew.xml file.
Add your new file to the directories Makefile:
SRCS+= chap-brandnew.xml
Make the following entry into the chatpters.ent file:
<!ENTITY chap-brandnew SYSTEM "chap-brandnew.xml">
At last, edit the netbsd.xml file:
&chap-brandnew;
When you have finished the document run 'make' and correct all eventually displayed errors. Re'run until no more errors occur
Don't forget to verify the new .html file of your chapter, using the WWW validator.
