www/server/staging/standards gnu-website-guidel...

[Therese Godefroy]

CVSROOT:        /webcvs/www
Module name:    www
Changes by:     Therese Godefroy <th_g> 21/02/22 14:29:43

Modified files:
        server/staging/standards: gnu-website-guidelines.html 

Log message:
        - Fix validation, typos, etc.
        - Adjust margins around images.
        - Rewrite the part about removing id's; add an example.
        - Link once to each stylesheet.

CVSWeb URLs:
http://web.cvs.savannah.gnu.org/viewcvs/www/server/staging/standards/gnu-website-guidelines.html?cvsroot=www&r1=1.16&r2=1.17

Patches:
Index: gnu-website-guidelines.html
===================================================================
RCS file: /webcvs/www/www/server/staging/standards/gnu-website-guidelines.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -b -r1.16 -r1.17
--- gnu-website-guidelines.html 21 Feb 2021 20:19:14 -0000      1.16
+++ gnu-website-guidelines.html 22 Feb 2021 19:29:42 -0000      1.17
@@ -3,6 +3,11 @@
 <title>Website Guidelines - GNU Project - Free Software Foundation</title>
 <style type="text/css"><!--
   .summary li { list-style: none; }
+  .emph-box { margin: .7em 0; }
+@media (min-width: 55em) {
+  .flex { display: flex; flex-direction: row; }
+  .flex > * { width: 49%; }
+}
 --></style>
  <!--#include virtual="/server/standards/po/gnu-website-guidelines.translist" 
-->
 <!--#include virtual="/server/banner.html" -->
@@ -199,7 +204,7 @@
 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 in lowercase).
+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>
@@ -225,7 +230,7 @@
 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, 3rd-party domains.</li>
+recommended when linking to external, third-party domains.</li>
 
 <li>Collections of files produced automatically from Texinfo source
 contain links with relative file names.  They always refer to another
@@ -245,10 +250,25 @@
 <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 <code>id</code>
-attribute from any header tag (<code>&lt;h1 id="example"&gt;&hellip;</code>,
-<code>&lt;h2&hellip;</code>, <code>&lt;h3&hellip;</code>, &hellip;) or
-anchor (e.g. <code>&lt;a id="example"&gt;#example&lt;/a&gt;</code>).</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 none, create one.
+Here is a typical example from the Philosophy main page:
+
+<pre class="emph-box">
+<samp>&lt;!-- please leave both these ID attributes here. ... --&gt;
+[...]
+&lt;div id="TOCFreedomOrganizations"&gt;
+&lt;p id="FreedomOrganizations"&gt;We also keep a list of
+&lt;a href="/links/links.html#FreedomOrganizations"&gt;Organizations
+that Work for Freedom in
+Computer Development and Electronic Communications&lt;/a&gt;.&lt;/p&gt;
+&lt;/div&gt;</samp>
+</pre>
+
+Please avoid moving the old <code>id</code> to a translatable string.
+Translators will thank you!
+</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
@@ -278,8 +298,7 @@
 going back to their web browser.  If the person doesn't have a web
 page, leave the name unanchored.  See
 <a href="https://tools.ietf.org/html/rfc6068#section-6";>RFC 6068</a> for
-advanced examples of mailto URIs (ie. to specify a subject, the body, 
&hellip;).
-
+advanced examples of mailto URIs (ie. to specify a subject, the body, etc.)
 </p></li>
 
 <li>When embedding static resources like videos that are not in
@@ -333,7 +352,7 @@
 Some browsers use this information to allow users to easily report
 problems they find on a page.</li>
 
-<li>The first header tag, <code>&lt;h<var>N</var>&gt;</code>, should have
+<li>The first header tag, generally <code>&lt;h1&gt;</code> or 
<code>&lt;h2&gt;</code>, should have
 its text duplicated at the start of the <code>&lt;title&gt;</code> tag.
 The <code>&lt;title&gt;</code> tag
 is used by many browsers in menus like the history and bookmarks lists,
@@ -387,6 +406,7 @@
 and
 <a href="https://www.w3.org/WAI/WCAG21/Techniques/failures/F91";>WCAG 2.1 
F91</a>
 do not occur in any circumstance.</li>
+<!-- Please explain -->
 
 <li>Some people like to organize links as a menu to
 the left or right of the main text when using graphical browsers.  That
@@ -433,10 +453,11 @@
 <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>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>.
+<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&nbsp;2) <a
 
href="https://yui.github.io/yui2/docs/yui_2.9.0_full/reset/index.html";>reset</a>
 and <a
@@ -444,12 +465,16 @@
 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 &lt;style&gt; element, between the SSI directives
@@ -471,15 +496,15 @@
 
 <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>
@@ -487,7 +512,7 @@
 </li>
 
 <li>Translators maintain stylesheets (<code>/style.<var>lang</var>.css</code>)
-that modify <a href="/layout.css"><code>layout.css</code></a> according to
+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>.</li>
 </ul>
@@ -501,64 +526,66 @@
 
 <ul class="para">
 <li>The webpages which are meaningful without media files (videos, graphics,
-photos, animations, &hellip;) may be tested on modern, stable text-only 
browsers
+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 (ie. lynx, elinks, w3m, &hellip;) executed
+stable and modern text mode browsers (ie. lynx, elinks, w3m, etc.) 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
-web browsers.<br />
-The correct way to prevent graphical web browsers from parsing
-a CSS fragment dedicated to text-only web browsers is:
-<code>
-<div class="emph-box" style="display: flex; flex-direction: row; margin: 0px">
-    <pre style="width: 50%; padding: 0.5em">
-/* Discarded by GUI-based web browsers */
+web browsers.
+
+<p>The correct way to prevent graphical web browsers from parsing
+a CSS fragment dedicated to text-only web 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; }
     &hellip;
-}</pre>
-    <pre style="width: 49%; padding: 0.5em">
-/* Not downloded by GUI-based web browsers */
+}</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);
-</pre>
+@import "tty.css" screen and (grid: 1);</code></pre>
 </div>
-</code>
-</code>
-&hellip;for in-page block embedding:
-<div class="emph-box" style="display: flex; flex-direction: row; margin: 0px">
-    <pre style="width: 50%; padding: 0.5em">
-&lt;-- Discarded by GUI-based web browsers -->
+
+<p>&hellip;for in-page block embedding:</p>
+
+<div class="flex">
+    <pre class="emph-box">
+<code>&lt;-- Discarded by GUI-based web browsers -->
 &lt;style media="only screen and (grid: 1)">
     exp { prop: value; }
     &hellip;
-&lt;/style></pre>
-    <pre style="width: 49%; padding: 0.5em">
-&lt;style &hellip;&nbsp;>
+&lt;/style></code></pre>
+    <pre class="emph-box">
+<code>&lt;style &hellip;&nbsp;>
     /* Discarded by GUI-based web browsers */
     @media only screen and (grid: 1) {
         exp { prop: value; }
         &hellip;
     }
-&lt;/style></pre>
+&lt;/style></code></pre>
 </div>
-&hellip;and for external resource (direct) inclusion:
-<code>
+
+<p>&hellip;and for external resource (direct) inclusion:</p>
+
 <pre class="emph-box">
-&lt;!-- Not downloded by GUI-based web browsers -->
+<code>&lt;!-- Not downloded by GUI-based web browsers -->
 &lt;link href="tty.css" rel="stylesheet" media="only screen and (grid: 1)">
-</pre>
-</code>
-Always double-check the result on different web browsers.
+</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,
@@ -566,13 +593,14 @@
 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">10. Use of Graphics</h3>
 
 <ul class="para">
 <li>The use of graphics should be minimized, so pages load fast
 over slow links, especially animations.<br />
 Ideally, the page loading time should remain under 3000 ms
-(with caching and proxying disabled), so when it exceeds this limit consider
+(with caching and proxying disabled). So, when it exceeds this limit, consider
 using lossless compression or smaller images.</li>
 
 <li>We do not use background images on our pages, as they make text
@@ -580,6 +608,8 @@
 Non-decorative elements must be implemented so as
 <a href="https://www.w3.org/WAI/WCAG21/Techniques/failures/F83";>WCAG 2.1 
F83</a>
 does not occur in common use cases.</li>
