Contents

man(8) documentation guidelines and standards

man(8) documentation guidelines and standards

This is a guide for a standard manual page documentation format and template. The aim is to allow documentation writers to focus on documentation and not on specific format and semantics, and to help integrate new texts with translation string automation.

Entities to be documented

All application binary, scripts, and configuration files installed on end server systems are to be documented with a manual page.

Documentation format

Use simplified ngroff syntax. see http://www.fnal.gov/docs/products/ups/ReferenceManual/html/manpages.html for ngroff format details.

Some additional markup is added for integration with po4a translation automation. see http://po4a.alioth.debian.org/man/man3pm/Locale::Po4a::Man.3pm.php for details on specific markup and limits imposed by those tools.

Each .SH section is preceded by an empty line. In ngroff syntax that is a line containing only a dot (.) as demonstrated below between the .TH line and the first .SH line.

The document overview is as follows. Introductory header markup as shown followed by any applicable sections. Which are detailed in more depth below.

.if !'po4a'hide' .TH binary.name 8
.
.SH NAME
.SH SYNOPSIS
.SH DESCRIPTION
.SH OPTIONS
.SH CONFIGURATION
.SH KNOWN ISSUES
.SH AUTHOR
.SH COPYRIGHT
.SH QUESTIONS
.SH REPORTING BUGS
.SH SEE ALSO

.SH NAME

One initial line of content.

name of file being documented. Marked not for translation.
a hyphen. Marked not for translation.
A one-line description of the file. Suitable for use in a title.

If a version number is relevant state it in a separate paragraph below the name details.

For example:

.
.SH NAME
squid \- HTTP Web Proxy caching server.
.PP
Version 1.0

documents

squid - HTTP Web Proxy caching server.

Version 1.0

.SH SYNOPSIS

The plain command line option syntax.

If an option takes a parameter those parameter descriptors are to be left open for translation. All other parts of the syntax are to be marked not for translation.

For example:

.
.SH SYNOPSIS
.if !'po4a'hide' .B squid
.if !'po4a'hide' .B [\-dh]
.if !'po4a'hide' .B [\-f
config\-file
.if !'po4a'hide' .B ]

documents:

squid [-dh] [-f config-file ]

.SH DESCRIPTION

The full description of what the file object is all about. It should but is not required to begin with the file name in bold. Paragraphs in the description are separated by .PP tags.

Use .if !'po4a'hide' to mark any lines of syntax as not for translation.

Any words which name a file or binary should be marked out in bold.

For example:

.
.SH DESCRIPTION
.PP
.B squid
is a high-performance proxy caching server for web clients,
supporting FTP, gopher, ICAP, ICP, HTCP and HTTP data objects.
Unlike traditional caching software,
Squid handles all requests in a single, non-blocking process.
.PP
Squid keeps meta data and especially hot objects cached in RAM,
caches DNS lookups, supports non-blocking DNS lookups, and implements
negative caching of failed requests.
.
.if !'po4a'hide' http://www.squid-cache.org/

.SH OPTIONS

A fully documented list of available command line options. With an empty line between each. The table column offset of the description text is 12 characters, set on the first .TP tag.

The option switch and any accepted variable names are marked not for translation (unlike in synopsis).

The option description is open for translation. Any repetition of the variable name is highlighted in bold.

For example:

.
.SH OPTIONS
.if !'po4a'hide' .TP 12
.if !'po4a'hide' .B \-d
Write debug info to stderr.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B "\-f config\-file"
Use configuration file
.B config\-file

.SH CONFIGURATION

Optional section specific to application binaries and maybe helper scripts.

Configuration files have their syntax covered under .SH DESCRIPTION

This section should cover snippets of config. Usually from squid.conf. Actual config snippets are to be marked not for translation.

For a multi-line configuration block use .br (lower case is important) to split the lines legibly.

$/!\$ Any word which begins with a dash / hyphen must be slash-escaped.

For example, URL re-writers would have something like this:

.
.SH CONFIGURATION
.PP The simplest configuration for URL re-writers is to add the script or binary name to
.B squid.conf
like so:
.if !'po4a'hide' .RS
.if !'po4a'hide' .B url_rewrite_program /usr/bin/squid/example.binary
.if !'po4a'hide' .RE
.PP Command line options sent to a helper script or binary are added to
.B squid.conf
following the helper binary name. Like so:
.if !'po4a'hide' .RS
.if !'po4a'hide' .B url_rewrite_program /usr/bin/squid/example.binary \-d
.if !'po4a'hide' .br
.if !'po4a'hide' .B url_rewrite_access ...
.if !'po4a'hide' .RE

