www/server/standards README.webmastering.html

[Therese Godefroy]

CVSROOT:        /webcvs/www
Module name:    www
Changes by:     Therese Godefroy <th_g> 17/03/11 05:03:51

Modified files:
        server/standards: README.webmastering.html 

Log message:
        Extensive rewrite of 'Structure and navigation' into 'Editing and 
creating web pages'.

CVSWeb URLs:
http://web.cvs.savannah.gnu.org/viewcvs/www/server/standards/README.webmastering.html?cvsroot=www&r1=1.187&r2=1.188

Patches:
Index: README.webmastering.html
===================================================================
RCS file: /webcvs/www/www/server/standards/README.webmastering.html,v
retrieving revision 1.187
retrieving revision 1.188
diff -u -b -r1.187 -r1.188
--- README.webmastering.html    2 Nov 2015 00:25:20 -0000       1.187
+++ README.webmastering.html    11 Mar 2017 10:03:50 -0000      1.188
@@ -1,4 +1,4 @@
-<!--#include virtual="/server/header.html" -->
+<!--#include virtual="/server/html5-header.html" -->
 <!-- Parent-Version: 1.77 -->
 <title>Webmastering Guidelines - GNU Project - Free Software Foundation</title>
 <!--#include virtual="/server/gnun/initial-translations-list.html" -->
@@ -21,7 +21,7 @@
 
 <a href="#working">Working as a webmaster</a> -
 <a href="#rt">Using RT</a> -
-<a href="#structure">Site structure</a> -
+<a href="#structure">Editing and creating web pages</a> -
 <a href="#announcements">Announcements</a> -
 <a href="#pollinking">Linking policies</a> -
 <a href="#mirrors">Mirrors</a> -
@@ -452,80 +452,100 @@
 webmasters get several hundred spams every day.</p>
 
 
-<h3 id="structure">Site structure and navigation</h3>
+<h3 id="structure">Editing and creating web pages</h3>
+
+<h4>Site structure and navigation</h4>
 
 <p>The site is divided up into directories by topic&mdash;there's a
 directory for GNU project information and history, a directory for our
 licenses, and so on.  Each of these directories has a page sharing the
 same name; for example, the /philosophy directory has a page,
-philosophy.html.  This page is the main page for this section of the
+philosophy.html, which is the main page for this section of the
 site, and so should provide access to all the material within that
 directory.</p>
 
-<p>In turn, every other page in the directory should link back to this
-main page, to allow people to get more information about a given topic.</p>
-
-<p>Links should include a full path, if possible.  For example, within a
-specific article in the philosophy section, link to
-/philosophy/philosophy.html, rather than just philosophy.html.  This
+<p>The main directories (/gnu, /philosophy, etc.) are accessible via
+navigation bars, but some other important directories (e.g. /proprietary)
+are not (yet?).  Every page in these directories should link back to the
+main page, to allow people to get more information about the topic at
+hand.</p>
+
+<p>Links should include a full path, if possible.  For example, within
+a specific article in the /proprietary directory, link to
+/proprietary/proprietary.html, rather than just proprietary.html.  This
 eases maintenance of the site as things get moved around.</p>
 
 <p>Some pages are dynamic and should include a link with the full
 hostname; a notable example is the Free Software Directory.  So, we link
 to that with the URL <tt>&lt;http://www.gnu.org/directory&gt;</tt>.</p>
 