+<!-- Please explain what this failure is. The W3C documents are nearly
+impossible to understand for the average reader. -->
 
 <li>In the past, GIFs have had patent problems.  However, now that
 the IBM and Unisys patents (and other patents worldwide that are
@@ -598,24 +628,23 @@
 
 <li>Always have a textual alternative for in-line images, to ensure
 indexability by search engines and accessibility.  For instance:
-<div style="clear: both"></div>
 
 <div style="float: left; text-align: center; border: 1px dotted;
-            padding: 0.5em; margin: 0em 1em">
-    <p>Loaded in graphic browser:<br>
+            padding: 0.5em; margin: .7em 1em .7em 0">
+    <p>Loaded in graphic browser:<br />
     <img src="/graphics/gnu-post/Alternative-GNU-stamp.png"
           title="BRIEF TEXT"
           alt="&nbsp;[DESCRIPTIVE TEXT]&nbsp;"
-          style="width: 5em; height: auto; border: 2px solid gray">
+          style="width: 5em; height: auto; border: 2px solid gray" />
     </p>
-    <p>Loading failed or text reader:<br>
+    <p>Loading failed or text reader:<br />
     <samp>
         <img src="/graphics/gnu-post/Alternative-GNU-stamp.invalid"
               title="BRIEF TEXT"
               alt="&nbsp;[DESCRIPTIVE TEXT]&nbsp;"
-              style="width: 5em; height: auto; border: 2px solid gray">
-        </p>
+              style="width: 5em; height: auto; border: 2px solid gray" />
     </samp>
+    </p>
 </div>
 
 <pre class="emph-box">
@@ -629,8 +658,9 @@
 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.
 <div style="clear: both"></div>
+</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
@@ -643,7 +673,7 @@
 <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: 0em 1em"
+      style="width: 10em; height: auto; float: right; margin: .7em 0 .7em 1em"
       width="77px"
       height="77px" />
 
@@ -651,7 +681,7 @@
 &lt;img src="/graphics/gnu-post/Alternative-GNU-stamp.png"
       title="GNU stamp"
       alt="&amp;nbsp;[Stamp with an abstract GNU head]&amp;nbsp;"
-      style="width: 10em; height: auto;"
+      style="width: 10em; height: auto; float: right; margin: .5em 0 .5em 1em"
       width="77px"
       height="77px" /&gt;
 </pre>
@@ -662,8 +692,8 @@
 the page loading phase, preventing incremental layout reflows.</li>
 
 <li>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="/server/standards/README.webmastering.html#templating">templated 
pages</a>
+<code>layout.css</code> (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
@@ -672,31 +702,32 @@
 <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 <code>IMAGES</code> section 
of
-the <a href="/layout.css"><code>layout.css</code></a> stylesheet. You can 
adjust
+the <code>layout.css</code> stylesheet. You can adjust
 the width in a style attribute if none of the predefined ones fits your needs,
 for instance:
 <div style="clear: both"></div>
 
-<div class="pict wide" style="width: 12em">
+<div class="pict wide" style="width: 14em">
     <img src="/graphics/gnu-post/GNU-stamp.png"
-          title="Head of a GNU"
-          alt="&nbsp;[DESCRIPTIVE TEXT]&nbsp;"/>
+          title="GNU stamp"
+          alt="&nbsp;[Stamp with a GNU head]&nbsp;"/>
 </div>
 
 <pre class="emph-box">
-&lt;div class="pict wide" style="width: 12em"&gt;
+&lt;div class="pict wide" style="width: 14em"&gt;
     &lt;img src="/graphics/gnu-post/GNU-stamp.png"
           title="GNU stamp"
           alt="&amp;nbsp;[Stamp with a GNU head]&amp;nbsp;" /&gt;
 &lt;/div&gt;
 </pre>
 
-Please note that the <code>div</code> container is necessary for
+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 nested <code>table</code> may not
-inherit <code>max-width</code> on all web browsers (ie. always test for
-compatibility when you need to put a table beside a picture).</li>
+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).
 <div style="clear: both"></div>
+</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
@@ -715,8 +746,8 @@
 &lt;p class="imgleft"&gt;
   &lt;a href="/graphics/gnu-post/"&gt;
     &lt;img src="/graphics/graphics/gnu-post/GNU-stamp.png"
-          title="Head of a GNU"
-          alt="&nbsp;[Black and white sketch of the Head of a GNU]&nbsp;"
+          title="GNU stamp"
+          alt="&nbsp;[Stamp with a GNU head]&nbsp;"
           style="width: 8em; height: auto"
           width="129px" height="122px" /&gt;
   &lt;/a&gt;
@@ -811,11 +842,11 @@
 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&mdash;and not much else&mdash;would be acceptable:
+text&mdash;and not much else&mdash;would be acceptable:</p>
 
-<blockquote>w3 is a web browser for GNU Emacs, similar to Internet Explorer.
+<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.</blockquote>
+proprietary Unix systems, and Windows.</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
@@ -833,8 +864,8 @@
 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>GNOME is part of the GNU Project, and is free software (sometimes
-referred to as open source software).</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
@@ -869,13 +900,13 @@
 primarily about free software, the policies do not hold full force for
 them.</p>
 
-<p>As a final explanation:<br>
-<blockquote>
+<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 &ldquo;free software&rdquo;
 rather than &ldquo;open source&rdquo;.  We do, however, require that they not
 promote any nonfree software. &mdash; <i>RMS</i>
-</blockquote></p>
+</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
@@ -1099,9 +1130,10 @@
 <h3 id="UsefulResources" class="subheader">Appendix 3 - Useful Resources</h3>
 
 
-<ul class="para">
 <h4>External resources</h4>
-<p>This section contains references managed by 3rd-parties.</p>
+
+<p>This section contains references managed by third parties.</p>
+
 <ul>
     <li>We follow the guidelines of the <a
     href="https://www.anybrowser.org/campaign/"; rel="noopener"
@@ -1130,7 +1162,9 @@
     ensures accessibility for a wide range of people with disabilities.</li>
 </ul>
 
+
 <h4>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>
@@ -1227,7 +1261,7 @@
 
 <p class="unprintable">Updated:
 <!-- timestamp start -->
-$Date: 2021/02/21 20:19:14 $
+$Date: 2021/02/22 19:29:42 $
 <!-- timestamp end --></p>
 </div>
 </div><!-- for class="inner", starts in the banner include -->