[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
www/server/staging/standards gnu-website-guidel...
|
From: |
Therese Godefroy |
|
Subject: |
www/server/staging/standards gnu-website-guidel... |
|
Date: |
Sat, 6 Mar 2021 14:16:25 -0500 (EST) |
CVSROOT: /webcvs/www
Module name: www
Changes by: Therese Godefroy <th_g> 21/03/06 14:16:25
Modified files:
server/staging/standards: gnu-website-guidelines.html
Log message:
- Partial rewrite: Standards, Graphics, Symlinks & Refresh sections.
- Restyle some images, add width & height attributes everywhere.
- Reword some headings.
- Minor fixes & edits.
CVSWeb URLs:
http://web.cvs.savannah.gnu.org/viewcvs/www/server/staging/standards/gnu-website-guidelines.html?cvsroot=www&r1=1.38&r2=1.39
Patches:
Index: gnu-website-guidelines.html
===================================================================
RCS file: /webcvs/www/www/server/staging/standards/gnu-website-guidelines.html,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -b -r1.38 -r1.39
--- gnu-website-guidelines.html 5 Mar 2021 12:29:25 -0000 1.38
+++ gnu-website-guidelines.html 6 Mar 2021 19:16:24 -0000 1.39
@@ -2,18 +2,30 @@
<!-- Parent-Version: 1.95 -->
<title>Website Guidelines - GNU Project - Free Software Foundation</title>
<style type="text/css"><!--
+ .reduced-width { width: 55em; }
.important { margin: 2em 0 3em; }
.skiptoc { position: absolute; top: -2.5em; left: 0; }
.toc { position: relative; padding: 1.4em 1.5% 1.6em; max-width: 97%; }
.toc li { list-style: none; }
.emph-box { margin: .7em 0; }
+ dl dt { font-size: 1.125em; }
+ .pict.left {
+ width: 14em; width: max-content;
+ padding: .5em; border: 1px dotted;
+ }
+@media (min-width: 45em) {
+ .columns { column-count: 2; }
+ .pict.left { float:left; margin: .4em 2em .4em 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" -->
+<div class="reduced-width">
<h2>GNU Website Guidelines</h2>
<div class="thin"></div>
@@ -41,22 +53,24 @@
<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 the Main Text</b></a>
- <ul style="inline-block">
+ <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 - local links</a></li>
+ <li><a href="#urls">URLs</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>
</ul></li>
- <li><a href="#styling"><b>Page Styling</b></a>
+ <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>
@@ -65,11 +79,11 @@
<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>Working with CVS Repositories</b></a>
+ <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="#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>
@@ -176,9 +190,10 @@
<ul class="para">
<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> or
-<a href="https://www.w3.org/TR/?status=ret";>Retired Recommendations (Ret)</a>,
-as opposed to Working Drafts (WD), Candidate Recommendations (CR) or
-Proposed Recommendations (PR).</li>
+<a href="https://www.w3.org/TR/?status=ret";>Retired Recommendations (Ret)</a>.
+To ensure wide browser support, avoid new elements and attributes that are
+proposed in Working Drafts (WD), Candidate Recommendations (CR) or Proposed
+Recommendations (PR).</li>
<!--
<li>HTML 5 and CSS3 are preferred over older (X)HTML and CSS standards.</li>
-->
@@ -207,8 +222,8 @@
file to handle this.</li>
<li id="NamingTranslations">If you translate your web page (say,
-<code><var>article</var>.html</code>) in different languages, please
-name the translations <code><var>article.lang</var>.html</code>—
+<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>,
@@ -317,7 +332,7 @@
</ul>
-<h3 id="writing" class="subheader">Writing the Main Text</h3>
+<h3 id="writing" class="subheader">Writing and Editing</h3>
<h4 id="page-contents">Page contents</h4>
@@ -522,7 +537,7 @@
</ul>
-<h3 id="styling" class="subheader">Page Styling</h3>
+<h3 id="styling" class="subheader">Styling</h3>
<h4 id="styling-templated">Styling of templated pages</h4>
@@ -597,6 +612,7 @@
<!-- Is this section really necessary? We are not going to write another
stylesheet for text browsers! -->
+<!--
<h4 id="text-only">Text-only browsers</h4>
<p>Even if the main web development target is composed by modern graphical
@@ -640,7 +656,7 @@
<div class="flex">
<pre class="emph-box">
-<code><-- Discarded by GUI-based web browsers -->
+<code><!-/- Discarded by GUI-based web browsers -/->
<style media="only screen and (grid: 1)">
exp { prop: value; }
…
@@ -658,7 +674,7 @@
<p>…and for external resource (direct) inclusion:</p>
<pre class="emph-box">
-<code><!-- Not downloded by GUI-based web browsers -->
+<code><!-/- Not downloded by GUI-based web browsers -/->
<link href="tty.css" rel="stylesheet" media="only screen and (grid: 1)">
</code></pre>
@@ -672,7 +688,7 @@
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>
@@ -691,10 +707,7 @@
server is really lousy. -->
<li>We do not use background images on our pages, as they make text
-significantly harder to read.<br />
-Images that are not purely decorative must provide <a
-href="https://www.w3.org/WAI/WCAG21/Techniques/failures/F83";>sufficient
-contrast between text, graphs, etc., and background</a>.</li>
+significantly harder to read.</li>
<li>In the past, GIFs have had patent problems. However, now that
the IBM and Unisys patents (and other patents worldwide that are
@@ -716,24 +729,29 @@
<h4 id="image-basics">Basic recommendations</h4>
<ul class="para">
+<li>Images that are not purely decorative must 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 style="float: left; text-align: center; border: 1px dotted;
- padding: 0.5em; margin: .4em 1.5em .4em 0">
- <p>Loaded in graphic browser:<br />
+<div class="pict left">
+ <p style="margin: 0 0 1em">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" />
+ 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" />
+ style="width: 5em; height: auto; border: 2px solid gray"
+ width="80px" height="80px" />
</samp>
</p>
</div>
@@ -753,11 +771,16 @@
<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, as a courtesy to users of
+CSS-unaware browsers (see some examples below).<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>Adjust image width or height in a style attribute, using scalable
+<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>
@@ -765,22 +788,20 @@
title="GNU stamp"
alt=" [Stamp with an abstract GNU head] "
style="width: 10em; height: auto; float: right; margin: .5em 0 .5em 1.5em"
- width="77px"
- height="77px" />
+ 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="77px"
- height="77px" />
+ 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.<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 layout reflows.</p></li>
+<p>This way, the page will look the same in CSS-aware browsers if the
+reader increases or decreases font size.
+</p></li>
<li>Link all images that are displayed throughout the website to the
relevant page, usually in <code>/graphics/</code>.
@@ -806,7 +827,7 @@
title="GNU stamp"
alt=" [Stamp with a GNU head] "
style="width: 8em; height: auto"
- width="129px" height="122px" />
+ width="128px" height="128px" />
</a></p>
<pre class="emph-box">
@@ -816,7 +837,7 @@
title="GNU stamp"
alt="&nbsp;[Stamp with a GNU head]&nbsp;"
style="width: 8em; height: auto"
- width="129px" height="122px" />
+ width="128px" height="128px" />
</a>
</p>
</pre>
@@ -826,28 +847,30 @@
<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;
+<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 wide" style="width: 14em">
+<div class="pict medium" style="width: 15em">
<img src="/graphics/gnu-post/GNU-stamp.png"
title="GNU stamp"
- alt=" [Stamp with a GNU head] "/>
+ alt=" [Stamp with a GNU head] "
+ width="225px" height="225px" />
</div>
<pre class="emph-box">
-<div class="pict wide" style="width: 14em">
+<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;" />
+ 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
+inherit <code>max-width</code> on all browsers (i.e., always test for
compatibility when you need to put a table beside a picture).</p>
<div style="clear: both"></div>
</li>
@@ -872,7 +895,7 @@
provide a link to a page from ours. They are listed below, in order of
descending general importance.</p>
-<dl style="font-size: 1.125em">
+<dl>
<dt>What's the context of the link?</dt>
<dd>
@@ -1019,7 +1042,7 @@
</dl>
-<h3 id="repo" class="subheader">Working with CVS Repositories</h3>
+<h3 id="repo" class="subheader">Technical tips</h3>
<h4 id="cvs">Basic CVS commands</h4>
@@ -1035,8 +1058,8 @@
<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:</p>
<pre class="emph-box">
<kbd>cvs -z3 -d:ext:<var>username</var>@cvs.savannah.gnu.org:/web/www co
www</kbd>
@@ -1047,8 +1070,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>
@@ -1065,7 +1088,7 @@
<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
+however, that the <var>fooproject</var> and main repositories are independent.
The
working directories can be anywhere in your filesystem.</p>
<p><em>Webmasters, please read <a
@@ -1099,7 +1122,7 @@
</li>
<li>
-<p>Perform the commit (no need for <code>cvs add</code> if the file is
+<p>Perform the commit (no need for <kbd>cvs add</kbd> if the file is
already in the repository):</p>
<pre class="emph-box">
@@ -1158,7 +1181,8 @@
ignored.</li>
</ul>
-<p>Here is an example of <code>.symlinks</code>:</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.
@@ -1178,42 +1202,54 @@
</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 <code>.symlinks</code> 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, as seen in
the <a href="#filenames">Filenames</a> section.
-When you need such redirections, use the
-<a href="#htaccess">htaccess mechanism</a>.</p>
+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 handling of symlinks happens on www.gnu.org
+<p id="cron">[*] 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 (don't use)</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>
+<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>">
</code></p>
-<p><em>Note:</em> Please don't use <code>http-equiv="refresh"</code>
-to refresh a page, because automatic refresh has <a
+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 an “update now”
-button.</p>
+issues</a>. If a page needs frequent updating, provide an
+“update now” button.</li>
+</ul>
<h4 id="scripts">Server-side scripts</h4>
@@ -1265,8 +1301,8 @@
<li>The W3C <a href="https://www.w3.org/Provider/Style/Overview.html";>
Style Guide</a>, although published in the 90's, gives recommendations
for web writing that are still valid today.</li>
- </ul>
-</li>
+</ul>
+
<h4 id="internal-resources">Internal resources</h4>
@@ -1303,11 +1339,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>
+</div>
</div><!-- for id="content", starts in the include above -->
<!--#include virtual="/server/footer.html" -->
@@ -1367,7 +1404,7 @@
<p class="unprintable">Updated:
<!-- timestamp start -->
-$Date: 2021/03/05 12:29:25 $
+$Date: 2021/03/06 19:16:24 $
<!-- timestamp end --></p>
</div>
</div><!-- for class="inner", starts in the banner include -->
- www/server/staging/standards gnu-website-guidel..., Therese Godefroy, 2021/03/05
- www/server/staging/standards gnu-website-guidel...,
Therese Godefroy <=
- www/server/staging/standards gnu-website-guidel..., Therese Godefroy, 2021/03/06
- www/server/staging/standards gnu-website-guidel..., Lorenzo L. Ancora, 2021/03/06
- www/server/staging/standards gnu-website-guidel..., Lorenzo L. Ancora, 2021/03/06
- www/server/staging/standards gnu-website-guidel..., Therese Godefroy, 2021/03/07
- www/server/staging/standards gnu-website-guidel..., Therese Godefroy, 2021/03/07