=================================================================== RCS file: /cvs/mandoc/Attic/manuals.7,v retrieving revision 1.2 retrieving revision 1.4 diff -u -p -r1.2 -r1.4 --- mandoc/Attic/manuals.7 2009/03/22 14:09:38 1.2 +++ mandoc/Attic/manuals.7 2009/03/22 14:35:16 1.4 @@ -28,105 +28,54 @@ format or directory structure or device driver, it nee .Sh CLASSIFICATION Classify your system component. In .Ux , -each component has a -.Dq manual section , -which categorises the component's function. The section of a manual is -usually listed in parenthesis next to the component name, such as +each component has a manual section , which categorises the component's +function. The section of a manual is usually listed in parenthesis next +to the component name, such as .Xr ps 1 , section 1. You can query a manual explicitly by its section: +.Bd -literal -offset XXXX +% man \-s 1 ps +% apropos ps +.Ed .Pp -.Dl % man \-s 1 ps +The following table lists classifications and the applicable manual +sections: .Pp -The following table lists broad classifications and the applicable -manual sections: -.Pp -.\" LIST .Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact -.It Em Category -.Em Section(s) -.It Device -4 -.It Executable -1, 6, 8 -.It Function -2, 3, 9 -.It File-format -5 -.It Other -7 -.El -.\" SUBSECTION -.Ss Devices -Consists of hardware (and pseudo-) device driver documentation. Drivers -are unilaterally classified in section 4. -.Em Note : -these manuals are necessarily system- and architecture-specific. -.Pp -Example: -.Pp -.\" LIST -.Bl -tag -width "File-formatX" -offset indent -compact -.It Em Manual -.Em Description -.It Xr dc 4 -DEC/Intel 10/100 Ethernet device -.El -.\" SUBSECTION -.Ss Executables -Executables consist of runnable binaries. They're further classified by -operator utility: -.Pp -.\" LIST -.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact .It Em Section .Em Description .It 1 operator utilities -.It 8 -administrator utilities +.It 2 +system calls +.It 3, 3p, 3f +programming libraries (C, Perl, Fortran) +.It 5 +file and wire protocol formats .It 6 games +.It 7 +tutorials, documents and papers +.It 8 +administrator utilities +.It 9 +in-kernel routines .El .Pp -Examples: +Some examples in regular name/section form: .Pp .\" LIST -.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact +.Bl -tag -width "File-formatX" -offset indent -compact .It Em Manual .Em Description +.It Xr dc 4 +DEC/Intel 10/100 Ethernet device .It Xr usermod 8 modify user login information .It Xr cc 1 the C compiler .It Xr fortune 6 print a random adage -.El -.\" SUBSECTION -.Ss Functions -Function documentation describes programme source code, whether in the -form of libraries, modules or standalone sources. They're further -classified by context: -.Pp -.\" LIST -.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact -.It Em Section -.Em Description -.It 2 -system calls -.It 3, 3p, 3f -programming libraries (C, Perl, Fortran) -.It 9 -in-kernel routines -.El -.Pp -.Em Note : -section 2 and 9 manuals are necessarily system- and often -architecture-specific. Examples: -.Pp -.\" LIST -.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact -.It Em Manual -.Em Description .It Xr open 2 open or create a file for reading or writing .It Xr isspace 3 @@ -135,43 +84,19 @@ whitespace character test convert POD data to formatted roff .It Xr tsleep 9 process context sleep -.El -.\" SUBSECTION -.Ss File-formats -A file format usually describes the format of on-disc binary or text -data, although it can also be used to describe wire protocols (this is -usually best left to RFC). These manuals are unilaterally classified in -section 5. -.Pp -Example: -.Pp -.\" LIST -.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact -.It Em Manual -.Em Description .It Xr passwd 5 format of the password file -.El -.\" SUBSECTION -.Ss Other -Documents with no other classification are relegated to section 7. This -constitutes reference tutorials (such as this document) and other -miscellaneous information. -.Pp -Examples: -.Pp -.\" LIST -.Bl -tag -width "XXXXXXXXXXXX" -offset indent -compact -.It Em Manual -.Em Description -.It Xr ascii 7 -ASCII character sets .It Xr symlink 7 symbolic link handling .El .\" SECTION .Sh COMPOSITION -Prepare your composition environment. +Prepare your composition environment by copying over the manual template +from +.Pa /usr/share/misc/mdoc.template . +.Em \&Do not +start afresh or by copying another manual unless you know exactly what +you're doing! .\" SUBSECTION .Ss Naming Your component will need a name by which to query its contents via @@ -220,9 +145,9 @@ formal language reference macro reference .El .Pp -Don't merely copy existing manuals! Most systems distribute an mdoc -template to help you get started in -.Pa /usr/share/misc/mdoc.template . +Open the template you've copied into +.Pa name.section +and begin editing. .\" SUBSECTION .Ss Development Tools While writing, make sure that your manual is correctly structured: @@ -242,7 +167,6 @@ to version-control your work. If you wish the last ch your document's date, use the following RCS tag for the date macro: .Pp .Dl \&.Dd $Mdocdate: March 22 2009 $ -.Pp .\" SUBSECTION .Ss Viewing mdoc documents may be paged to your terminal with traditional @@ -289,7 +213,7 @@ The .Xr mdoc 7 and .Xr mdoc.samples 7 -files will be indispensable in guiding composition. In this section, we +files are indispensable in guiding composition. In this section, we introduce some .Ux manual best practices: @@ -330,7 +254,15 @@ publications, please use the .Sq \&Rs/Re block macros. .\" SUBSECTION -.Ss Types and Prototypes -If writing section 3 manuals, make sure that you correctly annotate your -variables and functions. This guarantees that cross-referncing between -function names and their prototypes works properly. +.Ss Formatting +Let the front-ends worry about formatting for you, but if you must think +about formatting (at times necessary, especially for tagged and columnar +lists), assume that your output device is a fixed-width terminal window: +.Bd -literal -offset indent +\&.Bl \-tag \-width "-o outfile" +\&.It \&Fl \&Ar outfile +.Ed +.Pp +You may assume that the width calculated by the string literal +.Qq Fl o Ar outfile +will be covered by the \-width argument.