GNU Website Guidelines

Our goal is to get information to people. Keeping the site design simple helps accomplish that.

We want to share our ideas and web resources with the largest public, in the most efficient and professional way. Bookmark these guidelines for future reference, and don't hesitate to report oversights or outdated paragraphs.

[Skip the table of contents]

Table of Contents

General Guidelines

Please be considerate of all who access our web pages, and accommodate them, including those who use low-end hardware, as well as those with slow Internet connections. We wish to prevent web designs that look great under one version of one browser, and ugly under many others. Of course, please don't install any of the proprietary web browsers available if you don't already use them anyway. This website keeps the ideas of a community: before updating or publishing a page, don't forget to consult these guidelines and your peers.

GNU Policies

  • The GNU web server has only free software available. We prefer that only free software be used to prepare pages for the GNU web server.
  • The GNU website 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 and organizations. If in doubt, ask <gnu@gnu.org>.
  • The GNU website gives priority to software covered by either the GNU General Public License or the GNU Lesser General Public License.
  • Before you take any graphics or text from another website, please ask for permission to use it. It's polite to do so. It is also essential for us to avoid copyright infringement.
  • Before adding a link, check that it follows our linking criteria.
  • Do not list an address of an individual, including the maintainer of a GNU package, unless explicitly asked to have it listed. Most GNU maintainers do not want a lot of extra mail and prefer to get bug reports and other messages from the relevant mailing lists.
  • Pages should not load CSS from servers other than those run by the FSF.
  • Generally, the use of JavaScript is not allowed. Exceptions to this need to be reviewed and approved by the Chief GNUisance on a case-by-case basis.

Copyright Guidelines

  • Every page should have a copyright notice listing the copyright holder(s) and copyright year(s).
  • Every page should have a notice giving everyone permission to distribute it. If you cannot get such a permission from the author, please discuss the issue with the webmasters before posting it. This applies to CSS as well as to HTML.
  • Normally you shouldn't post a page that isn't copyright FSF unless we have permission to modify the version we publish. If you cannot get such a permission from the author, please discuss the issue with the FSF before posting it. This applies to CSS as well as to HTML.
  • If ultimately we decide to post a new page we don't have permission to modify, put the text “Posted in 20XX without FSF permission to modify” inside an HTML comment, just after the copyright notice.
  • All pages that explain how to do something, such as how to use certain programs, are documentation. This includes all the pages in /software/ that describe specific programs. By our principles, documentation must be free. So these pages must carry a free license. If such a page doesn't have a free license, please report the problem to <webmasters@gnu.org>.
  • For other pages, use the same license as some other page that serves a similar kind of purpose.

Web and accessibility standards

  • All public pages of the GNU website should be strictly compliant with W3C Recommendations (REC), as opposed to Working Drafts (WD), Candidate Recommendations (CR), Proposed Recommendations (PR) or Retired Recommendations (RET).
  • HTML 5 and CSS3 are target for upgrade from older standards.
  • Regardless of the web standards used, all pages should meet the Web Content Accessibility Guidelines (WCAG).

Creating a New Page

Naming the file

  • To make simultaneous edition of many files easier, try and give each HTML file a unique and descriptive name; the special filename index.html should only be used as a symbolic link, as explained next.
  • Each directory in the web server tree should have a symbolic link named index.html to the top-level HTML file for that directory. Use the .symlinks file to handle this.
  • If you translate your web page (say, page.html) in different languages, please name the translations page.lang.html— lang should contain the relevant two-letter code from ISO 639-1, and optionally a hyphen followed by the two-letter Alpha-2 country code from ISO 3166-1 (converted to lowercase). For example, the German translation of not-ipr.html should be named not-ipr.de.html; the Brazilian Portuguese translation should be named not-ipr.pt-br.html.

