Editing htdocs

General notes on htdocs

Who can edit htdocs

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'.

Users without CVS commit access are encouraged to check out htdocs via anoncvs, and mail patches to www@NetBSD.org; see below.

What is required to edit htdocs

Read the CVS introduction.
Install meta-pkgs/netbsd-www, which provides the tools required to build the web site. Please note that any special LOCALBASE or PKG_SYSCONFBASE settings in /etc/mk.conf should not be protected by BSD_PKG_MK as their values are used by the htdocs makefiles.
Also install meta-pkgs/netbsd-doc-print to regenerate The NetBSD guide and some other pages which depend on the guide.
Set your CVSROOT as indicated and run
```
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

After making any changes you should run your html through an HTML validator such as http://validator.w3.org/. The URL for a link to an index.html file should not include the trailing index.html.

NetBSD.org naming scheme

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

Converting to XML

In order to facilitate global changes, we are currently converting the NetBSD website to XML (docbook-website). As of 2004-11-15, any non-XML file that needs to be edited shall be converted to XML at the same time. You may find the script htdocs/scripts/list2xml helpful to initiate the conversion of plain .html files. Please note, however, that this script only does a few simple replacements of tags, and you will need to do a lot by hand after running it. In particular, you need to make sure that all tags are closed in the proper order.

When creating or converting .xml files, please make sure to add a “id” attribute to each <sect[1-4]> as well as each <table> tag: this will prevent xsltproc to generate an ID itself, which would require an update of the resulting .html file after each regeneration. Also remember to replace each “&” with “&” and /sys with /usr/src/sys where applicable.

If you are unsure how to convert a given HTML tag to the XML equivalent, you may find some useful examples installed as part of the textproc/docbook-website on your system. And of course you can ask on the www@ list for help.

If you want an autogenerated TOC, you will need to include the following code:

<sect1 role="toc">

This will generate a TOC listing all <sect2>s with a bulleted list of its <sect3>s.

After converting a file to XML, remember to add it to the htdocs/layout.xml file and regenerate the website. See below for details.

Processing .xml (docbook-website) files

In order to build .html files from .xml files, you need meta-pkgs/netbsd-www, at least version 1.10.

To regenerate, just run make in the target directory.

If you added a new file to layout.xml, then you do need to run make in the htdocs top level.

Renaming or moving files

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

copy the file from the original location to new location
cvs add the new file and cvs rm the old file
adjust htdocs/layout.xml
cvs commit the new file and 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?

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. It's a grotty hack, but it makes things look right.

XML template files

There are a few template files in htutils/templates to get you started with XML. Please compare to existing pages in use when you add new content.

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

The NetBSD webpages are stored in CVS in the "htdocs" repository. mollari updates the website from CVS in the live website under “/u0/www”. -->The script performing this functionality is htutils/scripts/update.http and it is run 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.

How is the whole web site structured?

What are the individual files for?

Makefile: Contains a description of the directory's contents. Usually it suffers to define the variables SUBDIR and XMLDOCS, and then .include the file htdocs/share/mk/web.site.mk using the appropriate relative path. The files in the share/mk contain large comments at the top that describe what you can do in the Makefile.
*.xml: XML files contain the source code for a single HTML page, in the “DocBook Website” format.

Adding to specific areas

Adding to the “NetBSD in action” gallery

If possible, a screenshot should contain some easily recognizable visual indication that it was made on a NetBSD system. A common way to do this is by showing an X terminal that displays the output of uname -a.

Adding News Items

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

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

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

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

Before you do anything with htdocs:

Ensure you have meta-pkgs/netbsd-www installed. Also, see above.
Check out htdocs from the CVS repository.
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! This is best done by running
```
  $ cd htdocs
  $ make update
```

To add a change entry:

Edit htdocs/changes/index.xml.

In the right section, add the entry of the form

  <sect3 id="link-name>
  <title>XX Mon XXX - FREEFORM TITLE</title>
  <para>
    Entry text goes here.  Manual pages can be referred to as “&man.command.X;”,
    email addresses as <email>full@address</email>.
  <para>
  </sect3>

Run make.

Adding links from the main pages:

By running make from within htdocs/changes, you will automatically update htdocs/index.html. No further action on your part is required.

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

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

Edit htdocs/ports/arch/index.html, and search for the '' block.
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 multiple lines and may use HTML tags and links.

Finally:

You may want to validate the HTML in your modified files.
Check in the files. The command make commit, when issued from the htdocs toplevel directory, will commit the main index-page 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.
If the news is noteworthy it is a good idea to submit it to some news sites, like Daily Daemonnews, OSNews, Slashdot and BSDForums.

Adding Events

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

cd .../htdocs/gallery
$EDITOR events.xml
make events.html

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

Adding to/editing the MailingLists page

If a mailing list is missing from the MailingLists page:

Edit the htdocs/mailinglists/index.xml and htdocs/mailinglists/list2group.xsl files.
Run the makefile in htdocs/mailinglists, it will generate the index.html.
Confirm the generated html is good.
Commit the index.xml and list2group.xsl files.
Regenerate the index.html file to include the proper "generated from" statement.
Commit the generated index.html file.

Consultants for hire

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.