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

[Therese Godefroy]

CVSROOT:        /webcvs/www
Module name:    www
Changes by:     Therese Godefroy <th_g> 21/02/23 08:49:59

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

Log message:
        Minor rewording; add comments after passages that are unclear to me.

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

Patches:
Index: gnu-website-guidelines.html
===================================================================
RCS file: /webcvs/www/www/server/staging/standards/gnu-website-guidelines.html,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -b -r1.18 -r1.19
--- gnu-website-guidelines.html 22 Feb 2021 22:13:33 -0000      1.18
+++ gnu-website-guidelines.html 23 Feb 2021 13:49:58 -0000      1.19
@@ -89,6 +89,7 @@
 <li>The GNU website gives priority to software covered by either
 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>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
@@ -112,11 +113,12 @@
 <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>
+the newer entries should be first; in other words, preserve reverse
+chronological order.</li>
 
 <li>Pages should not load CSS from servers other than those run
 by the FSF.</li>
@@ -256,7 +258,7 @@
 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
@@ -266,7 +268,7 @@
 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>
+the same file, and double-check that the anchor actually works.</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>.
@@ -288,12 +290,11 @@
 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
-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
+<li>We encourage FTP sites to use one directory for each package. This
+directory should contain all versions of the package as well as all
+related information (<code>README</code> file, list of available
+versions, documentation, fonts, etc.) This will ensure that the package
+URL does not need updating, 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>
@@ -312,11 +313,12 @@
 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
+of the page, they will have a copy of the email address they can use without
 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, etc.)
+advanced examples of how to use mailto URIs to specify a subject, the
+body, etc.
 </p></li>
 
 <li>When embedding static resources like videos that are not in
@@ -352,7 +354,7 @@
 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>&lt;html&gt;</code>, <code>&lt;head&gt;</code>,
-<code>&lt;title&gt;</code>, <code>&lt;body&gt;</code>, etc. when using HTML 4,
+<code>&lt;title&gt;</code> and <code>&lt;body&gt;</code> when using HTML 4,
 and always include the appropriate DTD or Schema reference in all markup
 standards older than HTML 5.
 This appeases overly pedantic web browsers.</li>
@@ -404,7 +406,7 @@
       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>
@@ -433,11 +435,11 @@
 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 &ldquo;skip link&rdquo; to the main text
-is another option.</li>
+is another option (see the top of this page for an example).</li>
 </ul>
 
 
@@ -550,7 +552,7 @@
 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, w3m, etc.) executed
+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>
 
@@ -1073,7 +1075,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 (&ldquo;#&rdquo;) are ignored.</li>
@@ -1082,7 +1085,7 @@
 ignored.</li>
 </ul>
 
-<p>Here is an example of a .symlinks file:</p>
+<p>Here is an example of <code>.symlinks</code>:</p>
 
 <pre class="emph-box">
 # Make a link named l.html to a target t.html.
@@ -1103,7 +1106,7 @@
 
 <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
+rewriting.  Thus 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
@@ -1115,7 +1118,7 @@
 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
+<p>These days, 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>
 
@@ -1133,9 +1136,10 @@
   url=https://www.gnu.org/<var>target</var>"&gt;
 </code></p>
 
-However, the latter must be implemented so as
+<p>However, the latter must be implemented so as
 <a href="https://www.w3.org/WAI/WCAG21/Techniques/failures/F41";
-rel="noopener">WCAG 2.1 F41</a> does not occur in any circumstance.
+rel="noopener">WCAG 2.1 F41</a> does not occur in any circumstance.</p>
+<!-- Please explain -->
 
 <h4 id="scripts">Server-side scripts</h4>
 
@@ -1287,7 +1291,7 @@
 
 <p class="unprintable">Updated:
 <!-- timestamp start -->
-$Date: 2021/02/22 22:13:33 $
+$Date: 2021/02/23 13:49:58 $
 <!-- timestamp end --></p>
 </div>
 </div><!-- for class="inner", starts in the banner include -->