Doctype and required HTML elements

  • Please follow the above mentioned web standards strictly, even when you are forced to follow superseded W3C recommendations: don't neglect required elements such as <html>, <head>, <title> and <body>, and always include the appropriate DTD or Schema reference in all markup standards older than HTML 5. This appeases overly pedantic web browsers.
  • Do not add <!-- comments --> at the top of a document. Old web browsers expect the doctype, XML declaration, or Schema to be at the top. Comments will confuse them, and often cause them to incorrectly interpret your markup.
    If you must add a comment before <!DOCTYPE html>, then use <!--[if !IE]> comments <![endif]-->.
  • The <head> element should contain this line:

    <link rel="author" href="mailto:webmasters@gnu.org">

    Some browsers use this information to allow users to easily report problems they find on a page.
  • The first header element, generally <h1> or <h2>, should have its text duplicated at the start of the <title> element. The latter is used by many browsers in menus like the history and bookmarks lists, as a link to that page. Repeating the main heading in the <title> ensures that, when users click on an item in these menus, they get a page with the expected heading. Please properly use your headers in numerical order: 1, 2, etc. These are not used for looks, but for the organization of the document.
  • The <title> element should include the phrases “GNU Project” and “Free Software Foundation” so the pages can be better indexed by external search engines. The default is to add this at the end: - GNU Project - Free Software Foundation.

Page footer

  • All pages should have a footer. See the boilerplate, referred below.
  • The footer should include the copyright and license notices for the page itself. The copyright and license notices for material that is part of the page (such as images) should normally be placed in the main text.
    The rules for listing copyright holders and years are detailed in the GNU Maintainers' guide.
  • The Copyright Infringement Notification is a legal requirement.
  • In addition, the footer should have contact info for both the FSF (or responsible party) and the address for bug reports (webmasters for general pages, but project-specific addresses otherwise). The reason to note this in the footer is so the user always finds this information at the same place on each page.

Using our page template

  • To help people follow the above guidelines, a page template (or “boilerplate”) is provided for both the main part of the GNU website, and the software projects. Its use is mandatory for new pages in www.gnu.org, and highly recommended for software pages. Please don't start out with an existing page to create a new one; use the original source of the boilerplate instead, and follow the instructions in it.
  • The templated pages must follow the XHTML-1.0 guidelines. Well-formedness is essential for translatable pages that need to be converted to POT files by the PO4A/Gettext tools.
  • Our SSIs declare UTF-8 as the character encoding; using any other encoding is problematic.
    See the Introduction to Apache SSIs to learn more on this topic.

Writing and Editing

Page contents

  • On pages with dated entries (e.g., /philosophy/latest-articles.html), the newer entries should be first; in other words, preserve reverse chronological order.
  • Offer a document in as many formats as the GNU Project has it. For an example, see The GNU Free Documentation License. This lets users get the document in the format most useful to them.

Spelling and punctuation

  • English pages should follow the standard American spelling, hyphenation and punctuation conventions.
  • Since these conventions are not always very specific, especially as regards hyphenation and quotes, gnu.org adds its own rules for the sake of consistency:
    • The term “nonfree” is preferred over “non-free”; likewise, “noncommercial” over “non-commercial.”
    • In ordinary text, HTML entities “&ldquo;…&rdquo;” and “&lsquo;…&rsquo;” are preferred over straight quotes ("..." and '...'). This doesn't apply to script-generated documents.
    • Where they exist, the double spaces after sentence breaks should be preserved. They enable Emacs sentence commands to do the right thing.

