[wwwdocs] Move all documentation projects to a new page

[Steven Bosscher]

On Monday 22 November 2004 02:37, Joseph S. Myers wrote:
> On Mon, 22 Nov 2004, Steven Bosscher wrote:
> > > If the text of any project description has changed, please submit the
> > > change of text as a separate patch from the move to a separate page.
> >
> > I am not going to do that, sorry.  You have many comments on each
> > patch I submit, which is fine normally.  But this one, I'm not going
> > to address your comments, they only cause more work for me.
>
> Submitting patches in a form that is easy to review is important for all
> submissions, not special to this.
> (..) but the 
> description of the patch as submitted suggests that some changes to 
> individual projects may be hidden in the move to a new page.

The patch would be not easy to review if I moved everything at once.  In
its current form it is perfectly easy to review.  You can see what was
removed from the pages, and read the whole new page.  That is about as
easy as I can make it.

What I did, as I said in my original mail, is "reordered and cleaned up
the listed projects a bit".  Where did I say I hid projects?  I would
rather say I've rediscovered and exposed them.

In many cases, what you are asking for is not even possible because the
only reason I could clean up or reorder some of the projects is that they
are on a different page now.  For example (before and after the patch):

-<ul>
-<li>Document every RTX code and accessor macro thoroughly.</li>
-<li>Ditto, every meaningful insn name.</li>
-<li>Ditto, every tm.h macro.  (See <a
-href="http://gcc.gnu.org/ml/gcc/2001-06/msg00507.html";>a list of
-undocumented ones</a>.)</li>
-<li>Ditto, every command line switch.
-
-<p>These may involve hunting down whoever added whichever thing it is
-and torturing information out of them.</p></li>
-
-<li>Work out the correct argument and return types for each tm.h
-macro, and make the manual describe them with <code>@deftypefn</code>
-and similar using C prototypes.  For those macros for which
-performance is not important, change them to be functions, in the
-<code>targetm</code> structure.</li>
(...)
+Document every RTX code and accessor macro, every insn name, every
+<code>tm.h</code> macro and every target hook thoroughly.  (See <a
+href="http://gcc.gnu.org/ml/gcc/2001-06/msg00507.html";>this list of
+undocumented tm.h macros</a>.
+
+<p>These may involve hunting down whoever added whichever thing it is
+and torturing information out of them.</p>
+
+<p>Work out the correct argument and return types for each tm.h
+macro, and make the manual describe them with <code>@deftypefn</code>
+and similar using C prototypes.  For those macros for which
+performance is not important, change them to be functions, in the
+<code>targetm</code> structure for target hooks.</p>

This is merely more than a change in layout.  The reason for the
change is that on one page these projects were itemized, while on the
other they are not.  If you are asking me to submit changes like this
individually, then I first will have to turn one page into a bigger
mess than it already is.  And I refuse to do that.


I also cleaned up duplicate projects, for example from index.html:
-<li>Update the porting manual.
-
-<p>The porting manual describes what used to be the proper way to
-write a GCC back end.  It is several years out of date.  Find all the
-out-of-date advice for porters and replace it with correct advice.
-Mark old, deprecated features as such.</p></li>

A similar project was on index.html, the one with all the items for
a TOC.  So I merged them:

+<h2><a name="better_documentation_of_how_gcc_works_and_how_to_port_it">Better
+documentation of how GCC works and how to port it</a></h2>
+
+<p>The porting manual describes what used to be the proper way to
+write a GCC back end.  It is several years out of date.  Find all the
+out-of-date advice for porters and replace it with correct advice.
+Mark old, deprecated features as such.  Replace examples using old
+targets with examples for newer targets.</p>
+
+<p>Here is an outline proposed by Allan Adler.</p>
+
+<ol type="I">

These shocking changes in content could have been in a separate patch,
but I only found out about them after merging the projects lists.  What
you are asking for me is to go back to the originals and do the changes
there again.  No way jose that I'm going to to that.

What you are asking for is only making things more difficult on me and
serves no other purpose than satisfying your interpretation of the
"smallest possible change".  I believe this is the smallers reasonable
change I can make and I'm not going to redo it just to make you happy.


> I will object to patches that don't follow the GCC Coding Conventions, 
> regardless of the area of the compiler involved. 

I wish I could object with 4 years delay to your patches that created
much if this mess in the first place and left it unattended.  I wonder
what the code conventions say about being responsible for the changes 
one makes.

You are objecting to patches that clean up a part of the web documents
that has basically gone untouched for four years and is shamefully
outdated. Even the documentation projects have not received attention
in all these years, despite your apparent worries about what the pages
say about such projects.

Gr.
Steven