-<p>Our pages make use of SSI and CSS to do a variety of things.  At
-present, our pages should do an include of
-<tt>&lt;/server/banner.html&gt;</tt>, as shown in
-<tt>&lt;/server/standards/boilerplate.html&gt;</tt>.  This reads
-<tt>/style.css</tt>, which in turn reads <tt>/combo.css (Yahoo's User
-Interface CSS for <a
-href="http://developer.yahoo.com/yui/reset/";>reset</a>, <a
-href="http://developer.yahoo.com/yui/grids/";>grids</a>, <a
-href="http://developer.yahoo.com/yui/fonts/";>fonts</a> and <a
-href="http://developer.yahoo.com/yui/base/";>base</a></tt> plus
-<tt>/layout.css</tt>, which contains gnu.org specific CSS formatting. In
-addition, users of mobile devices (cellphones, music players, etc) are
-sent to <tt>/mini.css</tt> instead. This stylesheet is just the YUI
-reset and base stylesheets, as mobile devices typically have minimal
-need for various fonts and no need for fancy layouts.</p>
-
-<p>Historical pages refer to <tt>/gnu.css</tt> which also loads the
-mobile CSS, as these pages are usually very basic, plain pages with
-little or no formatting.</p>
-
-<h4>A little more on Yahoo's User Interface CSS</h4>
-
-<p>YUI is a project of Yahoo (the search engine company) to provide a
-set of standard userfaces for the web. They're licensed under the
-modified BSD-license (3 clause), here's a quick run down of what they do:</p>
-
-<dl>
-  <dt>reset</dt>
-  <dd>As all the major browsers, both free and
-  nonfree are different, reset reverts all their specific default CSS
-  to a very basic level, allowing the developer to provide her own
-  styles, or use a standard library. In our case, we use
-  <b>base</b>.</dd>
-  <dt>grids</dt>
-  <dd>Laying out pages in an
-  attractive way can be tricky using CSS -- YUI provides a mechanism
-  for this that is pretty attractive. Using the <a
-  href="http://developer.yahoo.com/yui/grids/";>documentation for
-  grids</a>, or the <a
-  href="http://developer.yahoo.com/yui/grids/builder/";>interactive
-  grids builder</a>, the discerning developer can quickly build
-  attractive and functional grid-based layouts, which are the <a 
href="http://en.wikipedia.org/wiki/Grid_%28page_layout%29";>cornerstone of good 
typographical practice</a> without resorting to tables, which is considered <a 
href="http://www.w3.org/TR/WCAG10-HTML-TECHS/#tables";>a bad practice for 
accessibility</a>.</dd>
-  <dt>fonts</dt>
-  <dd>Fonts are also a mess on the web, as many gnu.org developers will tell 
you, we have long wrestled with the problem of how gnu.org should handle fonts. 
From the original 'no fonts' design, through the many interactions of Matt 
Lee's current GNU designs, fonts have been an often-debated problem for the 
site. YUI's fonts takes care of this, by use of much testing on the part of 
Yahoo.</dd>
-  <dt>base</dt>
-  <dd>Base does the final part of the job that <b>reset</b> does &mdash; 
provides a consistent definition for all the major elements on a page. With 
base, headings, paragraphs and lists are consistent in their margins and 
padding across all browsers.</dd>
-</dl>
+<h4>Page templating</h4>
+
+<p>All new pages in the main part of gnu.org should use a <a
+href="/server/standards/boilerplate.html">boilerplate</a> that includes 
+additional files by means of Apache SSIs. Please don't start out with
+an existing page to create a new one; use the <a
+href="http://web.cvs.savannah.gnu.org/viewvc/*checkout*/www/server/standards/boilerplate.html?root=www&amp;content-type=text%2Fplain";>
+original source</a> of the boilerplate instead. The latter was designed for
+package home pages; the instructions for normal articles are as follows:</p>
+
+<ol>
+<li>In the line starting with &ldquo;Parent-Version:&rdquo;, remove the
+&ldquo;$Revision...$&rdquo; from around the revision number, leaving just
+Parent-Version: and the number.</li>
+
+<li>Replace &ldquo;Baz&rdquo; in the <tt>title</tt> and <tt>h2</tt> elements
+with the title of the article.</li>
+
+<li>Replace everything between <tt>h2</tt> and the end of the content div
+&nbsp;(<tt>&lt;/div&gt;&lt;!-- for id="content"&hellip;</tt>)&nbsp; with the
+text of the article, making sure it follows the <a
+href="/server/fsf-html-style-sheet.html">stylesheet guidelines</a>.</li>
+
+<li>Remove the instructions at the top of the page (but not the SSI
+directives!)</li>
+</ol>
+ 
+<h4>Page styling</h4>
+
+<p>Generic styling for desktops and smartphones is provided by two CSS:
+<tt>/combo.css</tt> (version 2 of Yahoo's User Interface CSS for <a
+href="http://web.archive.org/web/20070321054317/http://developer.yahoo.com/yui/reset/";>reset</a>,
 <a
+href="http://web.archive.org/web/20070321054339/http://developer.yahoo.com/yui/grids/";>grids</a>,
 <a
+href="http://web.archive.org/web/20070321054126/http://developer.yahoo.com/yui/fonts/";>fonts</a>
 and <a
+href="http://web.archive.org/web/20070812114609/http://developer.yahoo.com/yui/base/";>base</a>),
 plus
+<tt>/layout.css</tt>, which contains gnu.org-specific CSS formatting.</p>
+
+<p>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
+that include header.html and banner.html. If the style applies to a single
+element, it should be normally be added as an attribute.</p>
+
+<p><em>Note about grids:</em>&nbsp; Very few pages currently use them. In the
+event you'd like to create one that does, good starting points may be
+found in <a
+href="https://yuilibrary.com/yui/docs/cssgrids/";>YUI version 3</a>, and <a
+href="https://purecss.io/grids/";>Pure Grids</a>. The components provided by
+these libraries are licensed under the modified (3-clause) BSD license.</p>
+
+<p>Mobile devices with very limited resources use <tt>/mini.css</tt>.
+This stylesheet is just the YUI reset and base stylesheets, as these
+devices typically have minimal need for various fonts and no need for
+fancy layouts.</p>
+
+<p>Printers use <tt>/print.css</tt>. Note that the header, navigation
+bars and footer (except copyright and license) are unprintable.</p>
+
+<p>Historical pages (unmaintained translations for the most part) refer
+to <tt>/gnu.css</tt> which also loads the mobile CSS, as these pages are
+usually very basic, plain pages with little or no formatting.</p>
+
+<p>Some software manuals use a dedicated CSS, <tt>/style.css</tt>.</p>
 
 
 <h3 id="announcements">Announcements: directory links, sitemap, home page</h3>
 
-<p>When significant new content is added, notices should be put up to
+<p>When significant new material is added, notices should be put up to
 make people aware of it:</p>
 
 <ul>
@@ -1282,7 +1302,7 @@
 
 <p class="unprintable">Updated:
 <!-- timestamp start -->
-$Date: 2015/11/02 00:25:20 $
+$Date: 2017/03/11 10:03:50 $
 <!-- timestamp end -->
 </p>
 </div>