The GNU/FSF Web Site Guidelines

(xbm 5k)

These are style guidelines for writing WWW web pages in HTML for the GNU/FSF web server.

Table of Contents

• Copyright Guidelines
• General Guidelines
• Filename and URL Guidelines
• HTML Guidelines
• Use of Graphics
• Useful Resources

Copyright Guidelines

• Every page should have a Copyright notice.

• The default is what's at the bottom of boilerplate.html.

• If the page is copyrighted by someone else, make sure their Copyright notice is on the page. Replace the default FSF Copyright notice at the bottom of the page with this:

  Copyright notice above.
  Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA

  The reason to note this at the bottom is so the user finds the copyright information at the same place on each page.

• If the source text for a set of pages is copyrighted by someone else, (i.e. you split a document into more than one page) make sure their Copyright notice is at the bottom of each page, where the default FSF Copyright notice would otherwise be.

  On the page containing their Copyright notice, you can replace the default FSF Copyright notice at the bottom of the page with this:

  Copyright notice above.
  Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA

  The reason to note this at the bottom is so the user finds the copyright information at the same place on each page.

General Guidelines

• Remember, its GNU to have fun along the way!

• Good spelling is encouraged. Use the GNU Emacs ispell-mode if in doubt.

• The FSF will install only free software on the GNU/FSF web server. We prefer that only free software be used to develop content for the GNU/FSF web server.

• The GNU/FSF web server only lists and links only to free software. The software's source code and executables have to be freely redistributable and modifiable to and by all people, companies, and organizations. If in doubt, ask <gnu@gnu.org>.

• The GNU/FSF web server gives priority to software covered by either the GNU General Public License or GNU Library General Public License, which is always listed first.

• The GNU/FSF web server is interested first in content. Substance is more important than style. The use of graphics should be minimized, so pages load fast over slow links. The GNU Project is for everyone, even those with slow Internet access and/or text-only WWW browsers.

• We like to leverage the work that GNU volunteers have done at their own web sites as much as possible. There's no need to write an article from scratch if someone has already written something suitable. But often we want to adapt and modify the text. Therefore, we generally copy the articles we really care about onto our server, rather than making links to them.

• Often a page will start off with some links, then have the GNU/FSF text. The goal is to get each user quickly to what they want to find out, having most of the info on the first screen. This is similar to having the start of a Menu within the first 24 lines of an Info page.

• Offer a document in as many formats as the GNU Project has it. For an example, see http://www.gnu.org/prep/tasks_toc.html. This lets the user get the document in the format most useful to him.

• Before you take any graphics or text from another Web site, please ask for permission to use it. It's polite to do so. It is also essential for us to avoid copyright infringement.

• Do not list an address of an individual, especially the maintainer of a GNU package, unless the maintainer has explicitly asked to have it listed. Most GNU maintainers do not want a lot of extra mail and prefer to get bug reports, etc. from the GNU bug report mailing lists (50k characters).

Filename and URL Guidelines

• Hand-written URLs which refer to other files should be absolute, starting from the root page. That is, file names should start with "/" (e.g. "/order/order.html", but not "http://www.gnu.org/"). This makes it easier to copy and paste "<A HREF="s from other pages, and also makes it easier to set up mirror servers.

• However, it is ok to omit the file name entirely when referring to a tag in the same file.

• When the link points to another page on the GNU/FSF server, omit the word "http:" at the beginning. In other words, use "http:" only before a host name.

• Collections of files produced automatically from Texinfo source contain links with relative file names. They always refer to another file in the same directory. These links are ok.

• Some people believe that mirror sites cannot easily handle absolute file names in links; they think our use of them requires a mirror site to place the mirrored GNU pages at the web root, so that the site could not contain anything but the GNU pages.

  Actually, that is not so; many web servers, including the free Roxen and Apache support multiple ``virtual servers'', each of which can use a different subdirectory as the virtual root.

• Always put the URL in a link in quotes. The reason is that some browsers don't handle unquoted URLs properly (see section 3.2.4 of RFC 1866 (147k characters) as to why this is). For example, use:

  <A HREF="/boilerplate.html">boilerplate.html</A>
         

  or

   <A HREF="http://lpf.ai.mit.edu/">the LPF site</A>
         

  or

  <A HREF="/server/fsf-html-style-sheet.html#TOCFilenameAndURLGuidelines"
     NAME="FilenameAndURLGuidelines">Filename and URL Guidelines</A>
         

• To make it easier to edit many files at once in Emacs:
  • Try and give each html file a unique name.

  • The filename index.html should only be used as a symbolic link.

• Each directory, in the web server tree, should have a index.html symbolic link to the top-level html file for that directory.

• Don't use just a directory name in a URL; always include the specific file name. E.g. use "/gnu/gnu-history.html" not just "/gnu/". And never use "index.html" in a URL. Both of these are kindnesses to the users, as browsers change the highlighting on a link, if a user has already seen it. If the link is known by several different file names, the user will not get a highlighted link on the file names the user hasn't explicitly referenced. So the user goes to pages the user has already seen, which is irritating.

HTML Guidelines

• Keep the HTML simple. The more complex the HTML, the more limited the access, as it will not format properly in many browsers. Our goal is to get information to people. Keeping the HTML and site design simple helps accomplish that.

• HTML on the GNU/FSF web server should be conservative. HTML 2.0 (147k characters) is good enough. HTML 1.0 is acceptable. We don't want to experiment with the latest features of any browser on the GNU/FSF web server. It is important that the pages on the GNU/FSF web server, display well on all browsers that implement no more than HTML 2.0.

  We support the Best Viewed with Any Browser campaign.

• Check pages after you change them with tools like htmlchek (installed in /usr/local/bin on www.gnu.org), and weblint. This will catch errors that will confuse users, before they are seen.

• Test view pages under many browsers, both text-only and full graphics, and older versions of each browser as well. This helps make sure the pages present well under all browsers, and prevent HTML design that looks great under one version of one browser, and ugly under many others. For example, test view under:
  • Lynx
  • GNU Emacs' w3-mode
  • Arena
  • Hot Java
  • Mosaic 2 and 2.75b
  • Netscape 3, 4, and 5
  • Internet Explorer, including the the AOL web browser, which is a special version of Internet Explorer (around 10 million users have AOL web browser as their only browser)

• All pages should have <HTML> <HEAD> <TITLE> <BODY> pairs (see file boilerplate.html). This makes up for overly pedantic browsers.

• All pages should have contact info for both the FSF (or responsible party) and the webmasters at the bottom of each page. The default is what's at the bottom of boilerplate.html. The reason to note this at the bottom is so the user always finds this contact information at the same place on each page.

• The first header tag, <Hn>, should have its text duplicated at the start of the <TITLE> tag. The <TITLE> tag is used by many browsers in menus like the history and bookmarks lists, as a link to that page. Its helps the user to have them the same, so when he clicks on an item in a list, he gets a page with the same "title".

• The <TITLE> tag should include the phrases "GNU Project" and "Free Software Foundation (FSF)" so the pages will be found when WWW search engines are used. The default is to add this at the end: " - GNU Project - Free Software Foundation (FSF)".

• The <HEAD> pair should have this line after the <TITLE> pair:
  <LINK REV="made" HREF="mailto:webmasters@www.gnu.org">
  Some browsers use this information to allow users to easily report problems they find on a page.

