are the are C [or C++] src sites ....

[Robert Bonomi]

> From owner-freebsd-questions at freebsd.org  Mon Apr 12 21:05:40 2010
> Date: Mon, 12 Apr 2010 19:05:04 -0700
> From: Gary Kline <kline at thought.org>
> To: Alejandro Imass <ait at p2ee.org>
> Cc: FreeBSD Mailing List <freebsd-questions at freebsd.org>
> Subject: Re: are the are C [or C++] src sites ....
>
> On Mon, Apr 12, 2010 at 12:34:32PM -0400, Alejandro Imass wrote:
> > On Sat, Apr 10, 2010 at 11:19 AM, Gary Kline <kline at thought.org> wrote:
> > >
>
> 	[[ ... ]]
>
> > 
> > When you install a lib in FBSD (and many other FLOSS OSs) it usually
> > installs a man page, so apropos and of course man will have it: man
> > sprintf, so the detailed information is usually there...
> > 
> > The tricky part is having like a table of contents of some sort
> > especially at the library level which is what _I think_ you are
> > referring to. For example, to answer the question ¿what library should
> > I use for X or Y need? . If you use Perl, you have the cpan search
> > engine (and others) wher you go llook for libs. For C it is many times
> > not tha obvious, nor is there a single repository of libraries for C
> > as there is for say Perl.

If you find the approrpirate/relevant manpage, it _usually_ lists the
library or libraries that must be linked in with code that uses the function(s)
in question.

One has to remember that manpages are _reference_ documentation, *NOT* 
'teaching guides'.

For figuring out "what's where" on a grand scale, the libraries live in a
handful of "standard" places -- exactly where they are depends on the O/S
varient's filesystem structure, They're almost *always* in a directory 
named 'lib', for sure there's one under /usr, probably /usr/local, 
possibly /usr/share, /usr/contrib, or /usr/opt, plus one under whatever
point the X windows stuff is hiding.  Running 'nm' on each of the 
'lib{mumble}.a' files in each of those 'lib' directories, with a little
judicious postprocessing of the 'nm' output, will give you a list of the
'user callable' functions in each library.

When you find a function listed in the 'nm' output, and there is -not- any
manpage for function, you've found a manpage that 'needs to be written'.
Go to it!!    <grin>



Note to _ALL_ library documentation maintainers:  there -should- be a manpage
named after the _library_, that indexes the functions therein.  See the
curses(3) manpage for a _minimal_ example. (it needs som fleshing out of the
parameter sequences for vairous functions, and a minimal description of what
the various parameters -are-, all the curses functions work with a very
limited set of parameter types, -one- description of the types, before or
after all function lines, is sufficient. 

Note to 'curses' documentation maintainers:  the curses(3) manage is great,
*but* there needs to be 'stub' pages for _every_one_ of the 'curses' functions
as well -- they can consist of just a 'link' to the curses(3) page, so that 
_it_ displays, if you do 'man delch', for example.  The _reason_ for doing 
this is so that the function name, and one-line description, are indexed for 
apropos(1), and similar tools.  The curses(3) manpage needs some fleshing out,
per above.  The curses manpage is also _missing_ the standard ERRORS section.