.SH KNOWN ISSUES

Optional section specific to application binaries and maybe helper scripts.

Simple set of .PP paragraphs outlining the problems which are known with using the program or script.

.SH AUTHOR

A list of relevant paragraphs specific to the authorship style of the documented program, script or file. Each paragraph ending with a list of author names and contacts and separated by a .PP tag.

For a simple binary or script where the manual was also authored by the same individual(s):

.
.SH AUTHOR
This program and documentation was written by
.if !'po4a'hide' .I Authors Name <[email protected]>

For a more complicated case where the application has one or more authors and is based on a prior work:

.
.SH AUTHOR
This program was written by
.if !'po4a'hide' .I Authors Name <[email protected]>
.if !'po4a'hide' .I Authors Name <[email protected]>
.if !'po4a'hide' .I Authors Name <[email protected]>
.PP
Based on prior work in
.B older.source
by
.if !'po4a'hide' .I Authors Name <[email protected]>

Where the manual documentation was by a different author or authors than the program:

.
.SH AUTHOR
This program was written by
.if !'po4a'hide' .I Authors Name <[email protected]>
.PP
This manual was written by
.if !'po4a'hide' .I Authors Name <[email protected]>

.SH COPYRIGHT

Details of the copyright associated with this binary, script, or configuration file.

For example:

.
.SH COPYRIGHT
.PP
 * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
.PP
Squid
.B example.binary
and this manual is Copyright 2010
.if !'po4a'hide' .I Authors Name <[email protected]>
.PP
Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

If no exact copyright details are known use the following snippet:

.
.SH COPYRIGHT
.PP
 * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
.PP
This program and documentation is copyright to the authors named above.
.PP
Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

.SH QUESTIONS

Verbatim snippet detailing the Squid project user help contacts.

.
.SH QUESTIONS
Questions on the usage of this program can be sent to the
.I Squid Users mailing list
.if !'po4a'hide' <[email protected]>

.SH REPORTING BUGS

Should begin with a standard text describing the Squid project points of contact:

.
.SH REPORTING BUGS
Bug reports need to be made in English.
See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
.PP
Report bugs or bug fixes using http://bugs.squid-cache.org/
.PP
Report serious security bugs to
.I Squid Bugs <[email protected]>
.PP
Report ideas for new improvements to the
.I Squid Developers mailing list
.if !'po4a'hide' <[email protected]>

Any further points of contact or reporting should be listed following the Squid project contacts and be written in a similar syntax.

.SH SEE ALSO

References to other documentation related to this file.

Each item listed should have a line of its own for easy readability and to allow individual items to be marked not for translation.

Should start with a list of other manual pages, followed by a list of described external resources.

For example:

.
.SH SEE ALSO
.if !'po4a'hide' .B squid "(8), "
.if !'po4a'hide' .B cachemgr.cgi "(8), "
.if !'po4a'hide' .BR GPL "(7), "
.br
The Squid FAQ wiki
.if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
.br
The Squid Configuration Manual
.if !'po4a'hide' http://www.squid-cache.org/Doc/config/

Templates

name.8 file

This is a template only. Alter it according to the requirements detailed above to document an installed file.

.if !'po4a'hide' .TH binary.name 8
.
.SH NAME
.if !'po4a'hide' .B binary.name
.if !'po4a'hide' \-
Description goes here
.PP
Version 1.0
.
.SH SYNOPSIS
.if !'po4a'hide' .B binary.name
.if !'po4a'hide' .B [\-dh]
.
.SH DESCRIPTION
.B binary.name
is an installed binary. The long description goes here
.
.SH OPTIONS
.if !'po4a'hide' .TP 12
.if !'po4a'hide' .B \-d
Write debug info to stderr.
.
.if !'po4a'hide' .TP
.if !'po4a'hide' .B \-h
Display the binary help and command line syntax info using stderr.
.
.SH KNOWN ISSUES
.PP
Optional test goes here. If there is nothing major remove the whole section.
.
.SH CONFIGURATION
.PP See FAQ wiki page for examples of how to write configuration snippets.
.PP Or just write what you want to say, then mark it up according to the wiki styles.
.
.SH AUTHOR
This program was written by
.if !'po4a'hide' .I Authors Name <[email protected]>
.if !'po4a'hide' .I Authors Name <[email protected]>
.PP
Based on prior work in
.B older.source
by
.if !'po4a'hide' .I Authors Name <[email protected]>
.PP
This manual was written by
.if !'po4a'hide' .I Authors Name <[email protected]>
.
.SH COPYRIGHT
.PP
 * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
