This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: [wwwdocs] Make codingconventions.html pass W3 validator.
Your links were a big help. Hopefully, I can return the favor with
a few comments and suggestions. Note that I did not understand
everything here, so my comments and suggestions may be wrong.
If they are, please use my mistakes as data!
On 6/20/12, Gerald Pfeifer <gerald@pfeifer.com> wrote:
> First of all you made me realize that we were missing a
> cross-link from http://gcc.gnu.org/projects/web.html to
> http://gcc.gnu.org/contribute.html#webchanges which the first
> patch included below does now.
We are also missing a direct link from contribute.html#webchanges
to projects/web.html. More importantly, I think we are missing the
context, which is that the web pages are a projects. I think that
context is better understood in one place. So, I suggest essentially
replacing contribute.html#webchanges with a link to the project page.
Specifically, I think contribute.html#webchanges should say
<h2><a name="webchanges">Web Site Changes</a></h2>
<p>The GCC web site is managed as its own
<a href="http://gcc.gnu.org/projects/web.html>project</a>.
Visit that page to understand the sources and the process for
modifying them.</p>
The cvs.html page should be laser-focussed on the CVS instructions.
It mostly is, but the introductory paragraph could be clearer.
I think that paragraph should say
<p>Our web pages and related scripts are available via our CVS
repository. You can
<a href="http://gcc.gnu.org/cgi-bin/cvsweb.cgi/wwwdocs/";>browse
them online</a>.
To change them, you must understand and contribute to the
<a href="projects/web.html">web page project</a>.</p>
Some of the other text might be clearer as well. I suggest
the following text, mostly modified from what is already there.
<hr />
<h2 name="checkout">Checking out copies of the CVS repository</h2>
<p>Assuming you have both CVS and SSH installed,
you can check out the web pages as follows:</p>
<ol>
<li>Set CVS_RSH in your environment to <code>ssh</code>.</li>
<li>
<p>Use the following command to check out the sources.</p>
<blockquote><code>
cvs -q -d <var>repository</var> checkout -P <var>module</var>
</code></blockquote>
<p>where
<code><var>module</var></code> is <code>wwwdocs</code>
<code><var>repository</var></code> is</p>
<dl>
<dt>for read-only anonymous checkouts</dt>
<dd><code>:pserver:cvs@gcc.gnu.org:/cvs/gcc</code></dd>
<dt>for read/write named checkouts</dt>
<dd><code>:ext:<var>username</var>@gcc.gnu.org:/cvs/gcc</code>
where <var>username</var> is your user name at gcc.gnu.org</dd>
</dl>
</li>
</ol>
<hr />
<h2><a name="checkin">Checking in a change</a></h2>
<p>When you check in changes to our web pages,
they will automatically be checked out,
modified to add additional informationa,
and put into the web server's data area.</p>
<p>The following is a very quick overview of how to check in a change.
We recommend you list files explicitly to avoid accidental checkins
and prefer that each checkin be of a complete, single logical change.</p>
<ol>
<li>Sync your sources with the master repository
via "<code>cvs update</code>".
This will also identify any files in your local tree
that you have modified.</li>
<li>We recommend reviewing the output of "<code>cvs diff</code>"
after applying a patch to a local tree.</li>
<li>Use "<code>cvs commit</code>" to check in the patch.</li>
<li>Upon successful checkin a message will be sent to the
gcc-cvs-wwwdocs mailing list.</li>
</ol>
<hr />
<h2><a name="system">The host system</a></h2>
<p>The setup of the machine running the gcc.gnu.org site
is also available, through
<a href="http://sourceware.org/cgi-bin/cvsweb.cgi/?cvsroot=sourceware";>
cvsweb</a> and anonymous read-only CVS.
Use the same procedure as above,
but for <code><var>repository</var></code> use
<code>:pserver:anoncvs@gcc.gnu.org:/cvs/sourceware</code>
<code><var>module</var></code> use <code>infra</code>.</p>
So, coming back to the all-important project page. That page could
be clearer about communicating the project and its process.
I suggest the following.
<p>This web pages project manages
<a href="contribute.html#webchanges">contributions to GCC's web pages.</p>
You can view and modify the web site sources with our
<a href="cvs.html">instructions for accessing the web CVS repository</a>.
<hr />
<h2>Making Changes</h2>
<p>Changes to the web site must
<a href="http://validator.w3.org/";>validate</a> as XHTML 1.0
Transitional. The web pages as checked into CVS do not include
DOCTYPE declarations; they are automatically added when the web server
checks out its copy. To validate your changes, temporarily insert
this header in place of the <html> tag, then use the "upload
file" mode of the validator.</p>
<blockquote><pre>
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
</pre></blockquote>
<p>Please mark patches with the tag [wwwdocs] in the subject line.</p>
<hr />
<h2>On the Back End</h2>
<p>As changes are checked in, the respective pages are preprocessed
via the script <code>wwwdocs/bin/preprocess</code> which in turn
uses a tool called <a href="http://metahtml.sourceforge.net/";>MetaHTML</a>.
Among others, this preprocessing adds CSS style sheets,
XML and HTML headers, and our standard footer.
The MetaHTML style sheet is in <code>wwwdocs/htdocs/style.mhtml</code>.</p>
<hr />
<h2>How You Can Help</h2>
<p>Any help concerning open issues is highly welcome, as are suggestions.
Suggestions accompanied by patches
have a higher chance of being implemented soon. ;-)</p>
<ul>
<li>Move extra pages corresponding to technical news items into a
directory of their own. Add an index for these.</li>
<li>Improve navigation, with a consistent (short) menu on every page.</li>
<li>Set up a system that automatically checks the mirrors list.
<p>It should detect mirrors that have gone away, are persistently
down, or are very out of date (the last being easy to do for those
carrying snapshots, harder for those with releases only).</p>
<p>DJ Delorie <<a href="mailto:dj@redhat.com";>dj@redhat.com</a>>
has some scripts to do this already.</p></li>
</ul>
> On Tue, 5 Jun 2012, Lawrence Crowl wrote:
> > Where do these prepended pages come from? How do I test the
> > page as it will appear?
>
> This is covered in http://gcc.gnu.org/contribute.html#webchanges .
>
> > I guess maybe I'm asking for the makefile that produces what
> > one would see. I want to validate that.
>
> This is now documented via the second patch below.
>
> > BTW, part of the problem is that the pages are complete enough as
> > they are to be considered complete. I.e. they are not obviously
> > fragments. Would it be better to make them clearly fragments?
>
> The idea was for them to be basic HTML, so that people can view
> them in their browsers and use some clever editors without
> problems. So far this has generally worked well. Is there
> something we can tweak to make it better for you?
My problem was that the basic HTML did not validate, and hence as
a developer I was concerned that something was missing.
> > Doesn't the prepending prevent incremental migration to new
> > standards?
>
> This is true, though we can mitigate this by adding separate
> tags or annotations to either "old" or "new" pages during such
> a transition.
Those tags or annotations could use documentation.
> The last time I did such a transition, it was not a big issue,
> though, and I expect web standards to be more incremental and
> usually quite compatible. But, you are right.
Yes, I expect most to be upward compatible, but some of us like to
use the strict standards, just to be sure.
> > > Since you ran into this, I would like to document this better.
> > > Would http://gcc.gnu.org/projects/web.html be a good place,
> > > or do you have a different suggestion?
> >
> > My entry point was http://gcc.gnu.org/cvs.html, so at a minimum
> > it need to be cross linked with
> > http://gcc.gnu.org/projects/web.html.
>
> Done via the patch below, which also shortens the cvs.html page
> to make it easier to consume (and move/integrate somewhere else
> later on).
>
> Anything else I can answer / document, let me know!
>
> Gerald
>
> Index: projects/web.html
> ===================================================================
> RCS file: /cvs/gcc/wwwdocs/htdocs/projects/web.html,v
> retrieving revision 1.11
> diff -u -3 -p -r1.11 web.html
> --- projects/web.html 30 Mar 2008 18:59:30 -0000 1.11
> +++ projects/web.html 20 Jun 2012 23:50:38 -0000
> @@ -8,6 +8,9 @@
>
> <h1>GCC: Web Pages</h1>
>
> +<p><a href="../contribute.html#webchanges">Contributing changes to
> +our web pages</a> is simple.</p>
> +
> <p>Our web pages are managed via CVS and can be accessed using the
> directions for <a href="../cvs.html">our CVS setup</a>.</p>
>
> Index: projects/web.html
> ===================================================================
> RCS file: /cvs/gcc/wwwdocs/htdocs/projects/web.html,v
> retrieving revision 1.12
> diff -u -3 -p -r1.12 web.html
> --- projects/web.html 20 Jun 2012 23:55:35 -0000 1.12
> +++ projects/web.html 21 Jun 2012 00:02:02 -0000
> @@ -14,6 +14,13 @@ our web pages</a> is simple.</p>
> <p>Our web pages are managed via CVS and can be accessed using the
> directions for <a href="../cvs.html">our CVS setup</a>.</p>
>
> +<p>As changes are checked in, the respective pages are preprocessed
> +via the script <code>wwwdocs/bin/preprocess</code> which in turn
> +uses a tool called MetaHTML. Among others, this preprocessing
> +adds CSS style sheets, XML and HTML headers, and our standard
> +footer. The MetaHTML style sheet is in
> +<code>wwwdocs/htdocs/style.mhtml</code>.</p>
> +
> <h2>TODO</h2>
>
> <p>Any help concerning open issues is highly welcome, as are
>
> Index: cvs.html
> ===================================================================
> RCS file: /cvs/gcc/wwwdocs/htdocs/cvs.html,v
> retrieving revision 1.220
> diff -u -3 -p -r1.220 cvs.html
> --- cvs.html 3 Apr 2011 13:00:43 -0000 1.220
> +++ cvs.html 21 Jun 2012 00:25:42 -0000
> @@ -12,7 +12,8 @@
> <p>Our web pages and related scripts are available via our CVS
> repository. You can also <a
> href="http://gcc.gnu.org/cgi-bin/cvsweb.cgi/wwwdocs/";>browse them
> -online</a>.</p>
> +online</a> or view <a href="projects/web.html">details on the
> +setup</a>.</p>
>
> <h2>Using the CVS repository</h2>
>
> @@ -28,8 +29,6 @@ and SSH installed, you can check out the
> <p>For anonymous access, use
> <code>-d :pserver:cvs@gcc.gnu.org:/cvs/gcc</code> instead.</p>
>
> -<p>Patches should be marked with the tag [wwwdocs] in the subject
> line.</p>
> -
>
> <hr />
> <h2><a name="checkin">Checking in a change</a></h2>
> @@ -37,25 +36,21 @@ and SSH installed, you can check out the
> <p>When you check in changes to our web pages, they will
> automatically be checked out into the web server's data area.</p>
>
> -<p>The following is meant to provide a very quick overview of how
> +<p>The following is a very quick overview of how
> to check in a change. We recommend you list files explicitly
> to avoid accidental checkins and prefer that each checkin be of a
> complete, single logical change.</p>
>
> <ol>
> <li>Sync your sources with the master repository via "<code>cvs
> -update</code>" before attempting a checkin; this will save you a little
> -time if someone else has modified that file since the last time you
> -synced your sources. It will also identify any files in your local
> +update</code>".
> +This will also identify any files in your local
> tree that you have modified.</li>
>
> -<li>We recommend using "<code>cvs diff</code>" after applying a patch to a
> -local tree. Review the output to make sure that only the changes you
> -wanted to check in will be checked in.</li>
> -
> -<li>Use "<code>cvs commit</code>" to check in the patch. You can enter
> -the log message via the "<code>-m</code>" argument to commit, or wait for
> -the editor window to appear.</li>
> +<li>We recommend reviewing the output of "<code>cvs diff</code>" after
> +applying a patch to a local tree.</li>
> +
> +<li>Use "<code>cvs commit</code>" to check in the patch.</li>
>
> <li>Upon successfull checkin a message will be sent to the
> gcc-cvs-wwwdocs mailing list.</li>
--
Lawrence Crowl