mainpage.html: Move building/writing instructions...

2003-07-16 Phil Edwards <pme@gcc.gnu.org> * docs/doxygen/mainpage.html: Move building/writing instructions... * docs/doxygen/guide.html: ...to here. New file. From-SVN: r69485
author: Phil Edwards <pme@gcc.gnu.org> 2003-07-16 23:59:54 +0000
committer: Phil Edwards <pme@gcc.gnu.org> 2003-07-16 23:59:54 +0000
commit: 1ef4a5d4c3f780623ed85b66fe7412c5afe85d81 (patch)
tree: 4092c31014cacaeeb2be24e0172f406eb56500fb /libstdc++-v3
parent: fada196198e4c9350a78fe08c7a132bb4055ba05 (diff)
download: gcc-1ef4a5d4c3f780623ed85b66fe7412c5afe85d81.zip
gcc-1ef4a5d4c3f780623ed85b66fe7412c5afe85d81.tar.gz
gcc-1ef4a5d4c3f780623ed85b66fe7412c5afe85d81.tar.bz2
3 files changed, 119 insertions, 45 deletions
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 7bc4aaf..f13fc2f 100644
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,3 +1,8 @@
+2003-07-16  Phil Edwards  <pme@gcc.gnu.org>
+
+	* docs/doxygen/mainpage.html:  Move building/writing instructions...
+	* docs/doxygen/guide.html:  ...to here.  New file.
+
 2003-07-16  Jonathan Wakely  <redi@gcc.gnu.org>
 
 	* docs/html/ext/howto.html: Update URL for SGI STL docs.
diff --git a/libstdc++-v3/docs/doxygen/guide.html b/libstdc++-v3/docs/doxygen/guide.html
new file mode 100644
index 0000000..7974358
--- /dev/null
+++ b/libstdc++-v3/docs/doxygen/guide.html
@@ -0,0 +1,107 @@
+<!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">
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+  <title>Build and Writing Guide for libstdc++-v3 Doxygen</title>
+  <link href="style.css" rel="stylesheet" type="text/css">
+</head>
+
+<body bgcolor="#ffffff">
+
+<h1>libstdc++-v3 Source Documentation</h1>
+
+<p>This file is docs/doxygen/guide.html in the libstdc++-v3 source tree.  It
+   is not included in the generated pages (no real point to doing that).
+</p>
+
+<ul>
+ <li><a href="#creating">Creating the pages</a></li>
+ <li><a href="#writing">Writing the markup</a></li>
+</ul>
+
+<hr />
+
+<a name="creating"><h2>Creating the pages</h2></a>
+<p>The Makefile rules <code>'make doxygen'</code>,
+   <code>'make doxygen-maint'</code>, and <code>'make doxygen-man'</code>
+   in the libstdc++-v3 build directory generate the user-level HTML docs, the
+   maintainer-level HTML docs, and the man pages, respectively.  Prerequisite
+   tools are
+   <a href="http://www.doxygen.org/">
+   <!-- snagged from the generated page -->
+   <img src="doxygen.png" alt="Doxygen" align=center border=0 width=110 height=53>
+   </a>, a working version of <code>g++</code> somewhere in the PATH, and
+   the <a href="http://www.gnu.org/software/coreutils/">GNU coreutils</a>.
+   (g++ is used to build a program which manipulates man pages.  GNU versions
+   of find, xargs, and possibly sed and grep are used, just because the GNU
+   versions make things very easy.)
+</p>
+
+<p>Careful observers will see that the Makefile rules simply call a script
+   from the source tree, <code>run_doxygen</code>, which does the actual work
+   of running Doxygen and then (most importantly) massaging the output files.
+   If for some reason you prefer to not go through the Makefile, you can call
+   this script directly.  (Start by passing <code>'--help'</code>.)
+</p>
+
+<p>If you wish to tweak the Doxygen settings, do so by editing
+   <code>docs/doxygen/user.cfg.in</code>.  Notes to v3-hackers are written in
+   triple-# comments.
+</p>
+
+<a name="writing"><h2>Writing the markup</h2></a>
+<p>In general, libstdc++-v3 files should be formatted according to the GNU
+   C++ Coding Standard rules found in the file
+   <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>.
+   Before any doxygen-specific formatting tweaks are made, please try to make
+   sure that the initial formatting is sound.
+</p>
+
+<p>Adding Doxygen markup to a file (informally called "doxygenating") is very
+   simple.  The Doxygen manual can be found
+   <a href="http://www.stack.nl/~dimitri/doxygen/download.html#latestman">here</a>.
+   We try to use a very-recent version of Doxygen.
+</p>
+
+<h3>Doxygen style guide</h3>
+<p>[incomplete and constantly evolving]</p>
+
+<p>For classes, use deque/vector/list and std::pair as examples.  For
+   functions, see their memeber functions, and the free functions in
+   <code>stl_algobase.h</code>.  Member functions of other container-like
+   types should read similarly to these member functions.
+</p>
+
+<p>These points accompany the first list in section 3.1 of the Doxygen manual:
+</p>
+<ol>
+ <li>Use the Javadoc style...</li>
+ <li>...not the Qt style.  The intermediate *'s are preferred.</li>
+ <li>Use the triple-slash style only for one-line comments (the "brief" mode).
+     Very recent versions of Doxygen permit full-mode comments in triple-slash
+     blocks, but the formatting still comes out wonky.</li>
+ <li>This is disgusting.  Don't do this.</li>
+</ol>
+
+<p>Use the @-style of commands, not the !-style.  Please be careful about
+   whitespace in your markup comments.  Most of the time it doesn't matter;
+   doxygen absorbs most whitespace, and both HTML and *roff are agnostic about
+   whitespace.  However, in &lt;pre&gt; blocks and @code/@endcode sections,
+   spacing can have "interesting" effects.
+</p>
+
+<p>Use either kind of grouping, as appropriate.  <code>doxygroups.cc</code>
+   exists for this purpose.  See <code>stl_iterator.h</code> for a good
+   example of the "other" kind of grouping.
+</p>
+
+<p>Please use markup tags like @p and @a when referring to things such as the
+   names of function parameters.  Use @e for emphasis when necessary.  Use @c
+   to refer to other standard names.  (Examples of all these abound in the
+   present code.)
+</p>
+
+</body>
+</html>
diff --git a/libstdc++-v3/docs/doxygen/mainpage.html b/libstdc++-v3/docs/doxygen/mainpage.html
index e0998fc..fdd40ed 100644
--- a/libstdc++-v3/docs/doxygen/mainpage.html
+++ b/libstdc++-v3/docs/doxygen/mainpage.html
@@ -42,47 +42,6 @@
    additional notes and additional classes/functions/etc.
 </p>
 
