<!--#include virtual="/server/header.html" -->
<!-- Parent-Version: 1.95 1.98 -->
<!-- This page is derived from /server/standards/boilerplate.html -->
<title>Website Guidelines - GNU Project - Free Software Foundation</title>
<style type="text/css" media="print,screen"><!--
  .good { color: #005f5f; }
  .bad { color: #960400; }
--></style>
<!--#include virtual="/server/standards/po/gnu-website-guidelines.translist" -->
<!--#include virtual="/server/banner.html" -->
<h2>GNU Website Guidelines</h2>
<p class="center emph-box">
  Our goal is to get information to people.
  Keeping the site design simple helps accomplish that.
</p>

<div class="summary">
<hr class="no-display" />
<h3 class="no-display">Table of Contents</h3>
<ul>
  <li><a href="#GeneralGuidelines">General Guidelines</a></li>
  <li><a href="#CopyrightGuidelines">Copyright Guidelines</a></li>
  <li><a href="#orthography">Spelling and Punctuation</a></li>
  <li><a href="#filenames">Filenames</a></li>
  <li><a href="#urls">URLs</a></li>
  <li><a href="#HTMLGuidelines">HTML Guidelines</a></li>
  <li><a href="#tables">Tables and menus</a></li>
  <li><a href="#templating">Using our page template</a></li>
  <li><a href="#styling">Page Styling</a></li>
  <li><a href="#UseofGraphics">Use of Graphics</a></li>
  <li><a href="#pollinking">Appendix 1 - Linking Policies</a></li>
  <li><a href="#repo">Appendix 2 - Working with Web CVS Repositories</a>
    <ul>
      <li><a href="#cvs">Basic CVS commands</a></li>
      <li><a href="#symlinks">Symbolic links</a></li>
      <li><a href="#htaccess">.htaccess and redirections</a></li>
      <li><a href="#scripts">Scripts</a></li>
      <li><a href="#sysadmins">System administrators</a></li>
    </ul>
  </li>
  <li><a href="#UsefulResources">Useful Resources</a></li>
</ul>
<hr class="no-display" />
</div>

<p>Please be considerate of all who access our web pages, and accommodate
them, including those who use text-only browsers or old browsers, as well
as those with slow 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.</p>


<h3 id="GeneralGuidelines" class="subheader">General Guidelines</h3>


<ul class="para">
<li>The GNU web server has only <a href="/philosophy/free-sw.html">free
software</a> available.  We prefer that only free software be used to
prepare pages for the GNU web server.</li>

<li>The GNU website lists and links
<strong>only</strong> 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 <a
href="mailto:gnu@gnu.org"><gnu@gnu.org></a>.</li>

<li>The GNU website gives priority to software covered by either
the GNU General Public License or GNU Lesser General Public
License.</li>

<li>The use of graphics should be minimized so pages load fast over
slow links.</li>

<li>Offer a document in as many formats as the GNU Project has it.
For an example, see <a href="/licenses/fdl.html">The GNU Free
Documentation License</a>.  This lets users get the document in the
format most useful to them.</li>

<li>In addition to <a href="#CopyrightGuidelines">copyright and license
notices</a>, 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 information at the same place on each page.</li>

<li>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.</li>

<li>Before adding a link, check that it follows our <a
href="#pollinking">linking criteria</a>.</li>

<li>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 <a
href="/prep/mailinglists.html">mailing lists</a>.</li>

<li>On pages with dated entries (e.g., /philosophy/latest-articles.html),
the newer entries should be first (i.e., reverse chronological order).</li>

<li>Pages should not load CSS from servers other than those run
by the FSF.</li>

<li>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.</li>
</ul>


<h3 id="CopyrightGuidelines" class="subheader">Copyright Guidelines</h3>


<ul class="para">
<li>Every page should have a copyright notice.  See the <a
href="//web.cvs.savannah.gnu.org/viewvc/*checkout*/www/server/standards/boilerplate.html?root=www&content-type=text%2Fplain">
boilerplate</a>, referred below.</li>

<li>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.</li>

<li>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.</li>

<li>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.</li>

<li>The user of our pages should always find the copyright information
at the same place on each page.  If the page is copyrighted by some
other person or entity, use per or its copyright notice instead of the
FSF copyright notice.  Use the rest of the FSF's normal footer
material, except when there is a specific reason to change something
in it.</li>

<li>All pages that explain how to do something, such as how to use
certain programs, are documentation.  This includes all the pages in
<code>/software/</code> that describe specific programs.  By our
principles, <a href="/philosophy/free-doc.html"> documentation must be
free</a>.  So these pages must carry
a <a href="/licenses/license-recommendations.html">free
license</a>.  If such a page doesn't have a free license, please report the
problem to <a
href="mailto:webmasters@gnu.org"><webmasters@gnu.org></a>.</li>

<li>For other pages, use the same license as some other page that serves
a similar kind of purpose.</li>
</ul>


<h3 id="orthography" class="subheader">Spelling and Punctuation</h3> 


<ul class="para">
<li>English pages should follow the standard American spelling,
hyphenation and punctuation conventions.</li>

<li>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:
  <ul>
  <li>The term “nonfree” is preferred over “non-free”;
  likewise, “noncommercial” over “non-commercial.”</li>
  <li>In ordinary text, HTML entities
  “<code>&ldquo;</code>…<code>&rdquo;</code>” and
  “<code>&lsquo;</code>…<code>&rsquo;</code>”
  are preferred over straight quotes ("..." and '...').
  This doesn't apply to script-generated documents.</li>
  <li>Where they exist, the double spaces after sentence breaks should be
  preserved.  They enable Emacs sentence commands to do the right thing.</li>
  </ul>
</li>
</ul>


<a id="FilenameAndURLGuidelines"></a>
<h3 id="filenames" class="subheader">Filenames</h3>


<ul class="para">
<li>To make simultaneous edition of many files easier,
try and give each HTML file a unique and descriptive name; the special filename
<code>index.html</code> should only be used as a symbolic link, as
explained next.</li>

<li>Each directory in the web server tree should have a
symbolic link named <code>index.html</code> to the top-level HTML file
for that directory.  Use the <a
href="#symlinks"><code>.symlinks</code></a>
file to handle this.</li>

<li id="NamingTranslations">If you translate your web page in different
languages, please name the English file <code><var>article</var>.html</code>, and
its translations <code><var>article</var>.<var>lang</var>.html</code>—
<code><var>lang</var></code> should contain the two-letter language code from <a
href="//www.loc.gov/standards/iso639-2/php/code_list.php">ISO 639</a>,
and optionally an hyphen followed the two-letter country code given in
ISO 3166 (lowercase).  For example, the German translation of <code>not-ipr.html</code>
should be named <code>not-ipr.de.html</code>; the Brazilian Portuguese
translation should be named <code>not-ipr.pt-br.html</code>.</li>
</ul>


<h3 id="urls" class="subheader">URLs</h3>


<ul class="para">
<li>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 <code>/</code> (e.g., <code>/gnu/about-gnu.html</code>; <em>not</em>
<code>http://www.gnu.org/gnu/about-gnu.html</code>, and <em>not</em>
<code>about-gnu.html</code>).  This makes it easier to copy and paste
links from other pages.  Besides, links like
<code>http://www.gnu.org/</code> will be wrong when the visitor uses
HTTPS.</li>

<li>Check if the linked host supports both HTTPS and HTTP and use
protocol-relative URLs (e.g. <code>//www.example.org</code>) if it does.</li>

<li>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.</li>

<li>Don't use just a directory name in a URL; always include the
specific filename.  E.g., use <code>/gnu/gnu.html</code>, not just
<code>/gnu/</code>.  Never use <code>index.html</code> 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.</li>

<li>Be sure to omit the filename entirely when linking to an anchor in
the same file and double-check that the anchor actually works.</li>

<li>Consider others linking to your page when removing an anchor or
<code>id</code> attribute.</li>

<li>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 <code>README</code> 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.</li>

<li><p>Cite people with e-mail addresses this way:</p>
<p class="emph-box"><code>
<a href="//www.stallman.org/">Richard Stallman</a>
<a href="mailto:rms@gnu.org">&lt;rms@gnu.org&gt;</a>
</code></p>
<p>which browsers display this way:</p>
<p class="emph-box" style="background-color: inherit">
<a href="//www.stallman.org/">Richard Stallman</a>
<a href="mailto:rms@gnu.org"><rms@gnu.org></a>
</p>
<p>It is less confusing to the user, because it's clear what is a link
to another web page and what is a <code>mailto:</code> anchor that
will bring up a mail form to fill out and send, if this is
supported by the client.  Also, if users save a copy of the page,
they will have a copy of the e-mail address they can use without
going back to their web browser.  If the person doesn't have a web
page, leave the name unanchored.</p></li>

<li>When embedding static resources like videos that are not in
the <code>www</code> 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
<code>static.gnu.org</code> rather than <code>static.fsf.org</code>.
Both of these addresses have been set to point to the same machine, so
they can be used interchangeably.</li>
</ul>


<h3 id="HTMLGuidelines" class="subheader">HTML Guidelines</h3>


<ul class="para">
<li>HTML on the GNU web server should be strictly compliant with
<a href="//www.w3.org/standards/">W3C standards</a>.</li>

<li>Please follow the above mentioned web standards strictly.  Don't
neglect <a
href="//www.w3.org/TR/html401/struct/global.html#h-7.1">required
elements</a> such as <code><html></code>, <code><head></code>,
<code><title></code>, <code><body></code>, etc. when using (X)HTML,
and always include the appropriate DTD or Schema reference.
This appeases overly pedantic web browsers.</li>

<li>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 them, and often cause them to
incorrectly interpret your markup.</li>

<li>The <head> element should contain this line:
<p class="emph-box">
<code><link rel="author" href="mailto:webmasters@gnu.org"></code></p>
Some browsers use this information to allow users to easily report
problems they find on a page.</li>

<li>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.  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.</li>

<li>The <title> tag should include the phrases “GNU Project”
and “Free Software Foundation” so the pages will be found
when web search engines are used.  The default is to add this at the
end: <code> - GNU Project - Free Software Foundation</code>.</li>

<li>Acronyms/abbreviations:
  <ul>
  <li>Never use <code><acronym></code>: HTML 5 obsoletes it in
  favor of <code><abbr></code>.</li>

  <li>Don't use <code><abbr></code> unless for a really
  compelling reason.  Browsers render it in an ugly way.</li>

  <li>When an abbreviation may be unfamiliar to a reader, give its
  expansion the first time it is used in a document, like this:
  <code><abbr title="Expanded
  Abbreviation">EA</abbr></code> or <code>EA
  (Expanded Abbreviation)</code>.</li>

  <li>Further occurrences, in any case, should be written without any
  markup: just <code>EA</code>.</li>

  <li>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 judgment.</li>
  </ul>
</li>
</ul>


<h3 id="tables" class="subheader">Tables and menus</h3>


<ul class="para">
<li>Please use tables to organize data, not the presentation of the
web page.</li>

<li>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 sure that reading a whole
page left to right doesn't confuse such software.  Please follow the
<a href="//www.w3.org/WAI/">W3C web accessibility guidelines</a>
to ensure that tables are properly marked for accessibility.</li>

<li>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.</li>
</ul>


<h3 id="templating" class="subheader">Using our page template</h3>


<ul class="para">
<li>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 <a
href="//web.cvs.savannah.gnu.org/viewvc/*checkout*/www/server/standards/boilerplate.html?root=www&content-type=text%2Fplain">
original source</a> of the boilerplate instead, and follow the instructions
in it.</li>

<li>The XHTML templated pages must follow the <a
href="//www.w3.org/TR/xhtml1/">XHTML-1.0 guidelines</a>.</li>

<li>Our server-side includes declare UTF-8 as the character encoding, so
using any other encoding is problematic.</li>
</ul>


<h3 id="styling" class="subheader">Styling</h3>


<h4>Styling of templated pages</h4>

<ul class="para">
<li>Generic styling for desktops and smartphones is provided by 
<code>/layout.css</code>; it covers most of our use cases.</li>

<li>Mobile devices with very limited resources use <code>/mini.css</code>.
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.</li>

<li>Printers use <code>/print.css</code>.  Note that the header, navigation
bars and footer (except copyright and license) are unprintable.</li>

<li>In addition to <code>/layout.css</code>, some pages have specialized
stylesheets: <code>/graphics/graphics.css</code> for the GNU Art section,
and <code>/side-menu.css</code> for the Malware and Education sections.</li>

<li>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 <code>header.html</code> and <code>banner.html</code>.  If the
style applies to a single element, it should normally be added as an attribute.</li>

<li>If you specify any color attribute in the HTML, 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 stylesheet for
this, and not HTML 3.2 (HTML 4 Transitional) deprecated
markup.</li>
</ul>


<h4>Other stylesheets</h4>

<ul class="para">
<li>Historical pages (unmaintained translations for the most part) refer
to <code>/gnu.css</code>, which in turn loads <code>/mini.css</code>, <code>/mini.css</code>
(the Yahoo User Interface reset and base stylesheet, version 2),
as these pages are
usually very basic, plain pages with little or no formatting.</li>

<li>There are dedicated stylesheets for software manuals.  The main ones are:
  <ul>
  <li><code>/style.css</code>;</li>
  <li><a href="/software/gnulib/manual.css">gnulib.css</a>,
  which imports <code>/style.css</code> and adds a few more definitions;
  it is used by <code>gendocs.sh</code> to <a
  href="/prep/maintain/html_node/Invoking-gendocs_002esh.html">
  regenerate Texinfo manuals</a>.</li>
  </ul>
</li>

<li>Translators maintain stylesheets (<code>/style.<var>lang</var>.css</code>) that
modify layout.css according to their own needs.  The RTL languages (Arabic,
Persian, and Hebrew) use <code>/style.rtl.css</code>.</li>
</ul>


<h3 id="UseofGraphics" class="subheader">Use of Graphics</h3>


<ul class="para">
<li>The use of graphics should be minimized, so pages load fast
over slow links, especially animations.</li>

<li>We do not use background images on our pages, as they make text
significantly harder to read.</li>

<li>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 <a
href="/philosophy/gif.html">https://www.gnu.org/philosophy/gif.html</a>.
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).</li>

<li>Before you take an image from another website, please ask for
permission to use it.</li>

<li>Always have a textual alternative for in-line images, to ensure
indexability by search engines and accessibility.  For instance:
<p class="emph-box"><code><img src="/graphics/*.jpg"
alt="&nbsp;[DESCRIPTIVE TEXT]&nbsp;"></code></p>
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.</li>

<li id="image-size">Make sure the image doesn't look too big or too small
when displayed at its original size, using the browser's default font
size.</li>

<li><p>Adjust image width or height in a style attribute, using scalable
units such as <code>em</code> or <code>%</code>; for instance:</p>

<p class="emph-box"><code><img src="/graphics/*.jpg"
alt="&nbsp;[DESCRIPTIVE TEXT]&nbsp;"
style="width: 10em; height: auto;" /></code></p>

<p>This way, the page will look the same if the reader increases or
decreases font size.</p></li>

<li>If you are adding a small floating image to a page that uses
<code>layout.css</code> (the stylesheet for <a
href="/server/standards/README.webmastering.html#templating">templated pages</a>),
you may want to use the <code>imgright</code> or <code>imgleft</code> 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.</li>

<li>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
<code>pict</code> classes that are defined in the IMAGES section of
<code>layout.css</code> (you can adjust the width in a style
attribute if none of the predefined ones fits your needs); for instance:

<p class="emph-box"><code><div class="pict wide"
style="width: 25em"><img src="/graphics/*.jpg"
alt="&nbsp;[DESCRIPTIVE TEXT]&nbsp;"
/></div></code></p>

Note that the <code>div</code> container is necessary because some browsers (e.g.,
NetSurf) don't know how to apply <code>max-width</code> to images.</li>

<li><p>Link all images that are displayed throughout the website to the
relevant page, usually in <code>/graphics/</code>.  This can be done with
code similar to this, which corresponds to the image on the left:</p>

<p class="imgleft">
<a href="/graphics/agnuhead.html"><img
   src="/graphics/gnu-head-sm.jpg"
   alt=" [Image of the Head of a GNU] "
   style="width: 8em" /></a>
</p>

<pre class="emph-box">
<p class="imgleft">
<a href="/graphics/agnuhead.html">
<img src="/graphics/gnu-head-sm.jpg"
     alt=" [Image of the Head of a GNU] "
     style="width: 8em" /></a>
</p>
</pre>
<div style="clear: both"></div>

This will allow users to quickly go to pages related to the pictures they
are interested in.</li>
</ul>

<h3 id="pollinking" class="subheader">Appendix 1 - Linking Policies</h3>

<p>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.</p>

<p>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, Foundation and/or the GNU Project, 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.</p>

<dl>
<dt>What's the context of the link?</dt>

<dd>
<p>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.</p>
</dd>

<dt>Does the page promote proprietary software?</dt>

<dd>
<p>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.</p>

<p>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.</p>

<p>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?</p>

<p>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.”</p>

<p>If the page requires <a href="/philosophy/javascript-trap.html">nonfree,
nontrivial JavaScript</a> 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.</p>

<p>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, Chrome, Photoshop, Acrobat Reader, 
and Flash.</p>

<p>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:</p>

<blockquote><p>w3

<p class="indent-para">w3 is a web browser for GNU Emacs, similar to 
Internet Explorer. It can run on all platforms GNU Emacs runs on, 
including GNU/Linux, proprietary Unix systems, and Windows.</p></blockquote> Windows.</p>

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

<dt>How does the page compare free software to open source?</dt>

<dd>
<p>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  Here's an 
example of a tactful way to do it:</p>

<blockquote><p>GNOME

<p class="indent-para">XYZ is part of the GNU Project, and is free free/libre 
software (sometimes referred to as open source software).</p></blockquote> software).</p>

<p>Any exceptions to this rule should be apparent from the context. For 
instance, user groups group pages or pages of organizations listed in 
links.html may talk in greater detail about open source; we state on the user groups page, “As with our links
page, the 
those pages, “The FSF is not responsible for the contents of other 
websites, or how up-to-date their information is.”</p>
</dd>

<dt>How does the page treat the GNU Project?</dt>

<dd>
<p>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 
projects and user group pages should almost never, if ever, fail to do 
this. Again, exceptions for other pages should be apparent from context.</p>

<p>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 our linking guidelines, since they're understood to be the 
opinion of their individual authors.  Similarly, on user group or third 
party organization pages, the contents of forums and wiki pages should 
not hold weight in these regards.</p>

<p>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 encouraged the use of Flash and Flash, talked exclusively 
about open source software, and do not advocate users' freedom to 
redistribute and change software.  It's generally understood that since 
these pages are not primarily about free software, the policies do not 
hold full force for them.</p>

<p>As a final explanation (coming from RMS):
Even for making links from www.gnu.org, we do not <em>require</em> 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.</p>

<p>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.</p>
</dd>

<dt id="javascript">Does the page work even if the user's browser 
refuses to run JavaScript code?</dt>

<dd>
<p>If the page requires <a href="/philosophy/javascript-trap.html">
nonfree, nontrivial JavaScript</a> 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.</p>

<p>In some cases, however, we can still refer to such pages and 
resources by using workarounds to bypass the JavaScript requirement.</p> 

<p id="gothub">One possibility is to use an instance of <a 
href="https://codeberg.org/gothub/gothub">GotHub</a>—a free 
software frontend for GitHub that works without JavaScript—to 
replace links to pages and resources hosted at GitHub, a website that 
requires running nonfree JavaScript to be usable as intended. 
<!-- Add link to future article as follows: (See also 
<a href="/DIR/whats-wrong-with-github.html">What's Wrong with GitHub</a>.)--> 
</p>

<p>Currently (March 2024), GotHub is not actively maintained and it 
lacks some functionalities. For example, it doesn't offer a way to 
browse repositories or download the source code without visiting the 
GitHub website, and it doesn't provide a git clone URL. Still, GotHub is 
helpful for some usages. For example, it works well for linking to 
individual files.</p>

<p><strong>* Software packages</strong>. A useful file for software 
projects is the README file; it contains a description of the package, 
which is usually the first thing a user wants to see before attempting 
to fetch the repository. We have applied this solution several times in 
www.gnu.org; for example, we replaced this:<br />
<span class="bad"><code><del>https://github.com/pbatard/rufus</del></code></span> <br />
with this: <br />
<span class="good"><code>https://gothub.projectsegfau.lt/pbatard/rufus</code></span>.</p>

<p>Another solution is to link directly to the tarball of a tagged 
commit on GitHub. The drawback of this method is that it is not very 
useful for tracking the project over time.</p>

<p><strong>* Graphics, documents, manuals</strong>. These resources are 
sometimes hosted in user pages that do not require JavaScript to be 
fully usable, even when they are hosted inside an area of the GitHub 
website. In these cases, it is okay to link to such pages. For example, 
we replaced a link to <br />
<span class="bad"><code><del>https://github.com/foocorp/gnu-fm/blob/main/clients/meego/librefm/src/librefm-logo.png</del></code></span><br />
with a link to <br />
<span class="good"><code>https://raw.githubusercontent.com/foocorp/gnu-fm/main/clients/meego/librefm/src/librefm-logo.png</code>
</span>. <br />
And we have links to documents such as <br />
<span class="good"><code>https://raw.githubusercontent.com/scootergrisen/licenser/master/gpl-3.0.da.txt</code></span>.
</p>

<p>Sometimes a resource may be hosted in more than one acceptable place. 
It can be a personal page in GitHub or somewhere else, or in some 
unrelated website. When evaluating which one to choose, consider factors
such as: What's the status of the document? Is it a final version or is 
it likely to be modified anytime soon? Is the URL reliably stable, or 
is it likely to be moved?</p> 

<p>For example, in the past we had the case of a manual that was listed 
in other-free-books.html with this URL:<br />
<span class="bad"><code><del>https://github.com/davidam/orgguide-es</del></code></span>.<br />
At the time, we had three possibilitites to replace that bad link: <br />
1. GotHub<br />
<span class="good"><code>https://gothub.projectsegfau.lt/raw/davidam/davidam.github.io/master/docu/orgguide.es.pdf</code></span><br />
2. Author's personal space at GitHub<br />
<span class="good"><code>https://raw.githubusercontent.com/davidam/davidam.github.io/master/docu/orgguide.es.pdf</code>
</span><br />
3. Publisher/Bookstore<br />
<span class="good"><code>https://traficantes.net/sites/default/files/pdfs/orgguide.es_.pdf</code></span><br />
We decided for the third one, since it didn't seem that the manual was
likely to be updated to a new version, and <cite>Traficantes de Sueños</cite>
is an established, well-known publisher.</p>

<p>Issue trackers on GitHub can be viewed and browsed without JavaScript, 
but active participation entails an account that can't be created without 
running nonfree JavaScript. It's okay to link to closed issues, like we 
did for <br />
<span class="good"><code>https://github.com/w3c/fingerprinting-guidance/issues/8</code></span>. <br />
Another possibility for closed issues is to link to the archived page at
the Wayback Machine.</p> 

<p>Lastly, consider the possibility of talking to maintainers and 
authors to explain the problem. Hopefully they will move the repo 
somewhere else or post the material in a place we can link to.</p>
</dd>
</dl>



<h3 id="repo" class="subheader">Appendix 2 - Working with Web CVS Repositories</h3>


<h4 id="cvs">Basic CVS commands</h4>

<ul class="para">
<li>For reference manual, execute <kbd>info cvs</kbd>.</li>

<li>
Before the initial checkout, set the environment variable
<code>CVS_RSH=ssh</code>.</li>

<li>
<p>If you have write access to www, check out the main www repository
with your Savannah login:</p>

<pre class="emph-box">
<kbd>cvs -z3 -d:ext:<var>username</var>@cvs.savannah.gnu.org:/web/www co www</kbd>
</pre>

<p>You will get a working directory, <code>www</code>, with the same
structure as our main website.</p>
</li>

<li>
<p>If you don't have write access to www, you can still make an
anonymous checkout of www:</p>

<pre class="emph-box">
<kbd>cvs -z3 -d:pserver:anonymous@cvs.savannah.gnu.org:/web/www co www</kbd>
</pre>
</li>

<li>
<p>Check out the web repository of the <var>fooproject</var>:</p>

<pre class="emph-box">
<kbd>cvs -z3 -d:ext:<var>username</var>@cvs.savannah.gnu.org:/web/<var>fooproject</var> \
         co <var>fooproject</var></kbd>
</pre>

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

<p><em>Webmasters, please read <a
href="/server/standards/README.webmastering.html#gnupackages">Web pages for
official GNU software</a> before committing anything to the web repository
of a software project.</em></p>
</li>

<li>
<p>Add a file or directory:</p>

<pre class="emph-box">
<kbd>cvs add <var>foo</var></kbd>
</pre>
</li>

<li>
<p>Update before you edit a file:</p>

<pre class="emph-box">
<kbd>cvs update -P <var>foo</var></kbd>
</pre>
</li>

<li>
<p>Check the changes you are going to commit:</p>

<pre class="emph-box">
<kbd>cvs diff -U2 <var>foo</var></kbd>
</pre>
</li>

<li>
<p>Perform the commit (no need for <code>cvs add</code> if the file is
already in the repository):</p>

<pre class="emph-box">
<kbd>cvs commit <var>foo</var></kbd>
</pre>

<p>This will open a text editor where you should enter a log message.  
It will also show you a list of all files to be committed. The commit 
will occur upon saving exiting the editor.</p>

<p>Alternatively:</p>

<pre class="emph-box">
<kbd>cvs commit -m "Log message" <var>foo</var></kbd>
</pre>

<p>This option is somewhat less safe, as it doesn't show you a list of
the files to be committed. Moreover, a minor typo in the log message
(omitting the space between the message and the filename) may result in
committing <em>all</em> modified files in a directory, because the
filename will not be treated as an argument, but as part of the
message.</p>

<p>Without

<p id="log-msg"> <strong>It's important to write good commit log messages 
to help project members and future generations <em>find</em> specific 
changes in a given file and <em>understand</em> why your changes were 
made.</strong></p>

<div class="important">
<ul>
<li>Without being excessively verbose, log messages should describe as
clearly as possible the nature of the commit, including commit.<br />
<span class="good">Good: <code>Update link to <var>XYZ</var>.</code></span><br />
<span class="bad">Bad: <code><del>Update a link.</del></code></span></li>

<li>Always include a reference to any related
ticket numbers from RT to allow future historians to understand why your
changes were made.</p> tickets and/or mailing 
lists discussions. If no such reference exists, mention the name of the 
person(s) who authorized the change.</li>

<li>For dates, we use either the American-style notation 
(Sept. 27, 2023) or the ISO 8601 international standard 
format (2023-09-27).</li>
</ul>
</div>

<p>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.</p>

<p>The changes (except to <a href="#symlinks">.symlinks files</a>) should
be visible on www.gnu.org within minutes.</p>
</li>
</ul>

<p>For further details on CVS, such as reverting to a previous version, or
looking at the <code>diff</code> output of a particular change, see the <a
href="/software/trans-coord/manual/cvs/">CVS documentation</a>.</p>


<h4 id="symlinks">Symbolic links</h4>

<p>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.)</p>

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

<p>Special files, named <code>.symlinks</code>, 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.</p>

<p>The .symlinks files obey the <code>ln -s</code> format, as described below:</p>

<ul>
<li>Lines starting with a sharp sign (“#”) are ignored.</li>

<li>Lines that do not contain two strings separated by white space are silently
ignored.</li>
</ul>

<p>Here is an example of a .symlinks file:</p>

<pre class="emph-box">
# Make a link named l.html to a target t.html.
# Strictly equivalent to ln -s t.html l.html:
t.html l.html
</pre>

<p>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 <code><var>dir</var>.html</code> exists in the
<code>/<var>dir</var></code> directory, and <code>index.html</code> does not exist,
<code>/<var>dir</var>/.symlinks</code> should contain a line like this:</p>

<pre class="emph-box">
<var>dir</var>.html index.html
</pre>

<p>The <code>ln -s</code> analogy accounts for only part of the story.
The current method actually takes advantage of the flexibility of URL
rewriting.  Thus a single HTML entry in the .symlinks file defines links
to all possible translations that follow our <a
href="#NamingTranslations">naming
conventions</a>.  This makes it impossible to use
symlinks to redirect to and from HTML files whose names look like
translations, that is, <code><var>page</var>.<var>ll</var>.html</code> or
<code><var>page</var>.<var>ll</var>-<var>cc</var>.html</code>, where
<var>ll</var> and <var>cc</var> are two-letter
codes.  When you need such redirections, use the <a
href="#htaccess">htaccess mechanism</a>.</p>

<p>These days, the .symlinks handling happens on www.gnu.org
via a cron job that runs twice an hour.  Webmasters do not have
access to it.</p>


<h4 id="htaccess">.htaccess and redirections</h4>

<p>To browsers, the symbolic links in the previous section are
indistinguishable from the actual file.  You may want an actual
redirection in some cases.  You can do this either in the top-level
control file <code>.htaccess</code>, or by using something like this as the
file to be redirected:</p>

<p class="emph-box"><code>
<meta http-equiv="refresh" content="0;
  url=https://www.gnu.org/<var>target</var>">
</code></p>


<h4 id="scripts">Server-side scripts</h4>

<p>A <a href="/server/source/source.html">description of scripts and
software</a> 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.</p>


<h4 id="sysadmins">System administrators</h4>

<p>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.</p>


<h3 id="UsefulResources" class="subheader">Useful Resources</h3>


<ul class="para">
<li>Outside gnu.org:
  <ul>
    <li>We follow the guidelines of the <a
    href="//www.anybrowser.org/campaign/">Best Viewed with Any
    Browser</a> campaign.</li>

    <li>Basic info on the web and its technical specifications can be
    found at <a href="//www.w3.org/">The World Wide Web
    Consortium</a>.</li>

    <li>The GNU web server follows the w3.org <a
    href="//www.w3.org/Provider/Style/Overview.html">Style
    Guide</a>.</li>

    <li>Use of <a href="//w3.org/TR/WCAG21/">WCAG 2.1</a> helps
    ensure accessibility for a wide range of people with disabilities.</li>
  </ul>
</li>

<li>On gnu.org:
  <ul>
    <li><a href="#content">The GNU Website Guidelines</a> (this page);</li>

    <li>Guidelines for
    <a href="/server/standards/README.editors.html">Web Page Creation</a> at
    www.gnu.org;</li>

    <li><a href="/software/texinfo/manual/texinfo/html_node/Tips.html">
    Appendix B Tips and Hints</a>, and other style tips in the <a
    href="/software/texinfo/manual/texinfo/">Texinfo Manual</a>;</li>

    <li><a href="/accessibility/accessibility.html">GNU Accessibility
    Statement</a>;</li>

    <li><a href="/server/standards/README.webmastering.html">GNU
    Webmastering Guidelines</a>;</li>

    <li>Guide to
    <a href="/server/standards/README.translations.html">translating</a> GNU
    web pages into other languages;</li>

    <li><a href="/software/trans-coord/manual/gnun/html_node/Webmaster-Tips.html">
    Tips for webmasters</a> to make translators' job easier;</li>

    <li><a href="//savannah.gnu.org/maintenance/FrontPage/">Documentation for
    Savannah</a>, the SourceForge clone dedicated to the GNU Project;</li> Project.</li>

    <li><a href="/prep/gnumaint/README">
    README</a> for the <code>/prep/gnumaint/</code> directory (those files
    are primarily used by <a href="/prep/maintain/">GNU maintainer
    administrators</a>, and occasionally by GNU webmasters, to update
    the <code>/*/allgnupkgs.html</code> files in www);</li>

    <li><a href="/server/tasks.html">How href="/help/help.html">How to help</a> with our
    <a href="/server/server.html">web server</a>.</li> server</a> and other tasks.</li>

  </ul>
</li>
</ul>

</div><!-- for id="content", starts in the include above -->
<!--#include virtual="/server/footer.html" -->
<div id="footer"> id="footer" role="contentinfo">
<div class="unprintable">

<p>Please send general FSF & GNU inquiries to
<a href="mailto:gnu@gnu.org"><gnu@gnu.org></a>.
There are also <a href="/contact/">other ways to contact</a>
the FSF.  Broken links and other corrections or suggestions can be sent
to <a href="mailto:webmasters@gnu.org"><webmasters@gnu.org></a>.</p>

<p><!-- TRANSLATORS: Ignore the original text in this paragraph,
        replace it with the translation of these two:

        We work hard and do our best to provide accurate, good quality
        translations.  However, we are not exempt from imperfection.
        Please send your comments and general suggestions in this regard
        to <a href="mailto:web-translators@gnu.org">
        <web-translators@gnu.org></a>.</p>

        <p>For information on coordinating and contributing translations of
        our web pages, see <a
        href="/server/standards/README.translations.html">Translations
        README</a>. -->
Please see the <a
href="/server/standards/README.translations.html">Translations
README</a> for information on coordinating and contributing translations
of this article.</p>
</div>

<!-- Regarding copyright, in general, standalone pages (as opposed to
     files generated as part of manuals) on the GNU web server should
     be under CC BY-ND 4.0.  Please do NOT change or remove this
     without talking with the webmasters or licensing team first.
     Please make sure the copyright date is consistent with the
     document.  For web pages, it is ok to list just the latest year the
     document was modified, or published.

     If you wish to list earlier years, that is ok too.
     Either "2001, 2002, 2003" or "2001-2003" are ok for specifying
     years, as long as each year in the range is in fact a copyrightable
     year, i.e., a year in which the document was published (including
     being publicly visible on the web or in a revision control system).

     There is more detail about copyright years in the GNU Maintainers
     Information document, www.gnu.org/prep/maintain. -->

<p>Copyright © 2010, 2013-2021 2013-2021, 2023, 2024 Free Software
Foundation, Inc.</p>

<p>This page is licensed under a <a rel="license"
href="http://creativecommons.org/licenses/by-nd/4.0/">Creative
Commons Attribution-NoDerivatives 4.0 International License</a>.</p>

<!--#include virtual="/server/bottom-notes.html" -->

<p class="unprintable">Updated:
<!-- timestamp start -->
$Date: 2024/11/06 10:43:22 $
<!-- timestamp end --></p>
</div>
</div><!-- for class="inner", starts in the banner include -->
</body>
</html>