URLs - local links

  • Hand-written URLs that refer to other files on www.gnu.org should be absolute, starting from the root page. That is, paths should start with / (e.g., /gnu/about-gnu.html; not http://www.gnu.org/gnu/about-gnu.html nor https://gnu.org/gnu/about-gnu.html, and not about-gnu.html). This makes it easier to copy and paste links from other pages. Besides, links like http://www.gnu.org/ will be wrong when the visitor uses HTTPS.
  • 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 relative links are to be tolerated.
  • Don't use just a directory name in a URL; always include the specific filename. For instance, use /gnu/gnu.html, not just /gnu/. Never use index.html in a URL. Both of these are kindnesses to the user, as browsers change the highlighting on a link after it has been visited. If links to a given file use several different URLs, the URLs that haven't been explicitly referenced will not be highlighted as visited. So the user goes to pages he/she has already seen, which is irritating. Also, this eases maintenance of the site as things get moved around.
  • When embedding static resources like videos that are not in the www CVS repository along with the rest of the www.gnu.org pages, it's important that the URL used to embed the asset be a subdomain of gnu.org, so that the Third-party Request Blocker add-on shipped with GNU IceCat would not consider it a third-party asset which it would prevent from being loaded. For example, when embedding videos from FSF campaigns on www.gnu.org, use static.gnu.org rather than static.fsf.org. Both of these addresses have been set to point to the same machine, so they can be used interchangeably.

URLs - page anchors

  • Be sure to omit the filename entirely when linking to an anchor in the same file, and double-check that the anchor actually works.
  • Consider others linking to your page when either removing an element that carries an id attribute, or changing an id. Place the old one on a block element nearby. If there is no suitable element, add one. Here is an example from the Philosophy main page: 
    <!-- please leave both these ID attributes here. ... -->
[...]
<div id="TOCFreedomOrganizations">
<p id="FreedomOrganizations">We also keep a list of
<a href="/links/links.html#FreedomOrganizations">Organizations
that Work for Freedom in
Computer Development and Electronic Communications</a>.</p>
</div>
    Please avoid moving the old id to a translatable string, unless there is no other way to keep the markup valid. Translators will thank you!
  • Reminder:  before adding a link, check that it follows our linking criteria.
  • Check if the linked host supports HTTPS and always prefer HTTPS over HTTP when the former is supported and has a valid certificate (this is expressed by a locked/green lock on most web browsers).

URLs - email links

  • Place angle brackets around mailto: anchors (which will bring up a mail form to fill out and send, if the visitor has installed a standard email client) to clearly distinguish them from hypertextual anchors. See RFC 6068 for advanced examples of how to use mailto URIs to specify a subject, the body, etc.
  • When citing people, place the mailto: anchor next to their name, so that the email address is retained in printed copies of the page; for example,
    • If the person has a website: 
      <a href="https://www.stallman.org/">Richard Stallman</a>
<a href="mailto:rms@gnu.org">&lt;rms@gnu.org&gt;</a>

      … rendered like

      Richard Stallman <rms@gnu.org>

    • If the person doesn't have a website:

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

      … rendered like

      Richard Stallman <rms@gnu.org>

Acronyms and abbreviations

  • Never use <acronym>: HTML 5 obsoletes it in favor of <abbr>. The latter must be expanded in a title attribute.
  • When an abbreviation may be unfamiliar to a reader, give its expansion only the first time it is used in a document.
    Example: <abbr title="Expanded Abbreviation">EA</abbr> or EA (Expanded Abbreviation).
  • Make sure <abbr> is styled via CSS to meet the accessibility guidelines. By default some browsers render it in an ugly way.
  • For common-enough initialisms, such as GNU, FSF, BSD, RAM, HTML, DVD, and so on, no markup is needed at all. Use your judgment.

Tables and menus

  • Please use tables to organize data (data tables), not the presentation of the web page (layout tables).
    If you must use layout tables, be sure that the table makes sense when linearized, and has appropriately marked up headers.
  • Some people like to organize links as a menu to the left or right of the main text when using graphical browsers. That does not work very well with text browsers since they will make the menu appear either on top of the page or at the bottom. If you have a menu that is more than 30 lines long, then it's very probable that a user viewing the page will never bother to read the text because it will be too far down. You should make an effort to keep such menus under 20 lines long, so that the beginning of the article is visible on the first page when viewing it with a text browser. A menu bar of one or two horizontal lines might accomplish your purpose as well. Providing a “skip link” to the main text is another option (see the table of contents above for an example).

Styling

Styling of templated pages

  • Generic styling for desktops and smartphones is provided by layout.css; it covers most of our use cases.
  • Mobile devices with very limited resources use mini.css. This stylesheet is just the Yahoo User Interface (version 2) reset and base stylesheets, as these devices typically have minimal need for various fonts and no need for fancy layouts.
  • Printers use print.css. Note that the header, navigation bars and footer (except copyright and license) are unprintable.
  • In addition to layout.css, some pages have specialized stylesheets: graphics.css for the GNU Art section, and side-menu.css for the Malware and Education sections.
  • If some special styling is needed for a specific page, it should be added to the page itself in a <style> element, between the SSI directives that include header.html and banner.html. If the style applies to a single element, it should normally be added as an attribute.
  • If you specify any color attribute in the HTML, you should specify all of them that are allowed for that element. 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. Please use a stylesheet for this, and not HTML 3.2 (HTML 4 Transitional) deprecated markup.

Other stylesheets

  • Historical pages (unmaintained translations for the most part) refer to gnu.css, which in turn loads mini.css, as these pages are usually very basic, plain pages with little or no formatting.
  • There are dedicated stylesheets for software manuals. The main ones are:
  • Translators maintain stylesheets (/style.lang.css) that modify layout.css according to their own needs. The RTL languages (Arabic, Persian, and Hebrew) use style.rtl.css. Please don't forget to update style.rtl.css if you make LTR-specific changes to layout.css.

Text-only browsers

The text-only web browsers are a class of web browsers which can be executed in a terminal, without the benefits of a graphical environment. They represent the lightest kind of web browser and at their minimal can be viewed as a combination of less, wget, ncurses with a html-to-text transformation engine.

Even if the main web development target is composed by modern graphical browsers, browsability through terminal web browsers is an indication of good accessibility: they behave similarly to some accessibility tools and may not ignore CSS, trying to approximate the graphic render as much as possible. It isn't necessary to use dedicated stylesheets, because its always possible to safely insert conditional feature-sensitive or agent-sensitive blocks inside the existing ones, to hold the style fragments which should be rendered exclusively on the grid devices (the text terminals).

  • The webpages which are meaningful without media files (videos, graphics, photos, animations, etc.) may be tested on modern, stable text-only browsers and should be accessible by text-only users.
  • The subset of text-only browsers for compatibility testing is composed by stable and modern text mode browsers such as Lynx, Elinks and w3m, executed on the latest stable xterm, with at least support for 24-bit color, italic/bold fonts and UTF-8 enabled.
  • The CSS media queries can be used to detect graphical web browsers and their capabilities, but may be ignored (always return true) on text-only browsers.

    The correct way to prevent graphical browsers from parsing a CSS fragment dedicated to text-only browsers is:

    /* Discarded by GUI-based web browsers */
@media only screen and (grid: 1) {
    exp { prop: value; }
    …
}
    /* Not downloded by GUI-based web browsers */
@import url('tty.css') screen and (grid: 1);
/* or, alternatively: */
/* Not downloded by GUI-based web browsers */
@import "tty.css" screen and (grid: 1);

    …for in-page block embedding:

    <-- Discarded by GUI-based web browsers -->
<style media="only screen and (grid: 1)">
    exp { prop: value; }
    …
</style>
    <style … >
    /* Discarded by GUI-based web browsers */
    @media only screen and (grid: 1) {
        exp { prop: value; }
        …
    }
</style>

    …and for external resource (direct) inclusion:

    <!-- Not downloded by GUI-based web browsers -->
<link href="tty.css" rel="stylesheet" media="only screen and (grid: 1)">

    Always double-check the result on different web browsers.

To maximize compatibility, assume the terminal buffer has 80 to 132 columns with no word-wrap and unlimited rows. In each screen the user can "scroll" in various ways and the terminal can always display at least 23 lines; moreover, the user can instantly jump from one link to another and from one end of the page to another. In some particular cases forced word-wrap is advantageous and you can use use fold from the GNU coreutils to ease the task.

Use of Graphics

Caveats

  • The use of graphics should be minimized, so pages load fast over slow links, especially animations.
    Ideally, the average page loading time should remain under 3000 ms (with caching and proxying disabled). So, when it exceeds this limit, consider using lossless compression or smaller images. Modern web browser do implement network speed throttling as a development functionality, natively or via extensions; a local transparent HTTP/S proxy can serve the same purpose; the GNU/Linux kernel TC implements HTB, which can be used to create advanced testing environments with throttled network interfaces.
  • We do not use background images on our pages, as they make text significantly harder to read.
    If you are forced to add a background, ensure there is sufficient contrast with text, graphs, … and remember that CSS gradients may not be rendered by accessibility tools.
  • In the past, GIFs have had patent problems. However, now that the IBM and Unisys patents (and other patents worldwide that are relevant to LZW compression) have expired, GIFs that are based on the 87a or 89a standard are acceptable. Please be wary of proprietary applications that may include non-standard patented technologies (we'd prefer you use free software applications when authoring for our websites). In general, PNG or JPEG format are still safe, and are probably better from a technical standpoint. For details regarding the old GIF problem, see “Why There Are No GIF Files on GNU Web Pages”. Other formats are also allowed, though JPEG is the one most widely recognized by web browsers (avoid JPEG 2000, and be careful with PNG alpha channels; the former is not widely supported, and the latter are not fully supported by some older browsers).

Basic recommendations

  • All images that are not purely decorative should provide sufficient contrast between informative parts (text, graphs, etc.) and background.

  • Always have a textual alternative for in-line images, to ensure indexability by search engines and accessibility. For instance:

    Loaded in graphic browser:
     [DESCRIPTIVE TEXT] 

    Loading failed or text reader:
     [DESCRIPTIVE TEXT]  

    <img src="/graphics/gnu-post/Alternative-GNU-stamp.png"
     title="BRIEF TEXT"
     alt="&nbsp;[DESCRIPTIVE TEXT]&nbsp;">

    We add the non-breaking spaces (&nbsp;) and square brackets to separate the DESCRIPTIVE TEXT from adjacent text, and help the user realize that this is a stand-in for an image. The point of using non-breaking spaces rather than normal ones is to make sure they find their way to the translatable strings that are extracted by the PO4A/Gettext tools.

  • Check that the image doesn't look too big or too small when displayed at its original size, using the browser's default font size. If it is too big and you can't make a smaller version, adjust the size with the width and height attributes.
    Specifying both width and height will reserve the space required for the image during the page loading phase. Loading will thus be faster and smoother, especially on low-end machines with poor connectivity.
  • Also adjust image width or height in a style attribute, using scalable units such as em or %; for instance:
     [Stamp with an abstract GNU head]  
    <img src="/graphics/gnu-post/Alternative-GNU-stamp.png"
     title="GNU stamp"
     alt="&nbsp;[Stamp with an abstract GNU head]&nbsp;"
     style="width: 10em; height: auto; float: right; margin: .5em 0 .5em 1.5em"
     width="160px"
     height="160px" />

    This way, the page will look the same if the reader increases or decreases font size.
    Specifying both width and height will reserve the space required for the image during the page loading phase, preventing incremental layout reflows.

  • Link all images that are displayed throughout the website to the relevant page, usually in /graphics/. This will allow users to quickly go to pages related to the pictures they are interested in. See the next section for an example.

CSS classes for images

  • If you are adding a small floating image to a page that uses layout.css (the stylesheet for templated pages), you may want to use the imgright or imgleft class (defined in the IMAGES section of the stylesheet). This will ensure that the floating direction is reversed if the page is translated into an RTL language. Here is an example:

     [Stamp with a GNU head]  

    <p class="imgleft">
  <a href="/graphics/gnu-post/">
    <img src="/graphics/graphics/gnu-post/GNU-stamp.png"
         title="GNU stamp"
         alt="&nbsp;[Stamp with a GNU head]&nbsp;"
         style="width: 8em; height: auto"
         width="128px" height="128px" />
  </a>
</p>

  • If the image you are adding is 12em wide or more, and the page is templated, you may find it convenient to use one of the responsive pict classes that are defined in the IMAGES section of layout.css. You can adjust the width in a style attribute if none of the predefined ones fits your needs; for instance:

     [Stamp with a GNU head]  
    <div class="pict wide" style="width: 15em">
    <img src="/graphics/gnu-post/GNU-stamp.png"
         title="GNU stamp"
         alt="&nbsp;[Stamp with a GNU head]&nbsp;"
         width="225px" height="225px" />
</div>

    Please note that the container (div in this case) is necessary for retrocompatibility with some browsers which cannot apply max-width to images; in addition, be aware that a nested table may not inherit max-width on all web browsers (i.e., always test for compatibility when you need to put a table beside a picture).

  • graphics.css has some other layouts.

Linking Policies

One of the most complex aspects of maintaining web pages is following the linking guidelines; however, it's also a very crucial aspect of the job.

We strive to ensure that all pages we promote—all pages which are given links on our site—are friendly to the free software movement. Some pages will obviously not meet such standards; if the site flames the Free Software Foundation, or has no apparent relation to free software and surrounding issues, the link shouldn't be made. Beyond that, however, there are criteria used in determining whether or not it is appropriate to provide a link to a page from ours. They are listed below, in order of descending general importance.

What's the context of the link?

The link's purpose on our site will play a role in determining how strongly it should be judged against the other criteria. Pages hosting GNU projects will be held to the highest standards. Pages about other free software and given high promotion—for example, included in a newsfeed on the main page—are a close second. Links on the philosophy page may be given more leeway in talking about proprietary software; GNU/Linux user group pages should call the system GNU/Linux almost always but are hardly checked on other criteria. Always keep this in mind when deciding how to weigh each aspect of these policies.

Does the page promote proprietary software?

The big point made by the free software movement is that proprietary software presents an ethical dilemma: you cannot agree to such nonfree terms and treat those around you as you would like to be treated. When proprietary software is promoted, people get the impression that it is okay to use it, while we are trying to convince them otherwise. As such, we avoid offering such free advertising, either directly on our site or indirectly through links.

What's tricky about this criteria is the “promotion” point: there's a difference between mentioning proprietary software and making a sales pitch for it. Indeed, the GNU Project website mentions proprietary software throughout, but never gives people the impression that its use does not present ethical problems.

There are two things to keep in mind when determining whether a reference to proprietary software promotes it, or simply mentions it. First, how much information does it offer about the software? Second, how much information is the reader likely to actually gain from this page?

Different pages provide different amounts of information about proprietary software; the more it provides, the more of a problem it poses for us. For example, some pages may link to the primary site for a proprietary software program. Others may describe its functionality in detail. Even the product name given matters; there's a difference between “Windows” and “Microsoft Windows XP Home Edition.”

If the page requires nonfree, nontrivial JavaScript and has serious failures with JavaScript disabled, the link shouldn't be made. Similarly, if the page has embedded Flash that plays an important role, so that a person would be missing something important if the videos do not play, the link should not be made.

The subject of the reference will also play a role in determining how problematic a reference is. If the software is already very popular, it's unlikely that a basic mention of it will be news to the reader. Some examples of proprietary software which are common enough to be considered “well-known” are major operating systems (Windows, Mac OS, Sun OS, HP-UX) and primary common applications such as Office, Internet Explorer, Photoshop, Acrobat Reader, and Flash.

GNU software project pages feel the full force of this policy. Proprietary software should only be mentioned when the GNU software provides support for it, or to compare it against the features of well-known proprietary software. For example, the following text — and not much else — would be acceptable:

w3m is a text-only web browser which can be used from GNU Emacs via emacs-w3m, replacing proprietary web browsers like Internet Explorer. It can run on all platforms GNU Emacs runs on, including GNU/Linux, proprietary Unix systems, and Windows.

Links which appear in other areas, such as the testimonials or philosophy pages, as well as links to user groups may discuss such software in greater detail, but links and other methods of encouragement to “learn more” should still be avoided.

How does the page compare free software to open source?

Almost all pages which have links on our site should, at the very least, treat free software and open source equally. Failure to do so—whether it be by omitting free software or by implying that open source is superior—is usually unacceptable. GNU software project pages should have little mention of open source. The GNOME page used to provide a good example of a tactful way to do it:

GNOME is part of the GNU Project, and is free software (sometimes referred to as open source software).

Any exceptions to this rule should be apparent from the context. For instance, user groups pages may talk in greater detail about open source; we state on the user groups page, As with our links page, the FSF is not responsible for the contents of other websites, or how up-to-date their information is.

How does the page treat the GNU Project?

Pages which we link to should treat the GNU Project well. The primary thing to look out for in this regard is whether the page calls the system GNU/Linux or just “Linux”. GNU software project and user group pages should almost never, if ever, fail to do this. Again, exceptions for other pages should be apparent from context.

That said, certain parts of a page should not be considered against these criteria. For example, suppose we were to make a link to a page on a free software news site. Any advertisements or reader comments attached to the article would not be considered when determining whether it met or linking guidelines, since they're understood to be the opinion of their individual authors. Similarly, on user group pages, the contents of forums and wiki pages should not hold weight in these regards.

Finally, some sites are understood to always have exception with most of these guidelines. These sites are usually about issues which are important, but somewhat peripheral, to the free software movement. Several times we have linked to the Electronic Frontier Foundation's site, even though they encourage the use of Flash and talked exclusively about open source software. It's generally understood that since these pages are not primarily about free software, the policies do not hold full force for them.

As a final explanation:

Even for making links from www.gnu.org, we do not require that people call the system GNU/Linux or use the term “free software” rather than “open source”. We do, however, require that they not promote any nonfree software. — RMS

If all this seems complicated, that's because, unfortunately, it is. Don't worry; a knack for it comes with time and experience. You may mis-evaluate a few pages as you're learning to get a feel for what's acceptable and what isn't; please don't hesitate to get a second opinion from a more experienced webmaster, or someone in charge like the Chief Webmaster or RMS. New exceptions will always come up; keep an open mind to that possibility and be ready to handle them properly.

Technical tips

Basic CVS commands

  • For the offline reference manual, execute info cvs.
  • Before the initial checkout, set the environment variable CVS_RSH=ssh.
    Alternatively, you can replace :ext: with :extssh: to use an external ssh program.

  • If you have write access to the main repository of www.gnu.org, check it out with your Savannah login username:

    cvs -z3 -d:ext:username@cvs.savannah.gnu.org:/web/www co www

    You will get a working directory, www, with the same structure as our main website.

  • If you don't have write access to the main repository, you can still check it out anonymously:

    cvs -z3 -d:pserver:anonymous@cvs.savannah.gnu.org:/web/www co www

  • Check out the web repository of the fooproject:

    cvs -z3 -d:ext:username@cvs.savannah.gnu.org:/web/fooproject \
         co fooproject

    You will get a working directory, fooproject, with the same structure as the www/software/fooproject subdirectory. Note, however, that the fooproject and main repositories are independent, so the working directories can be anywhere in your filesystem.

    Webmasters, please read Web pages for official GNU software before committing anything to the web repository of a software project.

  • Add a file or directory:

    cvs add foo

  • Update before you edit a file:

    cvs update -P foo

  • Check the changes you are going to commit:

    cvs diff -U2 foo

  • Perform the commit (no need for cvs add if the file is already in the repository):

    cvs commit foo

    This will open a text editor where you should enter a log message. The commit will occur upon saving the message.

    Without being excessively verbose, log messages should describe as clearly as possible the nature of the commit, including any related ticket numbers from RT to allow future historians to understand why your changes were made.

    Whenever possible, changes to multiple files that share the same log message should be bundled in one commit. Do not bundle multiple unrelated changes in one commit.

    The changes (except to .symlinks files) should be visible on www.gnu.org within minutes.

For further details on CVS, such as reverting to a previous version, or looking at the diff output of a particular change, see the CVS documentation.

Since CVS is not able to handle symbolic links directly, a separate mechanism has been implemented to allow webmasters to maintain symbolic links, as follows. (Actual symbolic links are no longer created on www.gnu.org; mod_rewrite rules are used instead. But we'll keep this discussion talking about symlinks since it is easier to understand that way.)

Being a symlink means that relative links from the linked page may break when the symlink jumps to a different directory.

Special files, named .symlinks, when committed to the CVS tree, are interpreted as specifications to build symbolic links. Each symbolic link specification from the .symlinks file is honored, i.e., the symbolic link is created if it does not exist yet. If a symbolic link is found in the directory and is not listed in the .symlinks file, it is removed.

The .symlinks files obey the ln -s format, as described below:

  • Lines starting with a sharp sign (“#”) are ignored.
  • Lines that do not contain two strings separated by white space are silently ignored.

Here is an example of .symlinks, which redirects a file to another file in the same directory:

# Make a link named l.html to a target t.html.
# Strictly equivalent to ln -s t.html l.html:
t.html l.html

On each line the first file name must be a relative path name to an existing file. The second file name may not contain any slash; it is the name of the symbolic link to be created in the present directory. For instance, if a page named dir.html exists in the /dir directory, and index.html does not exist, /dir/.symlinks should contain a line like this:

dir.html index.html

The ln -s analogy accounts for only part of the story. Nowadays, the symlinks are converted to rewrite directives which are part of the server configuration [*]. This allows for a lot of flexibility: directories can be redirected as well as single files, and the target can be on another website. The server treats external redirections as “permanent,” meaning that it replaces the requested URL with the target. Thus, what is shown in the URL bar of the browser is the actual location of the document.

A peculiarity of this method is that a single HTML entry in .symlinks defines links to all possible translations that follow our naming conventions. This makes it impossible to use symlinks to redirect to and from HTML files whose names look like translations, that is, page.ll.html or page.ll-cc.html, where ll and cc are two-letter codes, as seen in the Filenames section. When you need such redirections, use the htaccess mechanism.

In the other cases (that is, nearly all cases), the symlinks method is preferred, as it takes precedence over htaccess. If you are not familiar with it, please ask for help on <webmasters@gnu.org>.

[*] The handling of symlinks happens on www.gnu.org via a cron job that runs twice an hour. Webmasters do not have access to it.

Meta refresh

Please avoid the redirects as much as possible, because they are known to harm both accessibility and public search engine ranking.

  • Some old pages are still redirected via a meta refresh such as this:

    <meta http-equiv="refresh" content="0" url="https://www.gnu.org/target">

    Please don't use this method for new redirections, as some browsers (e.g., Firefox) prevent the redirection from happening without user input. This is a security feature, but many people find it annoying, and it can disorient some impaired users.
  • Automatic refresh should be avoided too, because of its accessibility issues. If updating is necessary, provide a button.

Server-side scripts

A description of scripts and software used on www.gnu.org is available. Please read it before writing any scripts, and also update it as needed if you have write access to www.

System administrators

The system administrators for GNU change from time to time. Please email the sysadmin list <sysadmin@gnu.org> rather than an individual, unless you have a specific reason to do so.

Useful Resources

External resources

This section contains references managed by third parties.

  • The technical specifications to implement the web standards can be found at The World Wide Web Consortium, including the XHTML 1.0, HTML 5.2, and WCAG 2.1 recommendations.
  • The MDN Learning Area provides reliable specifications, guides and tutorials for beginners. It cannot replace the aforementioned official W3C specifications but it often provides useful clarifications.
  • The Best Viewed on Any Browser campaign and the old W3C Style Guide provide informal tips to ensure that a website is able to convey information to the largest audience possible. If a page does not obtain a satisfying positioning on public search engines then dedicated SEO becomes necessary.

Internal resources

This section contains references managed by us.