-<p>Here are quick links to the pages which we seem to use the most; a full
-   index is at the bottom:
-   <!-- Keep this in sync with below. -->
-   <ul>
-    <li><a href="annotated.html">Compound List</a>
-    <li><a href="classes.html">Alphabetical List</a>
-    <li><a href="namespaces.html">Namespace List</a>
-    <li><a href="files.html">File List</a>
-    <li><a href="modules.html">Modules</a>
-   </ul>
-</p>
-
-<h2> Generating this file </h2>
-<p>These HTML pages are automatically generated, along with the man pages.
-   The Makefile rules <code> 'make doxygen' </code> and
-   <code> 'make doxygen-maint' </code> in the libstdc++-v3 build directory
-   generates these pages using a tool called, appropriately enough, Doxygen.
-   To learn more about Doxygen, take a look at
-   <a href="http://www.doxygen.org/">
-   <!-- snagged from the generated page -->
-   <img src="doxygen.png" alt="the Doxygen homepage"
-        align=center border=0 width=110 height=53>
-   </a>
-</p>
-
-<p>The libstdc++-v3 configuration files needed to generate doxygen output
-   are located:
-   <ul><li><code>docs/doxygen/user.cfg.in</code>
-       <li><code>docs/doxygen/run_doxygen</code>
-   </ul>
-</p>
-
-<h2> libstdc++-v3 doxygen style guide </h2>
-<p>In general, libstdc++-v3 files should be formatted according to the
-   GNU C++ Coding Standard rules found in the file <a
-href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>.
-   Before any doxygen-specific formatting tweaks are made, please try to
-   make sure that the initial formatting is sound.
-</p>
-
-<h2> Full page index </h2>
 <p>Here are entry points to all the pages generated by Doxygen:
    <ul>
     <li><a href="index.html">Main Page</a>
@@ -99,14 +58,18 @@ href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>.
    </ul>
 </p>
 
+<h2>Generating the documentation</h2>
+<p>These HTML pages are automatically generated, along with the man pages.
+   See <code>docs/doxygen/guide.html</code> in the source tree for how to
+   create (and write) the pages.
 
-<h2> License, Copyright, and Other Lawyerly Verbosity </h2>
+<h2>License, Copyright, and Other Lawyerly Verbosity</h2>
 <p>The libstdc++-v3 documentation is released under
    <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/license.html">
    these terms</a>.
 </p>
-<p>Part of the generated documentation involved comments
-   and notes from SGI, who says we gotta say this:
+<p>Part of the generated documentation involved comments and notes from
+   SGI, who says we gotta say this:
    <blockquote>
    Permission to use, copy, modify, distribute and sell this software and its
    documentation for any purpose is hereby granted without fee, provided
@@ -126,4 +89,3 @@ href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE">C++STYLE</a>.
 
 </body>
 </html>
-
author	Phil Edwards <pme@gcc.gnu.org>	2003-07-16 23:59:54 +0000
committer	Phil Edwards <pme@gcc.gnu.org>	2003-07-16 23:59:54 +0000
commit	1ef4a5d4c3f780623ed85b66fe7412c5afe85d81 (patch)
tree	4092c31014cacaeeb2be24e0172f406eb56500fb /libstdc++-v3
parent	fada196198e4c9350a78fe08c7a132bb4055ba05 (diff)
download	gcc-1ef4a5d4c3f780623ed85b66fe7412c5afe85d81.zip gcc-1ef4a5d4c3f780623ed85b66fe7412c5afe85d81.tar.gz gcc-1ef4a5d4c3f780623ed85b66fe7412c5afe85d81.tar.bz2