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

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 (top)

Read the CVS introduction.
Install meta-pkgs/netbsd-www, which provides the tools required to build the web site. Please make sure that you have at least textproc/docbook-xsl >= 1.68.1 and textproc/docbook-website >= 2.6.0nb1 (automatically required by meta-pkgs/netbsd-www 1.4, but earlier versions accepted earlier revisions of required tools, which may not be appropriate). 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 (top)

After making any changes you should run your html through an HTML verifier such as www/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 (Netbsd.org, netbsd.org, ...) in links, mailto's, or other pointers.

What are .list files? (top)

The .list files are obsolete!
You should convert any existing .list files to XML. Please see this section for details.

Converting to XML (top)

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 the old .list as well as 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 feel free to 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 (top)

In order to build .html files from .xml files, you will need at least textproc/libxslt and textproc/docbook-website installed. These are installed as part of meta-pkgs/netbsd-www. Please make sure that you have meta-pkgs/netbsd-www version 1.4.

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 (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
cvs add the new file and cvs rm the old file
add a note to htdocs/errors/index.xml, linking to the new location
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? (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).

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

XML template files (top)

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? (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 then a local checkout is done from that copy of the repository. 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?

Overview (top)

What are the individual directories for? (top)

share/mk: Contains the make(1) infrastructure to automatize the generation of the web pages from the source files.
share/xml: [TODO]
share/xsl: [TODO]

What are the individual files for? (top)

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.
layout.xml: [TODO]
autolayout.xml: [TODO]

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:

Verify that the remote site has a link back to www.NetBSD.org. If they do not link back, contact them to ask for a link back and add the information once the link is provided.
Ensure you have perl installed.
Save the message in your copy/paste buffer.
cd htdocs/gallery.
./addsite.pl, paste the buffer, add a ^D, and answer y if it parsed OK.
cvs commit.

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

Adding to the “NetBSD in action” gallery (top)

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 (top)

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, 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.xml
make events.html

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

Adding to/editing the MailingLists page (top)

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