* 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).