.PP
This program and documentation is copyright to the authors named above.
.PP
Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).
.
.SH QUESTIONS
Questions on the usage of this program can be sent to the
.I Squid Users mailing list
.if !'po4a'hide' <[email protected]>
.
.SH REPORTING BUGS
Bug reports need to be made in English.
See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.
.PP
Report bugs or bug fixes using http://bugs.squid-cache.org/
.PP
Report serious security bugs to
.I Squid Bugs <[email protected]>
.PP
Report ideas for new improvements to the
.I Squid Developers mailing list
.if !'po4a'hide' <[email protected]>
.
.SH SEE ALSO
.if !'po4a'hide' .BR squid "(8), "
.if !'po4a'hide' .BR GPL "(7), "
.br
The Squid FAQ wiki
.if !'po4a'hide' http://wiki.squid-cache.org/SquidFaq
.br
The Squid Configuration Manual
.if !'po4a'hide' http://www.squid-cache.org/Doc/config/

name.pl.in file

Perl code can be documented inline using pod2man syntax rather than have a separate .8 file.

This is a template only. Alter it according to the requirements detailed above to document an installed file.

 #!@PERL@

use strict;
use Pod::Usage;
use Getopt::Long;

=pod

=head1 NAME

binary.name - Brief Description goes here

Version 1.0

=head1 SYNOPSIS

 binary.name [options]

=head1 DESCRIPTION

 B<binary.name> is an installed binary. The long description goes here.

=head1 OPTIONS

=over 12

=item B<--debug>

Write debug info to stderr.

=item B<--help>

Display the binary help and command line syntax info using stderr.

=back

=head1 KNOWN ISSUES

Optional test goes here. If there is nothing major remove the whole section.

=head1 CONFIGURATION

See FAQ wiki page for examples of how to write configuration snippets.

Or just write what you want to say, then mark it up according to the wiki styles.

=head1 AUTHOR

This program was written by
I<Authors Name <[email protected]>> ,
I<Authors Name <[email protected]>>

Based on prior work in B<older.source> by I<Authors Name <[email protected]>>

This manual was written by I<Authors Name <[email protected]>>

=head1 COPYRIGHT

 * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

=head1 QUESTIONS

Questions on the usage of this program can be sent to the I<Squid Users mailing list <[email protected]>>

=head1 REPORTING BUGS

Bug reports need to be made in English.
See http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using http://bugs.squid-cache.org/

Report serious security bugs to I<Squid Bugs <[email protected]>>

Report ideas for new improvements to the I<Squid Developers mailing list <[email protected]>>

=head1 SEE ALSO

squid (8), GPL (7),

The Squid FAQ wiki http://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/

=cut

# the script code follows

TODO

The Manual best practice is to provide a man(x) page for each file installed on a server system. Squid installs a number of files of various types as listed below. Some work is underway to bring existing texts into matching these standard style of markup. However there are a number of installed files which have no manual at all.

