Re: [wwwdocs] Move all documentation projects to a new page

[Gerald Pfeifer <gerald at pfeifer dot com>]

On Mon, 22 Nov 2004, Steven Bosscher wrote:
> 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.

I wouldn't call it perfectly easy to review, though it was okay.  I agree
with Joseph that small patches are easier to review, however, given the
state of this documentation and the choice between not seeing it updated
or having to review a larger patch certainly made me opt for the latter,
especially since the patch indeed is self-contained and constitutes a
single sensible unit of change.

Thank you for working on this Steven, I really appreciate that.

Below you fill find some comments of mine, and I happily (pre)approve the
patch modulo these comments.

Gerald

Index: beginner.html
===================================================================
-<p>For example, all command line options should be indexed, and there
-should be index entries for the text of all error messages that might
-be confusing, if there's a relevant part of the manual.  See a <a
-href="http://gcc.gnu.org/ml/gcc-bugs/2001-02/msg00384.html";>message to
-gcc-bugs</a> about this.</p></li>

Did this get lost during the restructuring, or are you sufficiently
confident that it has been fully addressed?  If it's the latter, please
do mention this in the cvs commit log.

-<li>Give all commands a manpage.
-
-<p>This is best done by documenting them in the Texinfo manual, then
-generating the manpages via <code>texi2pod</code> etc.  That way we
-only have to remember to update the documentation in one place.</p>
-</li>

Similarly to the above.

Index: documentation.html
===================================================================
+<p>This page lists projects for GCC's documentation.  Some of these
+projects on this page concern the internals documentation of GCC,

Omit "project on this page"...

+obviously these projects require intimate knowledge of GCC's internals.

...and "these projects".

+<p>Be sure to contact one of the documentation maintainers before you
+take on one of the projects listed below.  You can find their email
+addresses under "docs co-maintainer" in the <code>MAINTAINERS</code>
+file in the toplevel directory.</p>

I believe Joseph suggested to omit that, and I agree.

+<ul>
+  <li><a href="#fully_document_the_interface_of_front_ends_to_gcc">Fully
+  document the interface of front ends to GCC</a></li>

The anchor here really is a bit lenghty. ;-)  How about 
"frontend-middleend-interface" or similar?

+  <li><a href="#fully_document_RTL">Fully document the backend intermediate
+  language data structures</a></li>

Just "#RTL".  I am aware that some of the changes I suggest do not affect
changes you have made with this patch, but since we are touching this
code (and move this to a page which is already called documentation.html)
let's just improve it.

+<p>Always, anytime, feel free to shout at anyone who sends in a patch
+to <a href="http://gcc.gnu.org/ml/gcc-patches/";>gcc-patches</a> without
+including all relevant documentation changes.</p>

I'd omit "to gcc-patches" here.  Brevity rules.

+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>.

Put this into <p>...</p> and add a ")" at the end of the paragraph.

+  <li><a href="#improve_user_and_installation_documentation">Improve
+  user and installation documentation.</a></li>

For a tool like GCC one might consider installation documentation on the 
same level as user documentation and just use "user level documentation"?
I'm not sure about this, though.

+  <li>Make sure all such Texinfo manuals are included and installed.</li>
+</ul>

Omit "such".

+  <li><a href="#revisit_actual_bugs">Revisit the list of "Actual Bugs"
+  listed in the manual</a></li>

Omit "listed".

+<p>Go through the list of "Actual Bugs" in
+<code>gcc/doc/trouble.texi</code>.  Work out what they refer to, if
+necessary by asking people who were involved in GCC development when
+those bugs were documented.  If a bug is no longer present, remove it
+from the list; if it is still present, file a bug report in the <a
+href="http://gcc.gnu.org/bugzilla";>GCC bug tracking system</a> or
+fix the bug yourself.</p>

...and omit the bug from trouble.texi, or keep it?

Index: index.html
===================================================================
@@ -11,6 +11,7 @@
 <li><a href="#projects_for_beginner_gcc_hackers">Projects for beginner GCC hackers</a></li>
 <li><a href="#projects_for_the_c_preprocessor">Projects for the C preprocessor</a></li>
 <li><a href="#projects_for_the_gcc_web_pages">Projects for the GCC web pages</a></li>

Can we shorten these three, please?  Just "beginner_hackers", "cpp", and 
"web", for example?


 <p>There is a separate projects list for the <a href="web.html">web
 pages</a>.</p>

+<h2><a href="documentation_projects">Projects for improving the GCC documentation</a></h2>
+<p>There is a separate projects list for <a
+href="documentation.html">projects for improving the GCC documentation</a>.</p>

Merge these into a single paragraph?