Re: libstdc++ documentation

[Phil Edwards <pedwards at disaster dot jaj dot com>]

On Wed, Nov 08, 2000 at 03:35:55AM +1100, Rich Churcher wrote:
> 
> I think I'd make a pretty fair ghost writer for those among us who
> detest writing documentation, but have all the requisite technical
> understanding.  Are there outstanding areas that should be addressed
> before GCC 3.0?  For example, what about a document discussing changes
> from V2 to V3, implications for old code, tasks involved in upgrading,
> and so on?

That particular task is being tackled in docs/17_intro/porting-howto.html.
Any contributions are welcome.

I don't know how much longer there's going to be a "docs" subdir, though...
The project documentation == the project web pages, and the web pages are
being moved to a different repository module.


> I would love to see a V3 Manual come together, in a more cohesive form
> than what we have now.  Something that can be searched and printed.
> With an index and table of contents <g> you know, like a Real Library
> Implementation <*cough*>.  
> 
> What level of information this should include on standard library
> features (as opposed to libstdc++ implementation) I couldn't
> say... certainly, I would imagine an overview of the implementation
> would be beneficial: the headers and their interactions/dependencies,
> areas which are not yet caught up with the standard, etc.  I just get
> the feeling we need something a bit more formalised & complete for the
> next major release.

Yeah... this is an itch that I've considered scratching.  There are already
some excellent references on the library and how to use it (e.g., the
Josuttis text, the Austern text) and I don't want to reinvent the wheel.
So far our documentation has been mostly concerned with v3 in particular:
implementation features and failings, changes we plan on making, etc.

There was a good thread a couple months ago on writing a set of man
pages for the library.  Rogue Wave did something similar; their pages are
pre-standard but still useful, and in fact are shipped with at least one
major vendor's compiler.  There is a "C++ Man Page Project" at sourceforge
which looks like it was created and then immediately abandoned; I mailed
the project admin asking about status, etc, but never heard a response.


> slightest...  however, for what it's worth I have some free time and a
> sizeable quota of patience.  Hell, I'll just do proofing and editing
> if that's what's needed.  Or update and maintain web pages.  Or add
> FAQ items, if people can suggest likely candidates.

Hey, that's how I started contributing, and now I introduce bugs into the
config headers, testing script, and build infrastructure on a regular basis!

ehhhh... i coulda found a better way to say that...

My point is, fire up the last few month's mail archives and read through
any of the threads that look interesting to you, and then don't be afraid
to jump in and make suggestions.  The web pages are currently being shifted
around and we haven't yet decided on the best method of combining things
afterwards.  The FAQ is the same as any of the other pages, except that
you also need lynx to regenerate the plaintext version.  Proofing and
editing is /always/ needed.  :-)

Just running the testsuite on platforms that don't get a lot of attention
is useful.  And hey, if you find a bug in the code, don't hesitate to
apply your C++ coding skills.  You learn by doing, after all.


-- 
pedwards at disaster dot jaj dot com  |  pme at sources dot redhat dot com
devphil at several other less interesting addresses in various dot domains
The gods do not protect fools.  Fools are protected by more capable fools.