On 12/16/2011 07:08 AM, Peng Yu wrote: > On Wed, Dec 14, 2011 at 8:37 PM, Bob Proulx <[email protected]> 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 [email protected] +1-919-301-3266 Libvirt virtualization library http://libvirt.org
signature.asc
Description: OpenPGP digital signature
