Hackathon5 - Howto
From NetBSD Wiki
Contents |
Setting up your environment
This page describes basic steps how to get started for Hackathon5.
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
Guidelines
Converting .list files
Prior to start converting a page, don't forget to update the according entry in the List of .list files stating you are working on the page. It may also be a good idea to ask at #NetBSD-Code, just in case someone missed to update the list.
The convert-to-xml section of "Editing htdocs" has basic intructions about converting .list files to XML.
If you are converting one of the port-specific FAQs, have a look at one of the already converted ones, e.g. htdocs/Ports/i386/faq.xml, as a template.
Tag substitution rules
- Be explicit with your markup. Many .list files simply use tags like <tt> or <i> to markup code snippets, commands, filenames etc. Use approriate tags like <code>, <command> or <filename> instead.
- Markup e-mail adresses with <email>.
- Use man-page entities. They have the form &man.<name>.<section>; and will automaticcaly be translated into appropriate links to the online man-page browser
Updating content
Sometimes, you will find paragraphs like "This is currently not supported/broken as of NetBSD X.Y.Z." Some of these might be good targets for users to hunt down if they are still relevant.
Adding new content
If you're going to add new content, be sure to keep changes separate from the actual conversion. This makes the review process much more easy. First convert and submit, then add new content.
A note on port-specific FAQs: If you think there's some question missing, but you can't provide a decent answer, add the question commented out with a note of the form "XXX: answer me". This will make it easier for port maintainers and other developers to track requests for addtion.
Submitting files and patches
Please be sure to check the following prior to submission:
- Check the section ID's to match the old ones. Otherwise a lot of links will be broken. This should not happen!.
- Make a general check if the new page's structure matches the old one's
- Even though the html output from .xml files should be valid HTML 4.01, this is not always the case. To verify if the new .html file is valid use the validator of the WWW Consortioum.
Converted files and patches should be reviewed by a NetBSD developer (at best by a member of the WWW team) before submission. Ask for a review at #netbsd-code. Once the file/patch has been approved, do the following:
- Update the List of .list files
- Send the file(s)/patch(es) to netbsd-docs@netbsd.org with a subject line containing the string [docathon]
