This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[wwwdocs] Move all documentation projects to a new page
- From: Steven Bosscher <stevenb at suse dot de>
- To: Gerald Pfeifer <gerald at pfeifer dot com>
- Cc: gcc-patches at gcc dot gnu dot org
- Date: Sun, 21 Nov 2004 15:13:45 +0100
- Subject: [wwwdocs] Move all documentation projects to a new page
- Organization: SUSE Labs
Hi,
This moves all documentation projects from beginners.html and
index.html to a new page called documentation.html. I've also
reordered and cleaned up the listed projects a bit. Some of
the projects were listed on both pages, for example.
OK?
Gr.
Steven
Index: beginner.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/projects/beginner.html,v
retrieving revision 1.52
diff -u -3 -p -r1.52 beginner.html
--- beginner.html 19 Nov 2004 19:38:49 -0000 1.52
+++ beginner.html 21 Nov 2004 14:09:45 -0000
@@ -18,8 +18,9 @@ the GCC project, by giving new developer
<p>Most of these projects require a reasonable amount of experience
with C and the Unix programming environment. Do not despair if any
individual task seems daunting; there's probably an easier one. If
-you have <em>no</em> programming skills, we can still use your help
-with documentation or the bug database. See below.</p>
+you have <em>no</em> programming skills, we can still use your <a
+href="documentation.html">help with documentation</a> or with the <a
+href="http://gcc.gnu.org/bugzilla/";>bug database</a>.</p>
<p>We assume that you already know how to <a href="../cvs.html">get the
latest sources</a>, configure and build the compiler, and run the test
@@ -842,99 +843,6 @@ include files. Remember that we already
</li>
</ul>
-<h2>Documentation</h2>
-
-<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>
-
-<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>
-
-<li>Finish documenting the tree structure and the front-end interface.
-
-<p>We've got quite a bit of this but it is scattered all over the
-place. It belongs in the official manual. There is a <a
-href="http://gcc.gnu.org/onlinedocs/gccint/Trees.html";>C/C++ specific manual</a>, and a
-<a href="http://www.ncsa.uiuc.edu/~wendling/tree.html";>third party,
-general manual</a>. Both of them are incomplete. Several people have
-written partial manuals on implementing new front ends: look at our
-<a href="../readings.html">readings list</a>.</p></li>
-
-<li>Roll information in external documents into the official manual.
-
-<p>Start with the <a href="../readings.html">readings list</a> and the
-secondary Texinfo documents in the source tree.</p></li>
-
-<li>Improve user and installation documentation.
-
-<p>Pick your favorite FAQ from the lists and roll it into the manual.
-Add information on relevant standards. Document the exact semantics
-of all the extensions. Also say what they're good for. If they're
-useless, admit it.</p></li>
-
-<li>Improve the indexing of the GCC manual.
-
-<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>
-
-<li>Read the whole manual.
-
-<p>Become familiar with what's documented where and report or fix any
-problems you see. Then shout at anyone who sends a patch to <a
-href="http://gcc.gnu.org/ml/gcc-patches/";>gcc-patches</a> without including all
-relevant documentation changes.</p></li>
-
-<li>Install all Texinfo manuals.
-
-<p>Such as <code>libstdc++-v3/docs/html/17_intro/porting.texi</code>.</p></li>
-
-<li>Improve support for building other manual formats.
-
-<p>For example, arrange for <code>make dvi</code> at top level to
-build DVI versions of all manuals. Add a <code>make html</code>
-target to build HTML versions of manuals (using
-<code>makeinfo --html</code>). Consider
-adding targets to build PostScript and PDF versions of manuals
-(<code>texinfo.tex</code> includes some support for PDF
-output).</p></li>
-
-<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>
-
-<li>Go through the list of "Actual Bugs" in <code>trouble.texi</code>.
-
-<p>Work out what they refer to, if necessary by asking people who were
-involved in GCC development when those bugs were documented. If no
-longer present, then remove them from the list; if still present, file
-bug reports or fix them.</p></li>
-
-</ul>
-
<h2>User interface</h2>
<ul>
Index: documentation.html
===================================================================
RCS file: documentation.html
diff -N documentation.html
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ documentation.html 21 Nov 2004 14:09:45 -0000
@@ -0,0 +1,236 @@
+<html>
+
+<head>
+<title>Documentation projects</title>
+</head>
+
+<body>
+<h1>Documentation projects</h1>
+
+<p>This page lists projects for GCC's documentation. Some of these
+projects on this page concern the internals documentation of GCC, so
+obviously these projects require intimate knowledge of GCC's internals.
+The other projects are about work on the user documentation, and could
+be taken on by anyone who has mastered US English and has basic
+technical writing skills.</p>
+
+<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>
+
+<ul>
+ <li><a href="#fully_document_the_interface_of_front_ends_to_gcc">Fully
+ document the interface of front ends to GCC</a></li>
+
+ <li><a href="#better_documentation_of_how_gcc_works_and_how_to_port_it">Better
+ documentation of how GCC works and how to port it</a></li>
+
+ <li><a href="#fully_document_RTL">Fully document the backend intermediate
+ language data structures</a></li>
+
+ <li><a href="#roll_external_documents_into_the_manual">Roll information
+ in external documents into the official manual.</a></li>
+
+ <li><a href="#improve_user_and_installation_documentation">Improve
+ user and installation documentation.</a></li>
+
+ <li><a href="#revisit_actual_bugs">Revisit the list of "Actual Bugs"
+ listed in the manual</a></li>
+</ul>
+
+<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>
+
+<p>It is also always appreciated if you read the whole manual and become
+familiar with what is documented where, and what documentation appears
+to be missing. Report or fix any problems you see.</p>
+
+<hr />
+
+<h2><a name="fully_document_the_interface_of_front_ends_to_gcc">Fully
+document the interface of front ends to GCC</a></h2>
+
+<p>Fully document the interface of front ends to GCC, that is, the
+<code>tree</code>, <code>cgraph</code>, and <code>langhooks</code>
+interfaces, and the various functions, data structures, etc., that
+a front end must or may provide.</p>
+
+<p>We've got quite a bit of this but it is scattered all over the
+place. It belongs in the official manual. There is a <a
+href="http://gcc.gnu.org/onlinedocs/gccint/Trees.html";>C/C++ specific manual</a>,
+and a <a href="http://www.ncsa.uiuc.edu/~wendling/tree.html";>third party,
+general manual</a>. Both of them are incomplete. The file
+<code>gcc/LANGUAGES</code> contains incomplete and outdated information
+about changes made in not so recent years to the <code>tree</code>
+interface. Several people have written partial manuals on implementing
+new front ends. Pointers to some of those can be found in our <a
+href="../readings.html">readings list</a>. With the advent of tree-ssa,
+most of these manuals are obsolete.</p></li>
+
+
+<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">
+<li>Overview of this document</li>
+<li>The machines on which GCC is implemented
+ <ol type="A">
+ <li>Prose description of those characteristics of target machines and
+ their operating systems which are pertinent to the implementation
+ of GCC.
+ <ol type="i">
+ <li>target machine characteristics</li>
+ <li>comparison of this system of machine characteristics with
+ other systems of machine specification currently in use</li>
+ </ol></li>
+ <li>Tables of the characteristics of the target machines on which
+ GCC is implemented.</li>
+ <li>A priori restrictions on the values of characteristics of target
+ machines, with special reference to those parts of the source code
+ which entail those restrictions
+ <ol type="i">
+ <li>restrictions on individual characteristics</li>
+ <li>restrictions involving relations between various characteristics</li>
+ </ol></li>
+ <li>The use of GCC as a cross-compiler
+ <ol type="i">
+ <li>cross-compilation to existing machines</li>
+ <li>cross-compilation to non-existent machines</li>
+ </ol></li>
+ <li>Assumptions which are made regarding the target machine
+ <ol type="i">
+ <li>assumptions regarding the architecture of the target machine</li>
+ <li>assumptions regarding the operating system of the target machine</li>
+ <li>assumptions regarding software resident on the target machine</li>
+ <li>where in the source code these assumptions are in effect
+ made.</li>
+ </ol></li>
+ </ol></li>
+<li>A systematic approach to writing the files <code>tm.h</code> and
+<code>xm.h</code>
+ <ol type="A">
+ <li>Macros which require special care or skill</li>
+ <li>Examples, with special reference to the underlying reasoning</li>
+ </ol></li>
+<li>A systematic approach to writing the machine description file
+ <ol type="A">
+ <li>Minimal viable sets of insn descriptions</li>
+ <li>Examples, with special reference to the underlying reasoning</li>
+ </ol></li>
+<li>Uses of the file aux-output.c</li>
+<li>Specification of what constitutes correct performance of an
+implementation of GCC
+ <ol type="A">
+ <li>The components of GCC</li>
+ <li>The itinerary of a C program through GCC</li>
+ <li>A system of benchmark programs</li>
+ <li>What your RTL and assembler should look like with these benchmarks</li>
+ <li>Fine tuning for speed and size of compiled code</li>
+ </ol></li>
+<li>A systematic procedure for debugging an implementation of GCC
+ <ol type="A">
+ <li>Use of GDB
+ <ol type="i">
+ <li>the macros in the file .gdbinit for GCC</li>
+ <li>obstacles to the use of GDB
+ <ol type="a">
+ <li> functions implemented as macros can't be called in
+ GDB</li>
+ </ol></li>
+ </ol></li>
+ <li>Debugging without GDB
+ <ol type="i">
+ <li>How to turn off the normal operation of GCC and access specific
+ parts of GCC</li>
+ </ol></li>
+ <li>Debugging tools</li>
+ <li>Debugging the parser
+ <ol type="i">
+ <li>how machine macros and insn definitions affect the parser</li>
+ </ol></li>
+ <li>Debugging the recognizer
+ <ol type="i">
+ <li>how machine macros and insn definitions affect the recognizer</li>
+ </ol></li>
+ <li></li>
+ <li>... ditto for other components...</li>
+ <li></li>
+ </ol></li>
+<li>Data types used by GCC, with special reference to restrictions not
+specified in the formal definition of the data type</li>
+<li>References to the literature for the algorithms used in GCC</li>
+</ol>
+
+
+<h2><a name="fully_document_RTL">Fully document the backend intermediate
+language data structures</a></h2>
+
+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>
+
+
+<h2><a name="roll_external_documents_into_the_manual">Roll information
+in external documents into the official manual.</a></h2>
+
+<p>Start with the <a href="../readings.html">readings list</a> and the
+secondary Texinfo documents in the source tree, such as
+<code>libstdc++-v3/docs/html/17_intro/porting.texi</code>. Pick your
+favorite FAQ from the lists and roll it into the manual.</p>
+
+
+<h2><a name="improve_user_and_installation_documentation">Improve
+user and installation documentation.</a></h2>
+
+<ul>
+ <li>Add information on relevant standards. Document the exact semantics
+ of all the extensions. Also say what they're good for. If they're
+ useless, admit it.</li>
+
+ <li>Improve support for building other manual formats. For example,
+ arrange for <code>make dvi</code> at top level to build DVI versions
+ of all manuals. Add a <code>make html</code> target to build HTML
+ versions of manuals (using <code>makeinfo --html</code>).</li>
+
+ <li>Consider adding targets to build PostScript and PDF versions of
+ all manuals (<code>texinfo.tex</code> includes some support for PDF
+ output).</li>
+
+ <li>Make sure all such Texinfo manuals are included and installed.</li>
+</ul>
+
+
+<h2><a name="revisit_actual_bugs">Revisit the list of "Actual Bugs"
+listed in the manual</a></h2>
+
+<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>
+
+</body>
+</html>
+
Index: index.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/projects/index.html,v
retrieving revision 1.51
diff -u -3 -p -r1.51 index.html
--- index.html 18 Nov 2004 10:21:14 -0000 1.51
+++ index.html 21 Nov 2004 14:09:45 -0000
@@ -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>
+<li><a href="#documentation_projects">Projects for improving the GCC documentation</a></li>
<li><a href="#development_branches">Development Branches</a></li>
<li><a href="#data_prefetch">Data prefetch support</a></li>
<li><a href="#optimizer_inadequacies">Optimizer inadequacies</a></li>
@@ -21,7 +22,6 @@
<li><a href="#improve_wconversion">Improve <code>-Wconversion</code></a></li>
<li><a href="#implement_various_builtin_functions_for_isoc99">Implement various builtin functions for ISO C99's
<code><tgmath.h></code></a></li>
-<li><a href="#fully_document_the_interface_of_front_ends_to_gcc">Fully document the interface of front ends to GCC</a></li>
</ul></li>
<li><a href="#better_builtin_string_functions">Better builtin string functions</a>
<ul>
@@ -51,7 +51,6 @@
<li><a href="#other_languages">Other languages</a></li>
<li><a href="#generalize_the_machine_model">Generalize the machine model</a></li>
<li><a href="#more_warnings">More warnings</a></li>
-<li><a href="#better_documentation_of_how_gcc_works_and_how_to_port_it">Better documentation of how GCC works and how to port it</a></li>
<li><a href="#the_old_problems_file">The old PROBLEMS file</a></li>
</ul>
<!-- table of contents end -->
@@ -79,6 +78,10 @@ href="cpplib.html">C preprocessor</a>.</
<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>
+
<h2><a name="development_branches">Development Branches</a></h2>
<p>There are several <a href="../cvs.html#devbranches">development branches</a>
pursuing various goals.</p>
@@ -133,14 +136,6 @@ but which have complex result type for c
for these builtins should be discussed with the gcc and libc-alpha
lists.</p>
-<h3><a name="fully_document_the_interface_of_front_ends_to_gcc">Fully document the interface of front ends to GCC</a></h3>
-<p>Fully document the interface of front ends to GCC (that is, the
-<code>tree</code> interfaces, and the various functions, hooks, etc.,
-that a front end must or may provide). <code>gcc/doc/c-tree.texi</code>
-includes some of this information; <code>gcc/LANGUAGES</code> contains
-incomplete information about changes that have been made to this
-interface.</p>
-
<h2><a name="better_builtin_string_functions">Better builtin string functions</a></h2>
<p>Although GCC implements numerous optimizations of the standard C
@@ -528,100 +523,6 @@ example:</p>
<p><code>-Wsequence-point</code> does some of this, but not that
particular case.</p>
-<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>Here is an outline proposed by Allan Adler.</p>
-
-<ol type="I">
-<li> Overview of this document</li>
-<li> The machines on which GCC is implemented
- <ol type="A">
- <li> Prose description of those characteristics of target machines and
- their operating systems which are pertinent to the implementation
- of GCC.
- <ol type="i">
- <li> target machine characteristics</li>
- <li> comparison of this system of machine characteristics with
- other systems of machine specification currently in use</li>
- </ol></li>
- <li> Tables of the characteristics of the target machines on which
- GCC is implemented.</li>
- <li> A priori restrictions on the values of characteristics of target
- machines, with special reference to those parts of the source code
- which entail those restrictions
- <ol type="i">
- <li> restrictions on individual characteristics</li>
- <li> restrictions involving relations between various characteristics</li>
- </ol></li>
- <li> The use of GCC as a cross-compiler
- <ol type="i">
- <li> cross-compilation to existing machines</li>
- <li> cross-compilation to non-existent machines</li>
- </ol></li>
- <li> Assumptions which are made regarding the target machine
- <ol type="i">
- <li> assumptions regarding the architecture of the target machine</li>
- <li> assumptions regarding the operating system of the target machine</li>
- <li> assumptions regarding software resident on the target machine</li>
- <li> where in the source code these assumptions are in effect
- made.</li>
- </ol></li>
- </ol></li>
-<li> A systematic approach to writing the files tm.h and xm.h
- <ol type="A">
- <li> Macros which require special care or skill</li>
- <li> Examples, with special reference to the underlying reasoning</li>
- </ol></li>
-<li> A systematic approach to writing the machine description file
- <ol type="A">
- <li> Minimal viable sets of insn descriptions</li>
- <li> Examples, with special reference to the underlying reasoning</li>
- </ol></li>
-<li> Uses of the file aux-output.c</li>
-<li> Specification of what constitutes correct performance of an
- implementation of GCC
- <ol type="A">
- <li> The components of GCC</li>
- <li> The itinerary of a C program through GCC</li>
- <li> A system of benchmark programs</li>
- <li> What your RTL and assembler should look like with these benchmarks</li>
- <li> Fine tuning for speed and size of compiled code</li>
- </ol></li>
-<li> A systematic procedure for debugging an implementation of GCC
- <ol type="A">
- <li> Use of GDB
- <ol type="i">
- <li> the macros in the file .gdbinit for GCC</li>
- <li> obstacles to the use of GDB
- <ol type="a">
- <li> functions implemented as macros can't be called in
- GDB</li>
- </ol></li>
- </ol></li>
- <li> Debugging without GDB
- <ol type="i">
- <li> How to turn off the normal operation of GCC and access specific
- parts of GCC</li>
- </ol></li>
- <li> Debugging tools</li>
- <li> Debugging the parser
- <ol type="i">
- <li> how machine macros and insn definitions affect the parser</li>
- </ol></li>
- <li> Debugging the recognizer
- <ol type="i">
- <li> how machine macros and insn definitions affect the
- recognizer</li>
- </ol></li>
- <li></li>
- <li> ... ditto for other components ...</li>
- <li></li>
- </ol></li>
-<li> Data types used by GCC, with special reference to restrictions not
- specified in the formal definition of the data type</li>
-<li> References to the literature for the algorithms used in GCC</li>
-</ol>
-
<hr />
<h2><a name="the_old_problems_file">The old PROBLEMS file</a></h2>