[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
www/server/standards gnu-website-guidelines.html
|
From: |
Lorenzo L. Ancora |
|
Subject: |
www/server/standards gnu-website-guidelines.html |
|
Date: |
Sat, 10 Apr 2021 15:31:25 -0400 (EDT) |
CVSROOT: /web/www
Module name: www
Changes by: Lorenzo L. Ancora <lorenzoancora> 21/04/10 15:31:25
Modified files:
server/standards: gnu-website-guidelines.html
Log message:
Total overhaul (import from Staging).
CVSWeb URLs:
http://web.cvs.savannah.gnu.org/viewcvs/www/server/standards/gnu-website-guidelines.html?cvsroot=www&r1=1.21&r2=1.22
Patches:
Index: gnu-website-guidelines.html
===================================================================
RCS file: /web/www/www/server/standards/gnu-website-guidelines.html,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -b -r1.21 -r1.22
--- gnu-website-guidelines.html 21 Feb 2021 10:41:58 -0000 1.21
+++ gnu-website-guidelines.html 10 Apr 2021 19:31:24 -0000 1.22
@@ -1,54 +1,126 @@
<!--#include virtual="/server/header.html" -->
<!-- Parent-Version: 1.95 -->
<title>Website Guidelines - GNU Project - Free Software Foundation</title>
+<style type="text/css"><!--
+ .skiptoc { position: absolute; top: -2.5em; left: 0; }
+ .toc {
+ position: relative;
+ padding: 1.4em 1.5% 1.6em;
+ max-width: 97%;
+ margin-top: 3em;
+ }
+ .toc li { list-style: none; }
+ .emph-box { margin: .7em 0; }
+ dl dt { font-size: 1.125em; }
+ .pict.left { display: none; }
+ .example { margin: 1.5em 0; }
+
+@media (min-width: 45em) {
+ .columns { column-count: 2; }
+ .pict.left {
+ display: block; float: left;
+ width: 14em; width: max-content;
+ padding: .5em; border: 1px dotted;
+ margin: .4em 2em .4em 0;
+ }
+}
+
+@media (min-width: 55em) and (orientation: landscape) {
+ .flex { display: flex; flex-direction: row; }
+ .flex > * { width: 49%; }
+}
+--></style>
<!--#include virtual="/server/standards/po/gnu-website-guidelines.translist"
-->
<!--#include virtual="/server/banner.html" -->
+<div>
<h2>GNU Website Guidelines</h2>
+<div class="thin"></div>
<p class="center emph-box">
- Our goal is to get information to people.
- Keeping the site design simple helps accomplish that.
+ <em>Our goal is to get information to people.
+ Keeping the site design simple helps accomplish that.</em>
</p>
-<div class="summary">
+<p class="center">
+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.</p>
+
+<div class="toc">
+<p class="skiptoc">
+<small><a href="#GeneralGuidelines">[Skip the table of
contents]</a></small></p>
<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>
+<ul class="columns">
+ <li><a href="#GeneralGuidelines"><b>General Guidelines</b></a>
+ <ul>
+ <li><a href="#gnu-policies">GNU Policies</a></li>
+ <li><a href="#CopyrightGuidelines">Copyright</a></li>
+ <li><a href="#HTMLGuidelines">Web and Accessibility Standards</a></li>
+ </ul></li>
+ <li><a href="#new-page"><b>Creating a New Page</b></a>
+ <ul>
+ <li><a href="#filenames">Naming the file</a></li>
+ <li><a href="#html-required">Doctype and required HTML elements</a></li>
+ <li><a href="#page-footer">Page footer</a></li>
+ <li><a href="#templating">Using our page template</a></li>
+ </ul></li>
+ <li><a href="#writing"><b>Writing and Editing</b></a>
+ <ul style="display: inline-block">
+ <li><a href="#page-contents">Page contents</a></li>
+ <li><a href="#orthography">Spelling and punctuation</a></li>
<li><a href="#urls">URLs</a></li>
- <li><a href="#HTMLGuidelines">HTML Guidelines</a></li>
+ <li><a href="#anchors">URLs - page anchors</a></li>
+ <li><a href="#mailto">URLs - email links</a></li>
+ <li><a href="#external-links">URLs - external links</a></li>
+ <li><a href="#abbreviations">Acronyms and abbreviations</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>
+ <li><a href="#styling"><b>Styling</b></a>
+ <ul>
+ <li><a href="#styling-templated">Styling of templated pages</a></li>
+ <li><a href="#other-stylesheets">Other stylesheets</a></li>
+ <li><a href="#text-only">Text-only browsers</a></li>
+ </ul></li>
+ <li><a href="#UseofGraphics"><b>Use of Graphics</b></a>
+ <ul>
+ <li><a href="#caveats">Caveats</a></li>
+ <li><a href="#image-basics">Basic recommendations</a></li>
+ <li><a href="#image-css">CSS classes for images</a></li>
+ </ul></li>
+ <li><a href="#pollinking"><b>Linking Policies</b></a></li>
+ <li><a href="#repo"><b>Technical tips</b></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="#refresh">Meta refresh (don't use)</a></li>
+ <li><a href="#scripts">Server-side scripts</a></li>
<li><a href="#sysadmins">System administrators</a></li>
- </ul>
- </li>
- <li><a href="#UsefulResources">Useful Resources</a></li>
+ </ul></li>
+ <li><a href="#UsefulResources"><b>Useful Resources</b></a>
+ <ul>
+ <li><a href="#external-resources">External resources</a></li>
+ <li><a href="#internal-resources">Internal resources</a></li>
+ </ul></li>
</ul>
<hr class="no-display" />
</div>
+
+<h3 id="GeneralGuidelines" class="subheader">General Guidelines</h3>
+
<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
+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.</p>
+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.</p>
-<h3 id="GeneralGuidelines" class="subheader">General Guidelines</h3>
-
+<h4 id="gnu-policies">GNU Policies</h4>
<ul class="para">
<li>The GNU web server has only <a href="/philosophy/free-sw.html">free
@@ -62,23 +134,9 @@
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>
+the <a href="/licenses/gpl-3.0.html">GNU General Public License</a> or the
+<a href="/licenses/lgpl-3.0.html">GNU Lesser General Public License</a>.</li>
+<!-- What does this mean exactly? -->
<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
@@ -90,28 +148,25 @@
<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
+to get bug reports and other messages from the relevant <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
+this need to be reviewed and approved by the
+<a href="/people/webmeisters.html"> Chief GNUisance</a> on a
case-by-case basis.</li>
</ul>
-<h3 id="CopyrightGuidelines" class="subheader">Copyright Guidelines</h3>
-
+<h4 id="CopyrightGuidelines">Copyright Guidelines</h4>
<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 copyright notice listing the copyright
+holder(s) and copyright year(s).</li>
<li>Every page should have a notice giving everyone permission
to distribute it. If you cannot get such a permission from the author,
@@ -127,13 +182,6 @@
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
@@ -149,35 +197,28 @@
</ul>
-<h3 id="orthography" class="subheader">Spelling and Punctuation</h3>
-
+<h4 id="HTMLGuidelines">Web and accessibility standards</h4>
<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>
+<li>All public pages of the GNU website should be strictly compliant with
+<a href="https://www.w3.org/TR/?status=rec";>W3C Recommendations (REC)</a>,
+as opposed to Working Drafts (WD), Candidate Recommendations (CR),
+Proposed Recommendations (PR) or Retired Recommendations (RET).</li>
+
+<li>HTML 5 and CSS3 are target for upgrade from older standards.</li>
+
+<li>Regardless of the web standards used, all pages should meet the
+<a href="https://www.w3.org/TR/2018/REC-WCAG21-20180605/";>Web Content
+Accessibility Guidelines (WCAG)</a>.</li>
</ul>
-<a id="FilenameAndURLGuidelines"></a>
-<h3 id="filenames" class="subheader">Filenames</h3>
+<h3 id="new-page" class="subheader">Creating a New Page</h3>
+<a id="FilenameAndURLGuidelines"></a>
+<h4 id="filenames">Naming the file</h4>
+
<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
@@ -190,41 +231,179 @@
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>
+<li id="NamingTranslations">If you translate your web page (say,
+<code><var>page</var>.html</code>) in different languages, please
+name the translations <code><var>page.lang</var>.html</code>—
+<code><var>lang</var></code> should contain the relevant two-letter code
+from <a href="https://www.loc.gov/standards/iso639-2/php/code_list.php";
+rel="noopener">ISO 639-1</a>,
+and optionally a hyphen followed by the two-letter <i>Alpha-2</i> country
+code from <a href="https://www.iso.org/obp/ui/#search/code/";
+rel="noopener">ISO 3166-1</a> (converted to 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>
+<h4 id="html-required">Doctype and required HTML elements</h4>
+<ul class="para">
+<li>Please follow the above mentioned web standards strictly, even when you are
+forced to follow superseded W3C recommendations: don't neglect
+<a href="https://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> and <code><body></code>,
+and always include the appropriate DTD or Schema reference in all markup
+standards older than HTML 5.
+This appeases overly pedantic web browsers.</li>
+
+<li>Do not add <code><!-- comments --></code> 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.<br />
+If you <i>must</i> add a comment before <code><!DOCTYPE html></code>, then
+use <code><!--[if !IE]> comments <![endif]--></code>.</li>
+
+<li>The <code><head></code> 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 element, generally <code><h1></code> or
<code><h2></code>, should have
+its text duplicated at the start of the <code><title></code> 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
+<code><title></code> 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 <code><title></code> element should include the
+phrases <i>“GNU Project”</i>
+and <i>“Free Software Foundation”</i> so the pages can be better
+indexed by external search engines. The default is to add this at the
+end: <code> - GNU Project - Free Software Foundation</code>.</li>
+</ul>
+
+
+<h4 id="page-footer">Page footer</h4>
+
+<ul class="para">
+<li>All pages should have a footer. 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>The footer should include the <a
+href="#CopyrightGuidelines">copyright and license notices</a> for the
+<em>page itself</em>. The copyright and license notices for material that
+is part of the page (such as images) should normally be placed in the
+main text.<br />
+The rules for listing copyright holders and years are detailed in
+the <a href="/prep/maintain/html_node/Copyright-Notices.html">GNU
+Maintainers' guide</a>.</li>
+
+<li>The Copyright Infringement Notification is a legal requirement.</li>
+
+<li>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.</li>
+</ul>
+
+
+<h4 id="templating">Using our page template</h4>
+
+<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>
+
+<!-- Impact on the transition toward HTML 5 and WCAG? -->
+<li>The templated pages must follow the <a
+href="https://www.w3.org/TR/xhtml1/";>XHTML-1.0 guidelines</a>.
+Well-formedness is essential for translatable pages that need to be
+converted to POT files by the PO4A/Gettext tools.</li>
+
+<li>Our <abbr title="Server-Side Include">SSI</abbr>s declare UTF-8 as the
+character encoding; using any other encoding is problematic.<br />See the
+<a href="https://httpd.apache.org/docs/current/howto/ssi.html";>
+Introduction to Apache SSIs</a> to learn more on this topic.</li>
+</ul>
+
+
+<h3 id="writing" class="subheader">Writing and Editing</h3>
+
+
+<h4 id="page-contents">Page contents</h4>
+
+<ul class="para">
+<li>On pages with dated entries (e.g., /philosophy/latest-articles.html),
+the newer entries should be first; in other words, preserve reverse
+chronological order.</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>
+</ul>
+
+
+<h4 id="orthography">Spelling and punctuation</h4>
+
+<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>
+
+
+<h4 id="urls">URLs - local links</h4>
<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>http://www.gnu.org/gnu/about-gnu.html</code> nor
+<code>https://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
+specific filename. For instance, 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
@@ -233,38 +412,6 @@
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
@@ -278,85 +425,125 @@
</ul>
-<h3 id="HTMLGuidelines" class="subheader">HTML Guidelines</h3>
-
+<h4 id="anchors">URLs - page anchors</h4>
<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>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>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>Consider others linking to your page when either removing an element
+that carries an <code>id</code> attribute, or changing an <code>id</code>.
+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:
-<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>
+<pre class="emph-box">
+<samp><!-- 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></samp>
+</pre>
-<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>
+Please avoid moving the old <code>id</code> to a translatable string,
+unless there is no other way to keep the markup valid. Translators will
+thank you!</li>
+</ul>
-<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>
+<h4 id="external-links">URLs - external links</h4>
+
+<ul class="para">
+<li><em>Reminder:</em> before adding a link, check that it follows our <a
+href="#pollinking">linking criteria</a>.</li>
+
+<li>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).</li>
+<!--
+<li>Protocol-relative URLs (e.g., <code>//www.example.org</code>) are not
+recommended when linking to external, third-party domains.</li>
+-->
+</ul>
+
+
+<h4 id="mailto">URLs - email links</h4>
+
+<ul class="para">
+<li>Place angle brackets around <code>mailto:</code> 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 <a href="https://tools.ietf.org/html/rfc6068#section-6";>RFC 6068</a> for
+advanced examples of how to use mailto URIs to specify a subject, the
+body, etc.</li>
+
+<li>When citing people, place the <code>mailto:</code> anchor next to
+their name, so that the email address is retained in printed copies of
+the page; for example,
-<li>Acronyms/abbreviations:
<ul>
- <li>Never use <code><acronym></code>: HTML 5 obsoletes it in
- favor of <code><abbr></code>.</li>
+ <li>If the person has a website:
+ <pre class="emph-box">
+<samp><a href="https://www.stallman.org/">Richard
Stallman</a></samp>
+<samp><a
href="mailto:rms@gnu.org">&lt;rms@gnu.org&gt;</a></samp></pre>
+ <p>… rendered like</p>
+ <p class="emph-box" style="background-color: inherit">
+ <a href="https://www.stallman.org/";>Richard Stallman</a>
+ <a href="mailto:rms@gnu.org";><rms@gnu.org></a>
+ </p>
+ </li>
+ <li>
+ <p>If the person doesn't have a website:</p>
+ <pre class="emph-box">
+<samp>Richard Stallman</samp>
+<samp><a
href="mailto:rms@gnu.org">&lt;rms@gnu.org&gt;</a></samp></pre>
+ <p>… rendered like</p>
+ <p class="emph-box" style="background-color: inherit">
+ Richard Stallman
+ <a href="mailto:rms@gnu.org";><rms@gnu.org></a>
+ </p>
+ </li>
+ </ul>
+</li>
+</ul>
- <li>Don't use <code><abbr></code> unless for a really
- compelling reason. Browsers render it in an ugly way.</li>
+
+<h4 id="abbreviations">Acronyms and abbreviations</h4>
+
+<ul class="para">
+ <li>Never use <code><acronym></code>: HTML 5 obsoletes it in
+ favor of <code><abbr></code>. The latter must be expanded in a
+ <code>title</code> attribute.</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
+ expansion <i>only the first time</i> it is used in a document.<br />
+ Example: <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>Make sure <code><abbr></code> is styled via CSS to meet the
+ accessibility guidelines. By default some browsers render it in an
+ ugly way.</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.
+ DVD, 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>
-
+<h4 id="tables">Tables and menus</h4>
<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>Please use tables to organize data (<a
+href="https://www.w3.org/WAI/WCAG21/Techniques/html/H51";><i>data</i>
tables</a>),
+not the presentation of the web page (<i>layout</i> tables).<br />
+If you <em>must</em> use layout tables, be sure that the table <a
+href="https://www.w3.org/WAI/WCAG21/Techniques/failures/F49";>makes sense
+when linearized</a>, and has <a
+href="https://www.w3.org/WAI/WCAG21/Techniques/failures/F91";>appropriately
+marked up headers</a>.</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
@@ -365,55 +552,42 @@
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
+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>
+is another option (see the table of contents above for an example).</li>
</ul>
<h3 id="styling" class="subheader">Styling</h3>
-<h4>Styling of templated pages</h4>
+<h4 id="styling-templated">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>Generic styling for desktops and smartphones is provided by <a
+href="/layout.css"><code>layout.css</code></a>; 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
+<li>Mobile devices with very limited resources use <a
+href="/mini.css"><code>mini.css</code></a>.
+This stylesheet is just the Yahoo User Interface (version 2) <a
+href="https://yui.github.io/yui2/docs/yui_2.9.0_full/reset/index.html";>reset</a>
+and <a
+href="https://yui.github.io/yui2/docs/yui_2.9.0_full/base/index.html";>base</a>
+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
+<li>Printers use <a href="/print.css"><code>print.css</code></a>. 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>In addition to <code>layout.css</code>, some pages have specialized
+stylesheets: <a
+href="/graphics/graphics.css"><code>graphics.css</code></a> for the GNU
+Art section, and <a
+href="/side-menu.css"><code>side-menu.css</code></a> 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
@@ -421,7 +595,7 @@
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
+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
@@ -431,40 +605,144 @@
</ul>
-<h4>Other stylesheets</h4>
+<h4 id="other-stylesheets">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>,
-as these pages are
+to <a href="/gnu.css"><code>gnu.css</code></a>, which in turn loads
+<code>mini.css</code>, 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;
+ <li><a href="/style.css"><code>style.css</code></a>;</li>
+ <li><a href="/software/gnulib/manual.css"><code>gnulib.css</code></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>
+<li>Translators maintain stylesheets (<code>/style.<var>lang</var>.css</code>)
+that modify <code>layout.css</code> according to
+their own needs. The RTL languages (Arabic, Persian, and Hebrew) use
+<a href="/style.rtl.css"><code>style.rtl.css</code></a>. Please don't
+forget to update <code>style.rtl.css</code> if you make LTR-specific
+changes to <code>layout.css</code>.</li>
</ul>
+<h4 id="text-only">Text-only browsers</h4>
+
+<p>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 <code>less</code>, <code>wget</code>, <code>ncurses</code>
+with a html-to-text transformation engine.</p>
+
+<p>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 <i>grid</i> devices (the text terminals).</p>
+
+<ul class="para">
+<li>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.</li>
+
+<li>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 <i>at least</i> support for 24-bit color,
+italic/bold fonts and UTF-8 enabled.</li>
+
+<li>The CSS media queries can be used to detect graphical web browsers and
their
+capabilities, but may be ignored (always return <var>true</var>) on text-only
+browsers.
+
+<p>The correct way to prevent graphical browsers from parsing
+a CSS fragment dedicated to text-only browsers is:</p>
+
+<div class="flex">
+ <pre class="emph-box">
+<code>/* Discarded by GUI-based web browsers */
+@media only screen and (grid: 1) {
+ exp { prop: value; }
+ …
+}</code></pre>
+ <pre class="emph-box">
+<code>/* 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);</code></pre>
+</div>
+
+<p>…for in-page block embedding:</p>
+
+<div class="flex">
+ <pre class="emph-box">
+<code><-- Discarded by GUI-based web browsers -->
+<style media="only screen and (grid: 1)">
+ exp { prop: value; }
+ …
+</style></code></pre>
+ <pre class="emph-box">
+<code><style … >
+ /* Discarded by GUI-based web browsers */
+ @media only screen and (grid: 1) {
+ exp { prop: value; }
+ …
+ }
+</style></code></pre>
+</div>
+
+<p>…and for external resource (direct) inclusion:</p>
+
+<pre class="emph-box">
+<code><!-- Not downloded by GUI-based web browsers -->
+<link href="tty.css" rel="stylesheet" media="only screen and (grid: 1)">
+</code></pre>
+
+<p>Always double-check the result on different web browsers.</p>
+</li>
+</ul>
+
+<p>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 <code>fold</code> from the GNU coreutils to ease the task.</p>
+
+
<h3 id="UseofGraphics" class="subheader">Use of Graphics</h3>
+<h4 id="caveats">Caveats</h4>
+
<ul class="para">
<li>The use of graphics should be minimized, so pages load fast
-over slow links, especially animations.</li>
+over slow links, especially animations.<br />
+Ideally, the <i>average</i> 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 <abbr title="Traffic Control">TC</abbr> implements
+<abbr title="Hierarchical Token Bucket">HTB</abbr>, which can be used to create
+advanced testing environments with throttled network interfaces.</li>
<li>We do not use background images on our pages, as they make text
-significantly harder to read.</li>
+significantly harder to read.<br />
+If you are forced to add a background, ensure there is <a
+href="https://www.w3.org/WAI/WCAG21/Techniques/failures/F83";>sufficient
+contrast</a> with text, graphs, … and remember that CSS gradients may
+not be rendered by accessibility tools.</li>
<li>In the past, GIFs have had patent problems. However, now that
the IBM and Unisys patents (and other patents worldwide that are
@@ -474,90 +752,172 @@
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>.
+old GIF problem, see “<a
+href="/philosophy/gif.html">Why There Are No GIF Files on GNU Web
Pages</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>
+</ul>
+
+
+<h4 id="image-basics">Basic recommendations</h4>
+
+<ul class="para">
+<li>All images that are not purely decorative should provide <a
+href="https://www.w3.org/WAI/WCAG21/Techniques/failures/F83";>sufficient
+contrast</a> between informative parts (text, graphs, etc.) and
+background.</li>
+
+<li><p>Always have a textual alternative for in-line images, to ensure
+indexability by search engines and accessibility. For instance:</p>
+
+<div class="pict left">
+ <p>Loaded in graphic browser:<br />
+ <img src="/graphics/gnu-post/Alternative-GNU-stamp.png"
+ title="BRIEF TEXT"
+ alt=" [DESCRIPTIVE TEXT] "
+ style="width: 5em; height: auto; border: 2px solid gray"
+ width="80px" height="80px" />
+ </p>
+ <p>Loading failed or text reader:<br />
+ <samp>
+ <img src="/graphics/gnu-post/Alternative-GNU-stamp.invalid"
+ title="BRIEF TEXT"
+ alt=" [DESCRIPTIVE TEXT] "
+ style="width: 5em; height: auto; border: 2px solid gray"
+ width="80px" height="80px" />
+ </samp>
+ </p>
+</div>
-<li>Before you take an image from another website, please ask for
-permission to use it.</li>
+<pre class="emph-box">
+<img src="/graphics/gnu-post/Alternative-GNU-stamp.png"
+ title="BRIEF TEXT"
+ alt="&nbsp;[DESCRIPTIVE TEXT]&nbsp;">
+</pre>
-<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
+<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>
+PO4A/Gettext tools.</p>
+<div style="clear: both"></div>
+</li>
-<li id="image-size">Make sure the image doesn't look too big or too small
+<li id="image-size">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.</li>
+size. If it is too big and you can't make a smaller version, adjust the
+size with the width and height attributes.<br />
+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.</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>
+<li>Also adjust image width or height in a style attribute, using scalable
+units such as <code>em</code> or <code>%</code>; for instance:
+<div style="clear: both"></div>
-<p class="emph-box"><code><img src="/graphics/*.jpg"
-alt="&nbsp;[DESCRIPTIVE TEXT]&nbsp;"
-style="width: 10em; height: auto;" /></code></p>
+<img src="/graphics/gnu-post/Alternative-GNU-stamp.png"
+ title="GNU stamp"
+ alt=" [Stamp with an abstract GNU head] "
+ style="width: 10em; height: auto; float: right; margin: .5em 0 .5em 1.5em"
+ width="160px"
+ height="160px" />
+
+<pre class="emph-box">
+<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" />
+</pre>
<p>This way, the page will look the same if the reader increases or
-decreases font size.</p></li>
+decreases font size.<br />Specifying both <code>width</code> and
+<code>height</code> will reserve the space required for the image during
+the page loading phase, preventing incremental <a
+href="https://developers.google.com/speed/docs/insights/browser-reflow";>
+layout reflows</a>.</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>Link all images that are displayed throughout the website to the
+relevant page, usually in <code>/graphics/</code>.
+This will allow users to quickly go to pages related to the pictures they
+are interested in. See the next section for an example.</li>
+</ul>
-<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>
+<h4 id="image-css">CSS classes for images</h4>
+
+<ul class="para">
+<li><p>If you are adding a small floating image to a page that uses
+<a href="/layout.css"><code>layout.css</code></a> (the stylesheet for <a
+href="#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. Here is an example:</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>
+<a href="/graphics/gnu-post/"><img
+ src="/graphics/gnu-post/GNU-stamp.png"
+ title="GNU stamp"
+ alt=" [Stamp with a GNU head] "
+ style="width: 8em; height: auto"
+ width="128px" height="128px" />
+</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>
+ <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>
</pre>
<div style="clear: both"></div>
+</li>
-This will allow users to quickly go to pages related to the pictures they
-are interested in.</li>
+<li><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
+<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>
+
+<div class="pict medium" style="width: 15em">
+ <img src="/graphics/gnu-post/GNU-stamp.png"
+ title="GNU stamp"
+ alt=" [Stamp with a GNU head] "
+ width="225px" height="225px" />
+</div>
+
+<pre class="emph-box">
+<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>
+</pre>
+
+<p>Please note that the container (<code>div</code> in this case) is necessary
for
+retrocompatibility with some browsers which cannot apply <code>max-width</code>
+to images; in addition, be aware that a nested <code>table</code> may not
+inherit <code>max-width</code> on all web browsers (i.e., always test for
+compatibility when you need to put a table beside a picture).</p>
+<div style="clear: both"></div>
+</li>
+
+<li><a href="/graphics/graphics.css"><code>graphics.css</code></a> has
+some other layouts.</li>
</ul>
-<h3 id="pollinking" class="subheader">Appendix 1 - Linking Policies</h3>
+<h3 id="pollinking" class="subheader">Linking Policies</h3>
<p>One of the most complex aspects of maintaining web pages is following the
@@ -632,18 +992,20 @@
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.</p>
+such as Office, Internet Explorer, 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>
+text — and not much else — would be acceptable:</p>
-<blockquote><p>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>
+<blockquote>
+ <p>w3m is a text-only web browser which can be used from GNU Emacs
+ via emacs-w3m, replacing proprietary web browsers like <em>Internet
+ Explorer</em>. It can run on all platforms GNU Emacs runs on, including
+ GNU/Linux, proprietary <em>Unix</em> systems, and <em>Windows</em>.</p>
+</blockquote>
<p>Links which appear in other areas, such as the testimonials or
philosophy pages, as well as links to user groups may discuss such
@@ -661,14 +1023,14 @@
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:</p>
-<blockquote><p>GNOME is part of the GNU Project, and is free software
(sometimes
-referred to as open source software).</p></blockquote>
+<blockquote><p>GNOME is part of the GNU Project, and is free software
+(sometimes referred to as open source software).</p></blockquote>
<p>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
+open source; we state on the user groups page, <q>As with our links
page, the FSF is not responsible for the contents of other websites,
-or how up-to-date their information is.”</p>
+or how up-to-date their information is.</q></p>
</dd>
<dt>How does the page treat the GNU Project?</dt>
@@ -676,7 +1038,7 @@
<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
+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.</p>
@@ -697,11 +1059,14 @@
primarily about free software, the policies do not hold full force for
them.</p>
-<p>As a final explanation (coming from RMS):
+<p>As a final explanation:</p>
+
+<blockquote><p>
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>
+rather than “open source”. We do, however, require that they not
+promote any nonfree software. — <i>RMS</i>
+</p></blockquote>
<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
@@ -714,21 +1079,24 @@
</dl>
-<h3 id="repo" class="subheader">Appendix 2 - Working with Web CVS
Repositories</h3>
+<h3 id="repo" class="subheader">Technical tips</h3>
<h4 id="cvs">Basic CVS commands</h4>
<ul class="para">
-<li>For reference manual, execute <kbd>info cvs</kbd>.</li>
+<li>For the offline reference manual, execute <kbd>info cvs</kbd>.</li>
<li>
Before the initial checkout, set the environment variable
-<code>CVS_RSH=ssh</code>.</li>
+<kbd>CVS_RSH=ssh</kbd>.<br />Alternatively, you can replace
+<code>:ext:</code> with
+<a href="/software/trans-coord/manual/cvs/cvs.html#Connecting-with-rsh-or-ssh">
+<code>:extssh:</code></a> to use an external ssh program.</li>
<li>
-<p>If you have write access to www, check out the main www repository
-with your Savannah login:</p>
+<p>If you have write access to the main repository of www.gnu.org, check
+it out with your Savannah login username:</p>
<pre class="emph-box">
<kbd>cvs -z3 -d:ext:<var>username</var>@cvs.savannah.gnu.org:/web/www co
www</kbd>
@@ -739,8 +1107,8 @@
</li>
<li>
-<p>If you don't have write access to www, you can still make an
-anonymous checkout of www:</p>
+<p>If you don't have write access to the main repository, you can still
+check it out anonymously:</p>
<pre class="emph-box">
<kbd>cvs -z3 -d:pserver:anonymous@cvs.savannah.gnu.org:/web/www co www</kbd>
@@ -748,7 +1116,7 @@
</li>
<li>
-<p>Check out the web repository of the <var>fooproject</var>:</p>
+<p>Check out the <strong>web</strong> 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> \
@@ -756,9 +1124,10 @@
</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>
+structure as the <code>www/software/<var>fooproject</var></code> subdirectory.
+Note, however, that the <var>fooproject</var> and main repositories
+are independent, so 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
@@ -840,7 +1209,8 @@
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>
+<p>The <code>.symlinks</code> files obey the <code>ln -s</code> format,
+as described below:</p>
<ul>
<li>Lines starting with a sharp sign (“#”) are ignored.</li>
@@ -849,7 +1219,8 @@
ignored.</li>
</ul>
-<p>Here is an example of a .symlinks file:</p>
+<p>Here is an example of <code>.symlinks</code>, which redirects a file to
+another file in the same directory:</p>
<pre class="emph-box">
# Make a link named l.html to a target t.html.
@@ -869,43 +1240,64 @@
</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
+Nowadays, the symlinks are converted to rewrite directives which are
+part of the server configuration [<a href="#cron">*</a>].
+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.</p>
+
+<p>A peculiarity of this method is that a single HTML entry in
+<code>.symlinks</code> 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>
+<var>ll</var> and <var>cc</var> are two-letter codes, as seen in
+the <a href="#filenames">Filenames</a> section.
+When you need such redirections, use the htaccess mechanism.</p>
+
+<p>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>.</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
+<p>[<a id="cron" href="#cron">*</a>] 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.</p>
-<h4 id="htaccess">.htaccess and redirections</h4>
+<h4 id="refresh">Meta refresh</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>Please avoid the redirects as much as possible, because they are known
+to harm both accessibility and public search engine ranking.</p>
+
+<ul class="para">
+<li>Some old pages are still redirected via a meta refresh such as this:
<p class="emph-box"><code>
-<meta http-equiv="refresh" content="0;
- url=https://www.gnu.org/<var>target</var>">
+<meta http-equiv="refresh" content="0"
+ url="https://www.gnu.org/<var>target</var>">
</code></p>
+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.</li>
+
+<li>Automatic refresh should be avoided too, because of its <a
+href="https://www.w3.org/WAI/WCAG21/Techniques/failures/F41";>accessibility
+issues</a>. If updating is necessary, provide a
+<a href=""><button style="cursor:pointer">Reload page</button></a> button.</li>
+</ul>
<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>
+access to <code>www</code>.</p>
<h4 id="sysadmins">System administrators</h4>
@@ -918,28 +1310,46 @@
<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>
+<h4 id="external-resources">External resources</h4>
- <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>
+<p>This section contains references managed by third parties.</p>
-<li>On gnu.org:
- <ul>
+<ul>
+ <li>The technical specifications to implement the web standards can be
+ found at <a href="https://www.w3.org/";>The World Wide Web
+ Consortium</a>, including the <a
+ href="https://www.w3.org/TR/2018/SPSD-xhtml1-20180327/";>XHTML 1.0</a>,
+ <a href="https://www.w3.org/TR/html52/";>HTML 5.2</a>, and
+ <a href="https://www.w3.org/TR/2018/REC-WCAG21-20180605/";>WCAG 2.1</a>
+ recommendations.</li>
+
+ <li>The <abbr title="Mozilla Developer Network">MDN</abbr>
+ <a href="https://developer.mozilla.org/en-US/docs/Learn";>Learning Area</a>
+ provides reliable specifications, guides and tutorials for beginners. It
+ cannot replace the aforementioned official W3C specifications but it often
+ provides useful clarifications.</li>
+
+ <li>The <a
+ href="https://www.anybrowser.org/campaign/"; rel="noopener"
+ style="text-decoration: none;">
+ <!-- You may use this icon on the pages which are intentionally simple -->
+ <img src="../graphics/icons/anybrowser.png" width="96px" height="18px"
+ title="Visit the 'Best Viewed on Any Browser' campaign website"
+ alt="Best Viewed on Any Browser"
+ style="vertical-align: middle; width: 6em; height: auto" /></a>
+ campaign and the old
+ <a href="https://w3.org/Provider/Style/Overview.html";>W3C Style Guide</a>
+ provide <em>informal tips</em> 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
+ <abbr title="Search Engine Optimization">SEO</abbr> becomes necessary.</li>
+</ul>
+
+<h4 id="internal-resources">Internal resources</h4>
+
+<p>This section contains references managed by us.</p>
+
+<ul>
<li><a href="#content">The GNU Website Guidelines</a> (this page);</li>
<li>Guidelines for
@@ -970,13 +1380,12 @@
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>
+ the <code>/*/allgnupkgs.html</code> files in <code>www</code>);</li>
<li><a href="/server/tasks.html">How to help</a> with our
<a href="/server/server.html">web server</a>.</li>
- </ul>
-</li>
</ul>
+</div>
</div><!-- for id="content", starts in the include above -->
<!--#include virtual="/server/footer.html" -->
@@ -1036,7 +1445,7 @@
<p class="unprintable">Updated:
<!-- timestamp start -->
-$Date: 2021/02/21 10:41:58 $
+$Date: 2021/04/10 19:31:24 $
<!-- timestamp end --></p>
</div>
</div><!-- for class="inner", starts in the banner include -->
- www/server/standards gnu-website-guidelines.html,
Lorenzo L. Ancora <=
- www/server/standards gnu-website-guidelines.html, Lorenzo L. Ancora, 2021/04/10
- www/server/standards gnu-website-guidelines.html, Therese Godefroy, 2021/04/11
- www/server/standards gnu-website-guidelines.html, Ineiev, 2021/04/12
- www/server/standards gnu-website-guidelines.html, Therese Godefroy, 2021/04/14
- www/server/standards gnu-website-guidelines.html, Therese Godefroy, 2021/04/14
- www/server/standards gnu-website-guidelines.html, Therese Godefroy, 2021/04/14
- www/server/standards gnu-website-guidelines.html, Lorenzo L. Ancora, 2021/04/26
- www/server/standards gnu-website-guidelines.html, Lorenzo L. Ancora, 2021/04/26
- www/server/standards gnu-website-guidelines.html, Therese Godefroy, 2021/04/26
- www/server/standards gnu-website-guidelines.html, Ineiev, 2021/04/27