Installed file	man(x)	Current State:
~/access.log		Missing. Relevant?
~/cache.log		Missing. Relevant?
~/netdb.state		Missing.
~/store.log		Missing. Relevant?
~/swap.state		Missing. Convert wiki page info
errors/errpages.css		Missing
helpers/basic_auth/DB/basic_db_auth	8	Done.
helpers/basic_auth/getpwnam/basic_getpwnam_auth	8	Done.
helpers/basic_auth/LDAP/basic_ldap_auth	8	Done.
helpers/basic_auth/NCSA/basic_ncsa_auth	8	Done.
helpers/basic_auth/NIS/basic_nis_auth		Missing.
helpers/basic_auth/PAM/basic_pam_auth	8	Done.
helpers/basic_auth/POP3/basic_pop3_auth	8	Done.
helpers/basic_auth/RADIUS/basic_radius_auth	8	Done.
helpers/basic_auth/SASL/basic_sasl_auth	8	Done.
helpers/basic_auth/SASL/basic_sasl_auth.pam		Missing.
helpers/basic_auth/SASL/basic_sasl_auth.conf		Missing.
helpers/basic_auth/SMB/basic_smb_auth		Missing.
helpers/basic_auth/SMB/basic_smb_auth.sh		Missing.
helpers/basic_auth/SMB_LM/basic_smb_lm_auth		Missing. Convert README.html
helpers/basic_auth/SSPI/basic_sspi_auth.exe	8	Done.
helpers/digest_auth/eDirectory/digest_edir_auth		Missing.
helpers/digest_auth/LDAP/digest_ldap_auth		Missing.
helpers/digest_auth/file/digest_file_auth	8	Done.
helpers/external_acl/delayer/ext_delayer_acl	8	Done.
helpers/external_acl/AD_group/ext_ad_group_acl	8	Done.
helpers/external_acl/file_userip/ext_file_userip_acl	8	Done.
helpers/external_acl/kerberos_ldap_group/ext_kerberos_ldap_group_acl	8	Done.
helpers/external_acl/LDAP_group/ext_ldap_group_acl	8	Done.
helpers/external_acl/LM_group/ext_lm_group_acl	8	Done.
helpers/external_acl/session/ext_session_acl	8	Done.
helpers/external_acl/SQL_session/ext_sql_session_acl	8	Done.
helpers/external_acl/unix_group/ext_unix_group_acl	8	Done.
helpers/external_acl/wbinfo_group/ext_wbinfo_group_acl	8	Done.
helpers/log_daemon/file/log_file_daemon		Missing.
helpers/log_daemon/DB/log_db_daemon	8	Check pod2man syntax
helpers/negotiate_auth/kerberos/negotiate_kerberos_auth	8	Done.
helpers/negotiate_auth/kerberos/negotiate_kerberos_auth_test		Missing. Convert README
helpers/negotiate_auth/SSPI/negotiate_sspi_auth.exe		Missing. Convert readme.txt
helpers/negotiate_auth/wrapper/negotiate_wrapper		Missing.
helpers/ntlm_auth/fake/ntlm_fake_auth		Missing. Convert wiki NTLM fake auth page.
helpers/ntlm_auth/smb_lm/ntlm_smb_lm_auth		Missing
helpers/ntlm_auth/SSPI/ntlm_sspi_auth.exe	8	Done.
helpers/ssl/cert_valid.pl		Missing. Convert intro text with pod2man
helpers/storeid_rewrite/file/storeid_file_rewrite	8	Done.
helpers/url_rewrite/fake/url_fake_rewrite		Missing
helpers/url_rewrite/fake/url_fake_rewrite.sh		Missing
helpers/url_rewrite/LFS/url_lfs_rewrite	8	Done.
src/dnsserver		Missing
src/mime.conf		Missing
src/mime.conf.default		Missing. Symlink to mime.conf manual?
src/recv-announce		Missing.
src/squid	8	Done.
src/squid.conf		Missing. Convert squid.conf.documented
src/squid.conf.default	N/A	http://www.squid-cache.org/Doc/config/ instead
src/squid.conf.documented	N/A	http://www.squid-cache.org/Doc/config/ instead
src/unlinkd		Missing
src/DiskIO/DiskDaemon/diskd		Missing
src/icmp/pinger		Missing
tools/cachemgr.cgi	8	Done.
tools/purge/	1	Done.
tools/squidclient/	1	Done.
tools/helper-mux.pl	8	Needs review of the perl/pod output.

Discuss this page using the "Discussion" link in the main menu

See Discussed Page

I like the idea. Would it be possible to have a complete template page attached to the wiki entry? It would make starting to write stuff easier.

-- FrancescoChemolli 2010-01-11 10:30:11

ProgrammingGuide/ManualDocumentation (last edited 2015-01-02 03:06:32 by AmosJeffries)

Navigation

Page

Search

User

man(8) documentation guidelines and standards

Entities to be documented

Documentation format

.SH NAME

.SH SYNOPSIS

.SH DESCRIPTION

.SH OPTIONS

.SH CONFIGURATION

.SH KNOWN ISSUES

.SH AUTHOR

.SH COPYRIGHT

.SH QUESTIONS

.SH REPORTING BUGS

.SH SEE ALSO

Templates

name.8 file

name.pl.in file

TODO