NetBSD Developer Documentation: Editing htdocs

This is intended to become a reference for those wishing to edit htdocs (the CVS repository for the NetBSD web server).

General notes on htdocs

• Who can edit htdocs
• What is required to edit htdocs
• Validate your HTML
• NetBSD.org naming scheme
• What are .list files, and how to use them
• Processing .xml (docbook-website) files
• Renaming or moving files
• What is the reasoning behind the flag links with empty.gif?
• How do the pages get to the web server, and when?

Adding to specific areas

• Adding to the 'Sites running NetBSD' gallery
• Adding news items
• Adding Events
• Adding to/editing the MailingLists page
• Consultants for hire

Related documentation

• News story guidelines
• Translating htdocs

General notes on htdocs

Who can edit htdocs (top)

Anyone with write access to the NetBSD CVS tree can checkout htdocs and make changes, and in fact is encouraged to do so. In particular as developers add features and drivers they should update the appropriate hardware or port homepage. Use your NetBSD.org login against cvs.NetBSD.org and checkout 'htdocs'.

What is required to edit htdocs (top)

• Read the CVS introduction.
• Install netbsd-www, which provides the tools required to build the web site.
• Set your CVSROOT as indicated and 'cvs checkout htdocs.
• Edit your preferred file, type make to rebuild the output files (if necessary).
• Check the results using cvs diff, and cvs commit if everything is good.

Validate your HTML (top)

After making any changes you should run your html through an HTML verifier such as weblint, or better still http://validator.w3.org/. The URL for a link to an index.html file should not include the trailing index.html. If you use weblint you may want to add the following to your ~/.weblintrc.

	extension Netscape

NetBSD.org naming scheme (top)

Make sure you use NetBSD.org and not any other scheme in links, mailto's or other pointers.

What are .list files, and how to use them (top)

A .list file contains standard HTML with additional special tags to simplify formatting. It is processed by list2html.pl into the desired .html file.

There should be a Makefile in each directory which handles processing the .list files into .html, and will recurse into any subdirs containing Makefiles.

Continuation lines are understood (useful for the special tags).

If you do not have CVS access and wish to submit changes, you can check out htdocs via anonymous CVS (see the NetBSD CVS HOWTO). The best approach is usually to:

1. Checkout the htdocs module
   'cvs checkout htdocs'
2. Edit the desired file. Most FAQ-style documents are generated from .list files, so it is best to check before editing.
3. Run 'make' if you have edited .list or similar files.
4. Validate the HTML. (Repeat these three steps as necessary).
5. Submit a diff to <www@NetBSD.org> using cvs diff, eg.
   'cvs diff -u htdocs/path/to/file.list'

You should run make before committing. You will need perl5 installed.

Compulsory tags  <LIST>: Include generated list of entries here. <SECTION>Text: Introduces new section, before DATE or ENTRY </LIST>: Tag for end of all special entries   Optional tags  <DATE>tag date Text: Changes entry, expanded to title & added to list <ENTRY>tag Text: Text expanded to entry title and added to list <LISTLINK>url Text: Link added to TOC, removed from main text <ENTRYLINK>url Text: Link added to list and main text <HEADING>Text: Standard heading at top of document <DEVHEADING>Text: Standard heading at top of developer docs <TROW>Text: Text: Table row, with two text fields - Note: <TROW> will automatically continue until a line containing </table> <HOMELINK>: Standard flag link to home page at base of document <DOCLINK>: Standard flag links to home page and Documentation top level at base of document <DEVLINK>: Standard flag links to home page and Developers Documentation at base of document <PORTLINK>: Standard flag links to home page and Supported Architectures top level at base of document <GALLINK>: Standard flag links to home page and Gallery page at base of document   Additional pattern matches  man pages: ([a-zA-Z_][-\w.+]*[\w+])\((\d)(|\.(\w+))(|\+(\W+))\) eg: ls(1) Note: Can also handle specific architectures and collections eg: (8.pmax), (8+1.4.3), (8.pmax+1.4.3) Default collection is NetBSD-current. Available collections are: "1.3.3", "1.4.3", "1.5", "1.5.1", "current". email addresses: <([-\w.]+@[-\w.]+)> eg: <abs@NetBSD.org> pkgsrc references: <PKGSRC>((\w+/|)([^\s<>]+\w)) eg: vilearn -current source: <CURRENTSRC>(path) eg: Makefile Note: Works with files or directories literal URLs: <URL>(url) eg: http://www.NetBSD.org/ RFCs: <RFC>([^\s<>]+\w) eg: RFC2795

Processing .xml (docbook-website) files (top)

In order to build .html files from .xml files, you will need at least libxslt and docbook-website installed. These are installed as part of netbsd-www

To regenerate, cd to htdocs/ and run
'make ./autolayout.xml'.
Then run make in the target directory.

Renaming or moving files (top)

In order to move or rename files within htdocs, the following procedure is recommended:

• copy the file from the original location to new location
• modify html of the original file:
  • include a <META HTTP-EQUIV=Refresh CONTENT="5; URL=new-location"> tag in the header
  • remove all content except the header and the footer
  • add a sentence saying that the page moved and hyperlink it to the new location
• cvs add the new file
• cvs commit the new file and the changes of the old file at the same time, so we have some cvs reference of when and why things moved

What is the reasoning behind the flag links with empty.gif? (top)

Each NetBSD 'flag' links at the base of each page has:

• href containing netbsd-banner with no alt tag
• href containing empty gif with "NetBSD" alt tag and the words "Home Page"

This has the effect of:

• Making the "NetBSD Home Page" link a single link in lynx, i.e. not a NetBSD link and a Home Page link.
• In netscape, causing the additional text to be centered and aligned "better" w.r.t the graphic. Without it, at least in netscape, they show up at the bottom not centered vertically, and abut the graphic (or, if you include spaces, include nasty underlined blanks which looks broken to me).

It's a grotty hack, but it makes things look right.

How do the pages get to the web server, and when? (top)

The NetBSD webpages are stored in CVS in the "htdocs" repository. For security reasons, the htdocs repository is copied (via rsync) to www.NetBSD.org each hour, and the a local checkout is done from that copy of the repository. The checked out tree can be found in "/NetBSD-www". The repository is updated and checked out every hour, about 40 minutes after the full hour (*:40). If you make a commit to htdocs, it will take up to an hour before the changes show up.

Note that there are several files like the Gnats database (http://www.NetBSD.org/Gnats/), the pkgsrc and source changes in Changes/changes*.html and Changes/pkg-changes*.html, the RSS files in Changes/rss-*.xml etc. that are not part of htdocs but that get generated by various scripts out of cron jobs directly on the web server. Check out "htutils/changes/*" to get access to the scripts.

Adding to specific areas

Adding to the 'Sites running NetBSD' gallery (top)

If you have a NETBSD GALLERY ADDITION email from the htdocs/gallery/addsite.html page:

1. Ensure you have perl installed
2. Save the message in your copy/paste buffer
3. cd htdocs/gallery
4. ./addsite.pl, paste the buffer, add a ^D, and answer 'y' if it parsed OK.
5. cvs commit

Alternatively you can manually edit htdocs/gallery/sites.data, and run make.

Adding news items (top)

Most news items go into htdocs/Changes/index.list (see note on .list files). Changes affecting a specific port should also be linked to from their htdocs/Port/*/ news section.

Important code news items should also be noted in the text doc/CHANGES file.

Quick ``howto'' for the impatient (but please do read on for details):

• cd htdocs/Changes
• make update
• ${EDITOR} index.list
• make
• make MSG="I added important NEWS!" commit

Before you do anything with htdocs:

1. Ensure you have perl installed for the .list files.
2. Check out htdocs from the CVS repository.
3. If you already have a copy of htdocs in your tree, make sure you update it regularly. In particular, when adding news items, make sure that gallery/events.* is up to date as well, as the events are pulled in from there!

To add a change entry:

1. Edit htdocs/Changes/index.list and search for the first line starting <DATE>.
2. Insert a new line of the form
   <DATE>tag date - title
   where
   • tag - A lowercase/number/hyphen identifier. eg: 'new-xx-driver'
   • date - In the form DAY MONTH YEAR. eg: '23 Jan 1999'
   • title - Freeform text for the entry title - can use \ to escape the end of line.
3. Add the body of the item. manual pages (eg: ls(1)), and email addresses (eg: <user@domain>) will be automatically expanded. Feel free to use HTML tags, though this is not compulsory.
4. Run 'make'

Adding links from the main pages:

By running make from within htdocs/Changes, you will automatically update htdocs/index.html and the index pages of all supported translations. No further action on your part is required.

Alternatively, you can run make index from the htdocs toplevel directory.

If you want to add a link from a port specific page:

1. Edit htdocs/Ports/arch/index.html, and search for the '<!-- news -->' block.
2. Add a new entry to the subsequent list in the form:

   <dt><b>date:</b> title
       <dd>body of item
       <p>

   where
   • date - Normally as YEAR.MONTH.DATE
   • title - Freeform (short) text title
   • body of item - Freeform text for the entry. Can span mutltiple lines and may use HTML tags and links.

Finally:

1. You may want to validate the HTML in your modified files.
2. Check in the files - do not forget any .list files will update the matching .html. The command 'make commit', when issued from the htdocs toplevel directory, will commit the main index-page, Changes/index.* and all the translations index pages with a default message of "NEWS; regen". If you would like to add a more specific message, use 'MSG="Added News regarding FooBar" make commit'.
3. If the news is noteworthy it is a good idea to submit it to some news sites, like Daily Daemonnews, OSNews, Slashdot, Newsforge and BSDForums.

Adding Events (top)

The main index page also contains links to "Upcoming Events". These links are updated much like the News entries:

• cd .../htdocs/gallery
• $EDITOR events.list
• make events

Since the events are included on all the translations index pages, all these pages need to be generated and committed as well. This can be achieved by issuing the 'make index' command from the htdocs directory.

• cd .../htdocs
• make index
• MSG="Added Event Foo" make commit

Adding to/editing the MailingLists page (top)

If a mailing-list is missing from the MailingLists page:

1. Edit the htdocs/MailingLists/index.m4 file
2. Run the makefile in htdocs/MailingLists, it will generate the index.html
3. Confirm the generated html is good.
4. commit the index.m4 and index.html files.

Consultants for hire (top)

Before adding an entry to the ``Consultants for hire'' page (gallery/consultants.html), please ask that the person in question provides a link back to our homepage and/or mentions NetBSD on their website. Needless to say that you should make sure that the URL given is active and accessible.

Home Page

Developer Documentation