• On pages with dated entries (e.g. What's New, Thank GNUs, and GNU's Bulletins, the newer entries should be first (i.e reverse chronological order).

• If a link is to a page with more than 10,000 characters on it, warn the reader of this fact by listing the size at the end of the link. For example:
  <A HREF="/server/fsf-html-style-sheet.html">style guidelines (12k characters)</A>
  This is so the user is warned that the transfer will take a longer than expected time.

• Cite people with e-mail addresses this way:

  <A HREF="http://www.gnu.org/people/rms.html">Richard Stallman</A>
  <A HREF="mailto:rms@gnu.org">&lt;rms@gnu.org&gt;</A>
         

  which browsers display this way:

  Richard Stallman <rms@gnu.org>

  It is less confusing to the user, because it's clear what is a http: link to another WWW page and what is a mailto: anchor that will bring up a mail form to fill out and send.

  Also, if the user saves a copy of the page, he will have a copy of the e-mail address he can use, without going back to his web broswer.

  If the person doesn't have a web page, use:

  Richard Stallman
  <A HREF="mailto:rms@gnu.org">&lt;rms@gnu.org&gt;</A>
         

  which browsers display this way:

  Richard Stallman <rms@gnu.org>

• Cite FTP locations of source code with the full URL of the directory they are in:

  <A HREF="ftp://ftp.gnu.org/pub/gnu/standards/">ftp://ftp.gnu.org/pub/gnu/standards/</A>
         

  which browsers display this way:

  ftp://ftp.gnu.org/pub/gnu/standards/

  It is less confusing to the user, because it's clear that it's source code to download, not a http: link to another WWW page.

  Also, if the user saves a copy of the page, he will have a copy of the FTP location he can use, without going back to his web broswer.

  We encourage FTP sites to use a directory for each package, and only put one package's files in each directory, so that the users can see what versions of that package and related information can be downloaded (e.g. a ReadMe file, information of what versions are available, documentations, fonts, etc.).

  Also, it means that the FTP location URLs do not need to be changed, on this and other sites, as new versions are released into that directory.

  Here is an example:

  You can download the sources for the GNU Coding Standards from directory ftp://ftp.gnu.org/pub/gnu/standards/ or from a GNU FTP Mirror Site.

• There is no reliable way to make a non-breaking space in HTML. Despite the standard, many browsers out there don't understand &nbsp;. Some browsers (such as DosLynx) use the Operating System current codepage so even if you use &#160; -- the ISO Latin-1 code -- if still won't look right.

• Some browsers can only change the foreground color, while others can only change the background. So leave the foreground black, but specify it as black (see below). If you want to use different colors, alter only the background color. This is especially important if you are using tables (but as tables are not HTML 2.0, and produce confusing, hard to understand pages under many browsers, it's best to stay away from them).

• If you specify any color attribute, you should specify all of them that are allowed for that tag. This is because some browsers allow users to specify defaults for the color attributes, and the user's choices could conflict with your choices, as your choices override the user's choices. In the worse case, the foreground and background could end up the same.

  For example, for the <BODY tag specify all these attributes: BGCOLOR, TEXT, LINK, ALINK, and VLINK.

Use of Graphics

• The use of graphics should be minimized, so pages load fast over slow links. The GNU Project is for everyone, even those with slow Internet access and/or text-only WWW browsers. The use of graphics on the LPF site is a good example. Note how they provide a small thumbnail to display on their pages, but also offer larger sizes and alternative formats through HTML links.

• Due to the patent problem with GIFs, all in-line images should be in JPEG format with a pointer to our page on the GIF problem http://www.gnu.org/philosophy/gif.html. Other formats are also allowed, though JPEG is the one most widely recognized by Web browsers.

• Before you take any graphics or text from another Web site, please ask for permission to use it. It's polite to do so. It is also essential for us to avoid copyright infringement.

• Whenever you add a graphic to this site's web pages, please:
  • locate the graphic file in the '/graphics/' subdirectory.

  • add another link to it on the GNU graphics (500k) page. This is so it's easy for visitors to the site to find all the graphics on the site in one place.

• Tag all images like this:
  (xbm 5k) no gifs due to patent problems
  This is so the user knows how big and what format the image is, if the user wishes to separately down load it. If several sizes and/or formats are available, just add more (Nk format) pairs. See http://lpf.ai.mit.edu/ or the GNU Graphics (500k) page for examples.

• Always have a textual alternative for in-line images:
  <IMG SRC="/graphics/*.jpg" ALT=" [Image of DESCRIPTIVE TEXT] ">.
  The FSF wants users who have text-only access to the Web to be treated as well as those who have both text and graphic access.
  We add the spaces and square brackets to separate the DESCRIPTIVE TEXT from adjacent text, and help the user realize that this is a stand-in for a graphic.

• Always have WIDTH and HEIGHT attributes for in-line images:
  <IMG SRC="/graphics/*.jpg" ALT=" [Image of DESCRIPTIVE TEXT] " WIDTH="999" HEIGHT="666">.
  This improves the performance of some browsers.

• We do not use backgrounds on our pages, as they make text significantly harder to read. Improving readability is also the reason we specify black text on a white background in the <BODY tags on our pages.

Useful Resources

• Appendix B Tips and Hints, and other style tips in the Texinfo Manual.

• We follow the guidelines of Best Viewed with Any Browser campaign.

• Basic info on the WWW and its technical specifications can be found at The World Wide Web.

• Basic info on HTML can be found at Hypertext Markup Language (HTML).

• The GNU/FSF web server follows the reasonable parts of the w3.org Style Guide.

FSF & GNU inquiries & questions to gnu@gnu.org. Other ways to contact the FSF.

Comments on these web pages to webmasters@www.gnu.org, send other questions to gnu@gnu.org.

Copyright (C) 1996, 1997, 1998 Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Updated: 11 Aug 1998 kwzh