public inbox for gcc@gcc.gnu.org
 help / color / mirror / Atom feed
* GNU C++ Library:  call for writers
@ 2002-02-01 17:00 Phil Edwards
  2002-02-02  2:31 ` Joseph S. Myers
  0 siblings, 1 reply; 3+ messages in thread
From: Phil Edwards @ 2002-02-01 17:00 UTC (permalink / raw)
  To: libstdc++, gcc


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

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: GNU C++ Library:  call for writers
  2002-02-01 17:00 GNU C++ Library: call for writers Phil Edwards
@ 2002-02-02  2:31 ` Joseph S. Myers
  2002-02-04  1:55   ` Phil Edwards
  0 siblings, 1 reply; 3+ messages in thread
From: Joseph S. Myers @ 2002-02-02  2:31 UTC (permalink / raw)
  To: Phil Edwards; +Cc: libstdc++, gcc

On Fri, 1 Feb 2002, Phil Edwards wrote:

> a wishlist request submitted already to incorporate the man pages in
> their distribution, and the man pages aren't even really useful yet!

When the man pages are useful, they should of course be included in the
GCC release distributions (provided the release manager has an appropriate
Doxygen version installed) and installed (provided either they were in the
source or the builder had an appropriate Doxygen version installed).

-- 
Joseph S. Myers
jsm28@cam.ac.uk

^ permalink raw reply	[flat|nested] 3+ messages in thread

* Re: GNU C++ Library:  call for writers
  2002-02-02  2:31 ` Joseph S. Myers
@ 2002-02-04  1:55   ` Phil Edwards
  0 siblings, 0 replies; 3+ messages in thread
From: Phil Edwards @ 2002-02-04  1:55 UTC (permalink / raw)
  To: Joseph S. Myers; +Cc: libstdc++, gcc

On Sat, Feb 02, 2002 at 10:31:13AM +0000, Joseph S. Myers wrote:
> On Fri, 1 Feb 2002, Phil Edwards wrote:
> 
> > a wishlist request submitted already to incorporate the man pages in
> > their distribution, and the man pages aren't even really useful yet!
> 
> When the man pages are useful, they should of course be included in the
> GCC release distributions (provided the release manager has an appropriate
> Doxygen version installed) and installed (provided either they were in the
> source or the builder had an appropriate Doxygen version installed).

Yep, that was the plan.


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

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2002-02-04  9:26 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2002-02-01 17:00 GNU C++ Library: call for writers Phil Edwards
2002-02-02  2:31 ` Joseph S. Myers
2002-02-04  1:55   ` Phil Edwards

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).