Date: Tue, 20 Apr 2010 16:28:52 -0500 (CDT) From: Robert Bonomi <bonomi@mail.r-bonomi.com> To: freebsd-questions@freebsd.org Subject: Re: are the are C [or C++] src sites .... Message-ID: <201004202128.o3KLSqkh026229@mail.r-bonomi.com>
next in thread | raw e-mail | index | archive | help
> From owner-freebsd-questions@freebsd.org Mon Apr 12 21:05:40 2010
> Date: Mon, 12 Apr 2010 19:05:04 -0700
> From: Gary Kline <kline@thought.org>
> To: Alejandro Imass <ait@p2ee.org>
> Cc: FreeBSD Mailing List <freebsd-questions@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@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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201004202128.o3KLSqkh026229>