GNU C++ Library: call for writers

[Phil Edwards]

For about a year a project has been taking shape under libstdc++-v3.
The goal is to produce nice-looking useful documentation automatically,
based largely on source code comments.  The inheritance and collaboration
graphs are also handy.  If you've seen postings from me patching files
to work with Doxygen, you know what I'm talking about.

Here's an example:  pull up
http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/index.html
in your favorite browser, follow the "Compound List" link, and select
std::exception, or std::unary_negate, or std::underflow, or whatever.

Recently we've started to generate man pages in addition to HTML.

This work has not gone unnoticed by the GCC user community.
Debian "testing" has a package containing the HTML pages; there is
a wishlist request submitted already to incorporate the man pages in
their distribution, and the man pages aren't even really useful yet!
Clearly somebody expects them to become so.  :-)  Other Linux distros have
also expressed interest, and we hope it won't be restricted only to Linux.


However, words do not write themselves.


We need help.  Documenting the Standard C++ Library is a lot of work.
The present goal is /not/ to provide a complete tutorial on the use
of the entire library; we are not going to try and reproduce something
like the comprehensive Josuttis text.  (At least, /I/ don't plan to...)
The example of std::exception should give you an idea of what we're
trying to do for now:  a reference, not a textbook.

What can you do?  Easy:

    + checkout the libstdc++-v3 CVS source and look at the list in
      docs/doxygen/TODO.

    + write some /** comments */ or maybe a simple HTML table, and
      send them in to us.  You don't need to compile a thing!

What do you need?  At minimum:

    + fair writing skills, in simple technical English.  By "simple
      technical" I don't mean extremely long-winded extra-precise detailed
      text (like the ISO Standard itself), but clear and simple phrases.
      Again, see the documentation already done for examples.

    + a text editor.

Optionally, you should consider also having:

    + a copyright assignment on file with the FSF, if you plan on doing
      more than a few entries:
      http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/contribute.html
      (This is not as onerous as it sounds.)

    + a copy of the ISO C++ Standard:
      http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#5_7
      This isn't strictly necessary, but it's very useful for answering
      those "what is this supposed to mean" questions.

    + the latest Defect List:
      http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#4_3
      All the things that have changed since the standard was published.
      You can download a local HTML copy and browse them locally.

    + an installed version of Doxygen, if you want to check the visual
      effect of your changes locally before submitting them.  Running our
      generating script, "sh docs/doxygen/run_doxygen", without any
      arguments will print the minimum required version and where to get it.

If you have questions, please ask!  The FAQ, the list address, and the
source code are here:

    http://gcc.gnu.org/libstdc++/


Thanks, and happy hacking.


Phil

-- 
If ye love wealth greater than liberty, the tranquility of servitude greater
than the animating contest for freedom, go home and leave us in peace.  We seek
not your counsel, nor your arms.  Crouch down and lick the hand that feeds you;
and may posterity forget that ye were our countrymen.            - Samuel Adams