The GNU/FSF Web Site Guidelines
These are style guidelines for writing WWW web pages in HTML for the GNU web server.
The standards documented here are the default for the GNU project website. All pages should appear this way by default.
Copyright Guidelines
- Every page should have a copyright notice. See the boilerplate document linked below.
- If the page is copyrighted by someone else, make sure their copyright notice replaces the FSF copyright, but maintains the address, etc. The user of our pages should always find 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.
- All pages should have a notice saying that they are freely distributable. If you can not get such a permission from the author, please discuss this with the webmasters first.
General Guidelines
- Good spelling is encouraged.
- The GNU web server has only free software available. We prefer that only free software be used to develop content for the GNU web server.
- The GNU web server 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 web server gives priority to software covered by either the GNU General Public License or GNU Lesser General Public License.
- The GNU 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 or text-only browsers.
- Offer a document in as many formats as the GNU Project has it. For an example, see The GNU Free Documentation License. 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, 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, etc. from the GNU bug report mailing lists.
HTML Guidelines
- Our goal is to get information to people. Keeping the site design simple helps accomplish that.
- HTML on the GNU web server should be strictly compliant with W3C standards.
- A boilerplate for web pages, especially project web pages, is provided: view formatted, view source (with server-side includes intact).
- Acronyms/abbreviations:
- Never use
<acronym>
: HTML5 obsoletes it in favor of<abbr>
. - Don't use
<abbr>
unless for a really compelling reason. Browsers render it in an ugly way. - When an abbreviation may be unfamiliar to a reader, give its
expansion the first time it is used in a document, like this:
<abbr title="Expanded Abbreviation">EA</abbr>
orEA (Expanded Abbreviation)
. - Further occurrences, in any case, should be written without any
markup: just
EA
. - For common-enough initialisms, such as GNU, FSF, BSD, RAM, HTML, DVD, and so on and so on, no markup is needed at all. Use your judgement.
- Never use
- Our server-side includes declare UTF-8 as the character encoding, so using any other encoding is problematic.
- Please be considerate of all who access our web pages, and accomodate them, including those who use text-only browsers, or old browsers. We wish to prevent HTML design that looks great under one version of one browser, and ugly under many others. Of course, please don't install any of the proprietary software browsers available if you don't already use them anyway.
- Please follow the above mentioned web standards strictly. Don't neglect required elements such as <HTML> <HEAD> <TITLE> <BODY>, etc. when using (X)HTML, and always include the appropriate DTD or Schema reference. This appeases overly pedantic browsers.
- All pages 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) at the bottom of each page. 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, <H[n]>, 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. It 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". 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> tag should include the phrases "GNU Project"
and "Free Software Foundation" 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
. - The <HEAD> pair should have this line after the
<TITLE> pair:
<LINK rev="made" href="mailto:webmasters@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).
- Cite people with e-mail addresses this way:
<a href="http://www.stallman.org/">Richard Stallman</a> <a href="mailto:rms@gnu.org"><rms@gnu.org></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, if this is supported by the client. 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 browser. If the person doesn't have a web page, leave the name unanchored. - Cite FTP locations of source code with the full URL of the
directory they are in:
<a href="http://ftp.gnu.org/gnu/foo">http://ftp.gnu.org/gnu/emacs</a>
which browsers display this way:
http://ftp.gnu.org/gnu/emacs
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., aREADME
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. - When they exist, preserve double spaces after sentence breaks. They enable Emacs sentence commands to do the right thing.
- 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. Please use a style sheet for this, and not HTML 3.2 (HTML 4 Transitional) deprecated markup.
- Please use tables to organize data, not the presentation of the webpage.
- Some people like to use tables to organize links as a menu to the left or right of content 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 content of the page 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.
- Consider others linking to your page when removing page anchors.
- Screen reader software used by most blind people reads the text from left to right, ignoring any tables that you make. If you use tables, you should make an effort to make sure that reading a whole page left to right doesn't confuse such software. Please follow the WAI compatibility guidelines to ensure that tables are properly marked for accessibility.
- SGML and XML are case sensitive. TITLE and title are not the same thing in HTML. (This means that text/html and application/xhtml+xml are mutually exclusive, which also means that strictly speaking XHTML and HTML are mutually exclusive.)
- Do not add comments at the top of a document. Web browsers expect the doctype, XML declaration, or Schema to be at the top. Comments will confuse web browsers, and often cause them to incorrectly interpret your markup.
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
, nothttp://www.gnu.org/
). This makes it easier to copy and paste links from other pages. Links likehttp://www.gnu.org/
will be wrong when the visitor uses HTTPS. - Be sure to omit the file name entirely when referring to a tag in the same file.
- 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.
- 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, as explained next: - Each directory in the web server tree should have an
symbolic link named
index.html
to the top-level HTML file for that directory. Use the.symlinks
file to handle this. - 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/". 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. Also, this helps mirroring.
- If you translate your web pages in different
languages, please use
article.html
name for the English files andarticle.LANG.html
for the translations. LANG should contain two-letter language code from ISO 639 and optional hyphen with two-letter country code given in ISO 3166. For example, the German translation ofnot-ipr.html
should be namednot-ipr.de.html
; the Brazilian Portuguese translation should be namednot-ipr.pt-br.html
.
Use of Graphics
- The use of graphics should be minimized, so pages load fast over slow links, especially animations. The GNU Project is for everyone, even those with slow Internet access and/or text-only WWW browsers.
- In the past, GIFs have had patent problems. However, now that the IBM and Unisys patents (and other patents world-wide 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 http://www.gnu.org/philosophy/gif.html. Other formats are also allowed, though JPEG is the one most widely recognized by Web browsers (be careful with JPEG 2000, as well as PNG alpha channels, as it includes features not fully supported by older 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:
- install the graphic file in the '/graphics/' subdirectory.
- create a new html web page in '/graphics/'
- add a link to it on the GNU graphics 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:
This will allow the user to quickly go to a page related to the picture if he or she is interested. - 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. - Use width and height attributes for in-line images, but not in
ISO HTML:
<img src="/graphics/*.jpg" alt=" [Image of DESCRIPTIVE TEXT] " width="999" height="666" />.
This improves the performance of, and display on, 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 as the default on our pages.
- Sometimes it can be useful to add some HTML tags, for example with <SPAN> and CSS, that gives a broader "white" area around a block of text. This can be used to draw more attention to one block in the text.
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 Consortium.
- Use of the ISO standard for the Hypertext Markup Language (HTML) allows for consistent backwards compatibility among web user agents.
- The GNU web server follows the w3.org Style Guide.