Re: What does 'safely' mean in man mktemp?

[Eric Blake]

On 12/16/2011 07:08 AM, Peng Yu wrote:
> On Wed, Dec 14, 2011 at 8:37 PM, Bob Proulx <address@hidden> wrote:
>> Peng Yu wrote:

Without regards to your specific concerns on mktemp, I'll try to answer
the bigger question:

> For the man page, it should be self-contained. Clearly the man page
> doesn't have any explanation for "safely". It should as least a
> sentence explaining what  "safely" means or at least refers to the
> info page (I'm not referring the reference at the bottom as that one
> is not specific to the word "safely").

The GNU Coding Standards requires info documentation, not man
documentation.  They also require concise --help output.

Coreutils (and many other GNU projects) specifically choose to convert
the --help output into a man page, since that is the lowest maintenance
path; the idea is that --help output (and thus the man page) is
intentionally a concise reference for someone already familiar with the
tool, and not an introductory manual, and should only focus on what is
essential to understanding the tool.

> 
> But if a reference is going to be added anyway. I'm wondering the
> necessity to make the info and man pages different.

The info pages are too complex to cram into either the --help output or
the man page format.  And since GNU Coding Standards already require two
formats (a concise --help output, and a comprehensive info page), we
don't want to make that burden any larger by adding yet a third format
for man pages, so it's easier to make the man page derive from the
--help output.

-- 
Eric Blake   address@hidden    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature