FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Debian > Debian Development

 
 
LinkBack Thread Tools
 
Old 09-12-2012, 08:47 PM
Vincent Danjean
 
Default question about section and name of a manpage

Hi,

In short, I would like to describe environment variables that
can modify the behavior of a library.
How should I name the manpage ? libXX ? libXX.so ? libXX.so.1 ? XX ?
In which section should I put this manpage ? (7 ?)
Note that I do not want to describe the API of the library.

With more details:

I'm upstream author and maintainer of a library that has multiple
packaged implementations. It is the libOpenCL.so.1 library. My
implementation in the ocl-icd project is free, but AMD, NVidia and
Intel also provide (non-free) implementations of libOpenCL.so.1.
Note that libOpenCL.so.1 is not a OpenCL implementation, it is just
a loader for real OpenCL implementations. So AMD, NVidia, Intel and
ocl-icd OpenCL loaders (libOpenCL.so.1) can be freely exchanged
(modulo the supported OpenCL version and bugs) and they
do *not* enforce one or another OpenCL implementation (AMD, NVidia,
Intel, Pocl, ...)

The libOpenCL.so.1 API comes from the OpenCL API. I do not want
to describe it in my manpage.
However, the ocl-icd implementation of libOpenCL.so.1 uses
environment variables in order to offer (non standard) extended
features (capability to test an ICD in its build tree, dump of
information about loaded OpenCL implementation, ...)
I would like to describe these environment variables in a
manpage but I do not know how to name it. I can think of :
- OpenCL (but user would better find official OpenCL here ?)
- libOpenCL
- libOpenCL.so
- libOpenCL.so.1
- ocl-icd (the name of the project providing this implementation)
- ???
And my first idea would be to put this manpage in the
section 7 (misc).

What do you think of all of that?

Regards,
Vincent

--
Vincent Danjean GPG key ID 0x9D025E87 vdanjean@debian.org
GPG key fingerprint: FC95 08A6 854D DB48 4B9A 8A94 0BF7 7867 9D02 5E87
Unofficial pkgs: http://moais.imag.fr/membres/vincent.danjean/deb.html
APT repo: deb http://people.debian.org/~vdanjean/debian unstable main


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 5050F4EA.7000507@free.fr">http://lists.debian.org/5050F4EA.7000507@free.fr
 
Old 09-12-2012, 09:36 PM
Samuel Thibault
 
Default question about section and name of a manpage

Vincent Danjean, le Wed 12 Sep 2012 22:47:38 +0200, a écrit :
> In short, I would like to describe environment variables that
> can modify the behavior of a library.
> How should I name the manpage ? libXX ? libXX.so ? libXX.so.1 ? XX ?

I'd say libXX.so, like we have ld.so.

Samuel


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 20120912213612.GC5224@type.youpi.perso.aquilenet.f r">http://lists.debian.org/20120912213612.GC5224@type.youpi.perso.aquilenet.f r
 
Old 09-12-2012, 10:09 PM
Ben Hutchings
 
Default question about section and name of a manpage

On Wed, Sep 12, 2012 at 10:47:38PM +0200, Vincent Danjean wrote:
> Hi,
>
> In short, I would like to describe environment variables that
> can modify the behavior of a library.
> How should I name the manpage ? libXX ? libXX.so ? libXX.so.1 ? XX ?

I think libXX is preferable (allows for the possibility of a
static library in the future) but you could also symlink to
make it available as libXX.so too.

I don't think the soversion should be included unless the
documentation is specific to the soversion (e.g. some major API
change).

> In which section should I put this manpage ? (7 ?)
> Note that I do not want to describe the API of the library.
[...]

I think section 7 is right for overview documentation like this.

Ben.

--
Ben Hutchings
We get into the habit of living before acquiring the habit of thinking.
- Albert Camus


--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 20120912220906.GZ29217@decadent.org.uk">http://lists.debian.org/20120912220906.GZ29217@decadent.org.uk
 

Thread Tools




All times are GMT. The time now is 06:23 AM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright ©2007 - 2008, www.linux-archive.org