diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/manpage.example | 114 | ||||
| -rw-r--r-- | docs/manpage.example.mdoc | 134 | ||||
| -rw-r--r-- | docs/manpage.example.pod | 126 | ||||
| -rw-r--r-- | docs/manpage.example.sgml | 232 |
4 files changed, 606 insertions, 0 deletions
diff --git a/docs/manpage.example b/docs/manpage.example new file mode 100644 index 0000000..8a9d22e --- /dev/null +++ b/docs/manpage.example @@ -0,0 +1,114 @@ +.\" In .TH, FOO should be all caps, SECTION should be 1-8, maybe w/ subsection +.\" other parms are allowed: see man(7), man(1) +.\" +.\" This template provided by Tom Christiansen <tchrist@jhereg.perl.com>. +.\" +.TH FOO SECTION +.SH NAME +foo, bar \- programs to do something +.SH SYNOPSIS +A short usage summary. +.PP +.B foo +{ +.BR this | that +} +[ +.B -flags +] +[ +.B \-o +.I option +] +.I argument +[ +.I more... +] +.SH DESCRIPTION +.\" Putting a newline after each sentence can generate better output. +Long drawn-out discussion of the program. +It's a good idea to break this up into subsections using the .SS macro, +like these: +.SS "A Sample Subsection" +.SS "Yet Another Sample Subsection" +References to the +.BR foo (SECTION) +(or other) manual page should use the .BR macro as here. +.PP +Use the .PP macro to start a new paragraph within a section. +.SH OPTIONS +Some people make this separate from the description. +The following style is typically used to document options: +.TP +.BR this | that +The user MUST specify either +.B this +or +.B that +to run the program. +The { and } braces mean one of the enclosed is required. +The bar (|) separates exclusive options (i.e. you cannot have both at once). +.TP +.B \-o +Pass the user-supplied +.I option +to +.B foo +to change its behaviour. +The fact that +.I option +is underlined or in italics means that the user replaces it with a valid +value for this option. +The [ and ] brackets mean it isn't required. +.IP +Use \(oq\e-\(cq rather than \(oq-\(cq for dashes in command-line options. +\(oq-\(cq means hyphen, and formats differently when using certain output +devices. +.TP +.I argument +The last +.I argument +is required, because it is not in brackets. +.TP +.I more +means that the user can optionally specify additional arguments at the end. +The ellipses (...) indicate one or more of this parameter is allowed. +.SH "RETURN VALUE" +What the program or function returns if successful. +.SH ERRORS +Return codes, either exit status or errno settings. +.SH EXAMPLES +Give some example uses of the program. +.SH ENVIRONMENT +Environment variables this program might care about. +.SH FILES +All files used by the program. +Typical usage is like this: +.br +.nf +.\" set tabstop to longest possible filename, plus a wee bit +.ta \w'/usr/lib/perl/getopts.pl 'u +\fI/usr/man\fR default man tree +\fI/usr/man/man*/*.*\fR unformatted (nroff source) man pages +.SH NOTES +Miscellaneous commentary. +.SH CAVEATS +Things to take special care with, sometimes called WARNINGS. +.SH DIAGNOSTICS +All the possible error messages the program can print out, +what they mean, and how to correct them if applicable. +.SH BUGS +Things that are broken or just don't work quite right. +.SH RESTRICTIONS +Bugs you don't plan to fix. :-) +.SH AUTHOR +Who wrote it (or AUTHORS if multiple). +.SH HISTORY +Programs derived from other sources sometimes have this. +.SH "SEE ALSO" +.\" Always quote multiple words for .SH +Other man pages to check out, like +.BR man (1), +.BR man (7), +.BR mandb (8), +.BR catman (8). diff --git a/docs/manpage.example.mdoc b/docs/manpage.example.mdoc new file mode 100644 index 0000000..b10fee7 --- /dev/null +++ b/docs/manpage.example.mdoc @@ -0,0 +1,134 @@ +.\" -mdoc is a groff macro package supporting logical formatting. The author +.\" of this example considers it the best package available in groff for +.\" writing manual pages. If you're used to the traditional Unix -man +.\" macros, give this a try; it doesn't take long to learn. groff_mdoc(7) is +.\" a complete reference manual. +.\" +.\" Many of the macros below stack, so ".Op Ar foo" means an optional +.\" argument called "foo", while ".Ar foo" means an argument called "foo". +.\" Where you see things like ".Ql .Fl" below, the second dot causes ".Fl" +.\" to be interpreted as ordinary text rather than calling the .Fl macro. +.Dd June 4, 2005 +.Os FooOS +.Dt FOO 1 +.Sh NAME +.Nm foo +.Nd program to do something +.Sh SYNOPSIS +A short usage summary. +.Pp +.Nm +.Brq Cm this | Cm that +.Op Fl flags +.Op Fl o Ar option +.Ar argument +.\" Punctuation is treated specially by -mdoc, and often gets pushed up +.\" against whatever precedes it without the special formatting, so having +.\" an underlined argument immediately followed by a normal comma is easy. +.\" If you want to make sure this special handling isn't applied, put a +.\" zero-width space, \&, before the punctuation. +.Op Ar more \&... +.Sh DESCRIPTION +.\" Putting a newline after each sentence generates better output. +Long drawn-out discussion of the program. +It's a good idea to break this up into subsections using the +.Ql .Ss +macro, like these: +.Ss A Sample Subsection +.Ss Yet Another Sample Subsection +.Pp +References to the +.Xr foo SECTION +(or other) manual page should use the +.Ql .Xr +macro as here. +References to the +.Sx OPTIONS +(or other) section within this manual page should use the +.Ql .Sx +macro as here. +.Pp +Use the +.Ql .Pp +macro to start a new paragraph within a section. +.Sh OPTIONS +Some people make this separate from the description. +The following list style is typically used to document options: +.Bl -tag -width 4n +.It Cm this | Cm that +The user MUST specify either +.Cm this +or +.Cm that +to run the program. +The { and } braces (using the +.Ql .Brq +macro) mean one of the enclosed is required. +The bar (|) separates exclusive options (i.e. you cannot have both at once). +.It Fl o +Pass the user-supplied +.Ar option +to +.Nm +to change its behaviour. +The fact that +.Ar option +is underlined or in italics means that the user replaces it with a valid +value for this option. +The [ and ] brackets (using the +.Ql .Op +macro) mean it isn't required. +.Pp +Use the +.Ql .Fl +macro to render dashes in command-line option. +.It Ar argument +The last +.Ar argument +is required, because it is not in brackets. +.It Ar more +means that the user can optionally specify additional arguments at the end. +The ellipses +.Pf ( Ar ... ) +indicate one or more of this parameter is allowed. +.\" Remember to close lists you open with .Bl. +.El +.Sh RETURN VALUE +What the program or function returns if successful. +.Sh ERRORS +Return codes, either exit status or errno settings. +.Sh EXAMPLES +Give some example uses of the program. +.Sh ENVIRONMENT +Environment variables this program might care about. +.Sh FILES +All files used by the program. +Typical usage is like this: +.Pp +.Bl -tag -width "/usr/man/man*/*.*" -compact +.It Pa /usr/man +default man tree +.It Pa /usr/man/man*/*.* +unformatted (nroff source) man pages +.El +.Sh NOTES +Miscellaneous commentary. +.Sh CAVEATS +Things to take special care with, sometimes called WARNINGS. +.Sh DIAGNOSTICS +All the possible error messages the program can print out, +what they mean, and how to correct them if applicable. +.Sh BUGS +Things that are broken or just don't work quite right. +.Sh RESTRICTIONS +Bugs you don't plan to fix. :-) +.Sh AUTHOR +Who wrote it (or AUTHORS if multiple). +.Sh HISTORY +Programs derived from other sources sometimes have this. +.Sh SEE ALSO +Other man pages to check out, like +.Xr man 1 , +.Xr man 7 , +.Xr mandb 8 , +.Xr catman 8 . diff --git a/docs/manpage.example.pod b/docs/manpage.example.pod new file mode 100644 index 0000000..7c62de7 --- /dev/null +++ b/docs/manpage.example.pod @@ -0,0 +1,126 @@ +=head1 NAME + +foo, bar - programs to do something + +=head1 SYNOPSIS + +A short usage summary. + +B<foo> { B<this>|B<that> } [ B<-flags> ] [ B<-o> I<option> ] I<argument> [ I<more...> ] + +=head1 DESCRIPTION + +Long drawn-out discussion of the program. It's a good idea to break this +up into subsections using "=head2" directives, like these: + +=head2 A Sample Subsection + +=head2 Yet Another Sample Subsection + +References to the foo(1) (or other) manual page should be written normally +as here; B<pod2man> will usually guess the correct formatting. Use S<L><> +(e.g. L<foo(SECTION)>) if you need to force this. + +Paragraphs are separated by blank lines. + +=head1 OPTIONS + +Some people make this separate from the description. + +The following style is typically used to document options: + +=over 8 + +=item B<this>|B<that> + +The user MUST specify either B<this> or B<that> to run the program. The { +and } braces mean one of the enclosed is required. The bar (|) separates +exclusive options (i.e. you cannot have both at once). + +=item B<-o> + +Pass the user-supplied I<option> to B<foo> to change its behaviour. The +fact that I<option> is underlined or in italics means that the user replaces +it with a valid value for this option. The [ and ] brackets mean it isn't +required. + +=item I<argument> + +The last I<argument> is required, because it is not in brackets. + +=item I<more> + +means that the user can optionally specify additional arguments at the end. +The ellipses (...) indicate one or more of this parameter is allowed. + +=back + +=head1 RETURN VALUE + +What the program or function returns if successful. + +=head1 ERRORS + +Return codes, either exit status or errno settings. + +=head1 EXAMPLES + +Give some example uses of the program. + +=head1 ENVIRONMENT + +Environment variables this program might care about. + +=head1 FILES + +All files used by the program. Typical usage is like this: + +=over 8 + +=item F</usr/man> + +default man tree + +=item F</usr/man/man*/*.*> + +unformatted (nroff source) man pages + +=back + +=head1 NOTES + +Miscellaneous commentary. + +=head1 CAVEATS + +Things to take special care with, sometimes called WARNINGS. + +=head1 DIAGNOSTICS + +All the possible error messages the program can print out, what they +mean, and how to correct them if applicable. + +=head1 BUGS + +Things that are broken or just don't work quite right. + +=head1 RESTRICTIONS + +Bugs you don't plan to fix. :-) + +=head1 AUTHOR + +Who wrote it (or AUTHORS if multiple). + +This example was constructed by Colin Watson <S<cjwatson@debian.org>> +from a template provided by Tom Christiansen <S<tchrist@jhereg.perl.com>>. + +=head1 HISTORY + +Programs derived from other sources sometimes have this. + +=head1 SEE ALSO + +Other man pages to check out, like man(1), man(7), mandb(8), catman(8). + +For this example, see pod2man(1) for more details. diff --git a/docs/manpage.example.sgml b/docs/manpage.example.sgml new file mode 100644 index 0000000..c460680 --- /dev/null +++ b/docs/manpage.example.sgml @@ -0,0 +1,232 @@ +<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ + +<!-- Process this file with docbook-to-man to generate an nroff manual + page: `docbook-to-man manpage.sgml > manpage.1'. You may view + the manual page with: `docbook-to-man manpage.sgml | nroff -man | + less'. A typical entry in a Makefile or Makefile.am is: + +manpage.1: manpage.sgml + docbook-to-man $< > $@ + --> + +<!-- This example was constructed by Colin Watson + <email>cjwatson@debian.org</email>, based on a man page template + provided by Tom Christiansen <email>tchrist@jhereg.perl.com</email> + and a DocBook man page example by Craig Small + <email>csmall@debian.org</email>. + --> + + <!-- Fill in the various UPPER CASE things here. --> + <!ENTITY manfirstname "<firstname>FIRSTNAME</firstname>"> + <!ENTITY mansurname "<surname>SURNAME</surname>"> + <!-- Please adjust the date whenever revising the manpage. --> + <!ENTITY mandate "<date>DATE</date>"> + <!-- SECTION should be 1-8, maybe with subsection. Other parameters are + allowed: see man(7), man(1). --> + <!ENTITY mansection "<manvolnum>SECTION</manvolnum>"> + <!ENTITY manemail "<email>EMAIL</email>"> + <!ENTITY manusername "USERNAME"> + <!ENTITY manucpackage "<refentrytitle>UCPACKAGE</refentrytitle>"> + <!ENTITY manpackage "PACKAGE"> +]> + +<refentry> + <refentryinfo> + <address> + &manemail; + </address> + <author> + &manfirstname; + &mansurname; + </author> + <copyright> + <year>2002</year> + <holder>&manusername;</holder> + </copyright> + &mandate; + </refentryinfo> + <refmeta> + &manucpackage; + + &mansection; + </refmeta> + <refnamediv> + <refname>&manpackage;</refname> + + <refpurpose>program to do something</refpurpose> + </refnamediv> + <refsynopsisdiv> + <cmdsynopsis> + <command>&manpackage;</command> + + <group choice="req"><arg>this</arg><arg>that</arg></group> + <group choice="opt"><arg>-flags</arg></group> + <group choice="opt"> + <arg>-o <replaceable>option</replaceable></arg> + </group> + <arg>argument</arg> + <arg rep="repeat" choice="opt"><replaceable>more</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + <refsect1> + <title>DESCRIPTION</title> + + <para>Long drawn-out discussion of <command>&manpackage;</command>. + It's a good idea to break this up into subsections, like these:</para> + + <refsect2> + <title>A Sample Subsection</title> + <para></para> + </refsect2> + <refsect2> + <title>Yet Another Sample Subsection</title> + + <para>References to the + <citerefentry> + <refentrytitle>foo</refentrytitle><manvolnum>SECTION</manvolnum> + </citerefentry> (or other) manual page should use the + <markup><citerefentry></markup> element as here. + </para> + + <para>Each paragraph within a section is contained within a + <markup><para></markup> tag.</para> + </refsect2> + </refsect1> + <refsect1> + <title>OPTIONS</title> + + <para>Some people make this separate from the description.</para> + + <variablelist> + <varlistentry> + <term><option>this</option>|<option>that</option></term> + <listitem> + <para>The user MUST specify either <option>this</option> or + <option>that</option> to run the program. The { and } braces + mean one of the enclosed is required. The bar (|) separates + exclusive options (i.e. you cannot have both at once.)</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>-o</option></term> + <listitem> + <para>Pass the user-supplied <replaceable>option</replaceable> to + <command>foo</command> to change its behaviour. The fact that + <replaceable>option</replaceable> is underlined or in italics + means that the user replaces it with a valid value for this + option. The [ and ] brackets mean it isn't required.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>argument</option></term> + <listitem> + <para>The last <option>argument</option> is required, because it + is not in brackets.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>more</option></term> + <listitem> + <para>means that the user can optionally specify additional + arguments at the end. The ellipses (...) indicate one or more of + this parameter is allowed.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>RETURN VALUE</title> + + <para>What the program or function returns if successful.</para> + </refsect1> + <refsect1> + <title>ERRORS</title> + + <para>Return codes, either exit status or errno settings.</para> + </refsect1> + <refsect1> + <title>EXAMPLES</title> + + <para>Give some example uses of the program.</para> + </refsect1> + <refsect1> + <title>ENVIRONMENT</title> + + <para>Environment variables this program might care about.</para> + </refsect1> + <refsect1> + <title>FILES</title> + + <para>All files used by the program. Typical usage is like this:</para> + + <variablelist> + <varlistentry> + <term><filename>/usr/man</filename></term> + <listitem><para>default man tree</para></listitem> + </varlistentry> + <varlistentry> + <term><filename>/usr/man/man*/*.*</filename></term> + <listitem><para>unformatted (nroff source) man pages</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>NOTES</title> + + <para>Miscellaneous commentary.</para> + </refsect1> + <refsect1> + <title>CAVEATS</title> + + <para>Things to take special care with, sometimes called WARNINGS.</para> + </refsect1> + <refsect1> + <title>DIAGNOSTICS</title> + + <para>All the possible error messages the program can print out, what + they mean, and how to correct them if applicable.</para> + </refsect1> + <refsect1> + <title>BUGS</title> + + <para>Things that are broken or just don't work quite right.</para> + </refsect1> + <refsect1> + <title>RESTRICTIONS</title> + + <para>Bugs you don't plan to fix. :-)</para> + </refsect1> + <refsect1> + <title>AUTHOR</title> + + <para>Who wrote it (or AUTHORS if multiple).</para> + </refsect1> + <refsect1> + <title>HISTORY</title> + + <para>Programs derived from other sources sometimes have this.</para> + </refsect1> + <refsect1> + <title>SEE ALSO</title> + + <para>Other man pages to check out, like man(1), man(7), mandb(8), + catman(8).</para> + </refsect1> +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:2 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:nil +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> |