manpages

NAME

SYNOPSIS

AVAILABILITY

DESCRIPTION

MANPAGE ORGANIZATION

MANPAGE SECTIONS

The man pages in WA2L/edrc are organized in the following sections which is very similar to the SunOS operating system:

man1

General Commands

man1m

Maintenance (administrative) Commands

man3

Library Functions and Library Commands

man4

File Formats and Configuration Files

MANPAGE STRUCTURE

MANPAGES FOR COMMANDS

NAME

name and short description of command.

SYNOPSIS

usage of the command.

AVAILABILITY

where the command is available (WA2L/edrc).

DESCRIPTION

detail command description.

OPTIONS

command line options.

ENVIRONMENT

environment variables that influence the command.

EXIT STATUS

all exit states of the command.

FILES

used files by the command.

EXAMPLES

examples of command usage.

SEE ALSO

reference to other man pages or documents.

NOTES

additional command notes that add additional information not given in the DESCRIPTION section.

BUGS

known bugs or limitations of the command.

AUTHOR

author(s) of the command and hint where to send bug reports and suggestions.

COPYRIGHT

copyright notice.

MANPAGES FOR CONFIGURATION FILES

NAME

name and short description of the file.

SYNOPSIS

file name and location.

AVAILABILITY

where the command is available (WA2L/edrc).

DESCRIPTION

detail file description.

FILEFORMAT

file format description.

OPTIONS

detail description of all configuration file settings (option,value pairs).

EXAMPLES

examples of the config file.

SEE ALSO

reference to other man pages or documents.

NOTES

additional command notes that add additional information not given in the DESCRIPTION section.

BUGS

known bugs or limitations of the command.

AUTHOR

author(s) of the command and hint where to send bug reports and suggestions.

COPYRIGHT

copyright notice.

CONVENTIONS FOLLOWED IN WA2L/edrc MAN PAGES

files

are set in bold face (.B).

directories

are set in bold face (.B).

indention steps

the indention for all sections, where labels are used is 10.

command line options

are set in bold face (.B).
  

configuration file options

are set in bold face (.B).

command line settings

are set in italic (.I).

configuration settings (=values)

are set in italic (.I).

using of foreign inventions

if parts of code, documentation or concepts from other individuals as the principal author of the command, config file or manual page is used those individuals should be mentioned in the NOTES and/or AUTHOR section of the man page.

references in SEE ALSO

each manual page should at least reference the edrcintro(1) man page.

edrcintro man page

each command that is distributed with WA2L/edrc must have a short description in the edrcintro(1) man page.

EDRC man page

each command and related config file that is distributed with WA2L/edrc must have an entry in the EDRC(1) man page, this is the main index to all commands and config files.

PostScript, PDF, HTML and eBook man pages

the man pages are formatted to PostScript, PDF, HTML and eBooks using the Makefiles located in doc/.man/. To generate the PostScript, PDF and HTML man pages invoke: cd ~edrc/doc/.man ; make. If a new man page is written or included to the WA2L/edrc package the doc/.man/Makefile has to be edited.

USED MANUAL PAGE MACROS WITH EXAMPLES

The list of macros available for man page exceeds the one given below by many more possibilities. The macros here are those used in the WA2L/edrc package and the explained usage is related to this special usage case. Therefore the option description is given for this particular usage. See groff_man(7) for a more complete description.

.TH

Set the title of the man page.

Format:

  .TH manpage section "day month year" "PACKAGE" "SECTION"

Example:

  .TH watchdog 1 "28 November 2005" "EDRC" "General Commands"

Result:

watchdog(1)         General Commands         watchdog(1)
:
:
EDRC                28 November 2005         watchdog(1)

.SH

Sets up an unnumbered section heading sticking out to the left.

Format:

  .SH TEXT

Example:

  .SH AVAILABILITY

Result:

AVAILABILITY

.SS

Sets up a secondary, unnumbered section heading.

Format:

  .SS TEXT

Example:

  .SS GLOBAL OPTIONS

Result:

GLOBAL OPTIONS

.TP

Sets up an indented paragraph list with label. The indentation is set to nnn if that argument is supplied (the default unit is 'n' if omitted), otherwise it is set to the default indentation value.

The first line of text following this macro is interpreted as a string to be printed flush-left, as it is appropriate for a label. It is not interpreted as part of a paragraph, so there is no attempt to fill the first line with text from the following input lines.

Nevertheless, if the label is not as wide as the indentation, then the paragraph starts at the same line (but indented), continuing on the following lines. If the label is wider than the indentation, then the descriptive part of the paragraph begins on the line following the label, entirely indented.

Format:

  .TP indent
  .B label_1
  description text

  .TP
  .B label_2
  description text

Example:

  .TP 10
  .B \-h
  usage message.

  .TP
  .BI "\-n " name
  name of the watchdog.

Result:

-h

usage message.

-n name

name of the watchdog.

.IP

Sets up a indented list with a marker.

Format:

  .IP marker [ width ] 
  description text

  .IP marker
  description text

Example:

  available colors are:

  .IP - 2
  red

  .IP -
  green

  .IP -
  yellow

Result:

available colors are:

-

red

-

green

-

yellow

.PP

End an indented paragraph list.

This is only needed, when additional text has to be set in the same section after the indented list.

Format:

  .TP indent
  .B label_1
  description text

  .TP
  .B label_2
  description text
  .PP

  non indented text

Example:

  .TP 10
  .B Mauna Kea 
  Shield volcano in Hawaii. 

  .TP
  .B Parinacota
  Strato volcano in Chile near the border to Bolivia.
  .PP

  For a list of all volcanos, see:  
  .B https://www.volcanodiscovery.com/de/volcanoes/alphabetical-list/a-z.html

Result:

Mauna Kea

Shield volcano in Hawaii.

Parinacota

Strato volcano in Chile.

For a list of all volcanos, see: https://www.volcanodiscovery.com/de/volcanoes/alphabetical-list/a-z.html

.RS

This macro moves the left margin to the right by the value nnn if specified (default unit is 'n'; otherwise the default indentation value is used. Calls to the RS macro can be nested.

Format:

  .RS +number

Example:

  .RS +10
  This text is moved by 10 characters to the right.
  .RE

Result:

  This text is moved by 10 characters to the right.

.RE

This macro moves the left margin back to level nnn; if no argument is given, it moves one level back. The first level (i.e., no call to RS yet) has number 1, and each call to RS increases the level by 1.

Format:

  .RE

Examples:

  .RS +10
  This text is moved by 10 characters to the right.
  .RS +5
  This text is moved 5 more characters to the right.
  .RE
  .RE

Result:

This text is moved by 10 characters to the right.

This text is moved 5 more characters to the right.

.B

Causes text to appear in bold face. If no text is present on the line where the macro is called, then the text of the next line appears in bold face.

Format:

  .B text

Example:

  .B abort

Result:

abort

.I

Causes text to appear in italic. If no text is present on the line where the macro is called, then the text of the next line appears in italic.

Format:

  .I italic text

Example:

  .I check_script

Result:

check_script

.BI

Causes text on the same line to appear alternately in bold face and italic. The text must be on the same line as the macro call.

Format:

  .BI bold italic

Example:

  .BI "-c " check_script

Result:

-c check_script

.IB

Causes text on the same line to appear alternately in italic and bold face. The text must be on the same line as the macro call.

Format:

  .IB italic bold

Example:

  .IB filename ".txt"

Result:

filename.txt

.BR

Causes text on the same line to appear alternately in bold face and roman. The text must be on the same line as the macro call.

Format:

  .BR bold roman

Example:

  .BR edrcintro (1)

Result:

edrcintro(1)

.RB

Causes text on the same line to appear alternately in roman and bold face. The text must be on the same line as the macro call.

Format:

  .RB roman bold

Example:

  .BR ( /etc/hosts )

Result:

(/etc/hosts)

USED TROFF COMMANDS WITH EXAMPLES

This are commands and escape sequences that were used in the WA2L/edrc manual pages and have been proofed to be compatible over various platforms and understood by troff(1) and the GNU variant groff(1). There are many more troff/groff commands available on the various Unix and Linux dialects as the ones explained here. For more information see troff(1), groff(1) and groff_char(7).

\(space)

Set a space. This is useful if after a .SS an empty line should be printed.

Format:

  \

Example:

  .SS "Step 5: Configure logcheckd"
  \

  The daemon is configured editing ...

\&.

Set a dot (.). This is useful if you have to set a dot at the beginning of a line.

Format:

  \&.

Example:

  the check specified in option
  .B -c
  \&. If the

Result:

the check specified in option -c. If the

.ds

Define a shortcut that can be used in the whole manpage.

Format:

  .ds name content

Example:

  .ds PK WA2L/edrc

  This is the install directory of the \*(PK package.  

Result:

This is the install directory of the WA2L/edrc package.

.\

Comment in a man page.

Format:

  .\" comment text

Example:

  .\"
  .\" manpages.4 - man page for writing manual pages
  .\"
  .\" [00] 17.06.2006 CWa       Initial Version
  .\"

.nf

The following lines are not formatted and the output is made verbatim as typed. However, shortcuts are resolved.

Format:

  .nf
  verbatim text
  .fi

Example:

  .nf
  #
  # /etc/hosts - internet hosts list
  #
  # [00] 01.01.2000 CWa   Initial Version 
  #
  127.0.0.1        localhost
  192.168.75.1     w2mzv7t001
  192.168.75.129   fc4mzv7t001
  .fi

.fi

End of verbatim output.

Format:

  .nf
  verbatim text
  .fi

Example:

  .nf
  #
  # /etc/hosts - internet hosts list
  #
  # [00] 01.01.2000 CWa   Initial Version 
  #
  127.0.0.1        localhost
  192.168.75.1     w2mzv7t001
  192.168.75.129   fc4mzv7t001
  .fi

.br

Insert a line break.

Format:

  .br

Example:

  This is the first,
  .br
  that the second and
  .br
  this is the third line.

Result:

This is the first,
that the second and
this is the third line.

.bp

Insert a page break in PostScript/PDF output.

Format:

  .bp

Example:

  This is on one page,
  .bp
  And this is on the next page.

'

Insert a single quote (').

Format:

  '

Example:

  .BI MESSAGE=' Text ' 

Result:

MESSAGE='Text'

"

Insert a formatted double quote (").

Format:

  .BI "bold=\"" underlined "\""

Example:

  .BI "MESSAGE=\"" Text "\""

Result:

MESSAGE="Text"

\

Insert a backslash (\).

Format:

  \e

Example:

  find /data -depth -print \e
    cpio -dtvum /save

Result:

find /data -depth -print \
  cpio -dtvum /save

\(co

Insert the copyright symbol (©).

Format:

  \(co

Example:

  Copyright \(co 2009 by ACME Switzerland 

Result:

Copyright © 2009 by ACME Switzerland

\™

Insert the trade mark symbol (™).

Format:

  \™

Example:

  Trade Mark \™ 2009 by ACME Switzerland

Result:

Trade Mark ™ 2009 by ACME Switzerland

.ft CW

Switch font to Courier from current line forward. This is seen in a PostScript, PDF or HTML output only.

Format:

  .ft CW
  Text in Courier  
  .ft R
  Text in Times Roman

Example:

  .ft CW
  ls -lisa *.txt
  .ft R

.ft R

Switch font to Times Roman from current line forward. This is seen in a PostScript, PDF or HTML output only.

Format:

  .ft CW
  Text in Courier  
  .ft R
  Text in Times Roman

Example:

  .ft CW
  ls -lisa *.txt
  .ft R

\fB

Switch font to bold from within a line forward.

\fI

Switch font to italic from within a line forward.

\fC

Switch font to Courier from within a line forward.

\f(CW

Switch font to Courier from within a line forward.

\fR

Switch font to Times Roman from within a line forward.

\fP

Switch font to previous font setting from within a line forward.

Format:

  \fB

Example:

  \fBcp \fR[ \fIoption\fR ] \fIsource dest

Result:

cp [ option ] source dest

USEFUL OWN DEFINED MACROS

\*(GO

print an "=>" arrow on the terminal and a typographic "->" arrow in a PostScript file.

Definition:

  .\" print => on terminal, -> on PostScript
  .if n .ds GO =>
  .if t .ds GO \(->
  ..

Format:

  \*(GO text 

Example:

  \*(GO goto step 1.

Result:

→ goto step 1.

\*(co

print an "(c)" copyright on the terminal and a typographic "(c)" copyright symbol, a c in a circle, in a PostScript file.

Definition:

  .\" print (c) on terminal, c in circle on PostScript
  .if n .ds co (c)
  .if t .ds co \(co
  ..

Format:

  Copyright \*(co by ACME Switzerland

Example:

  Copyright \*(co by ACME Switzerland

Result:

Copyright (c) by ACME Switzerland

.VB .VE

Verbatim Begin, Verbatim End. Set the text between .VB and .VE verbatim and in Courier font.

Definition:

  .de VB \" verbatim begin
  .ft CW
  .nf
  ..

  .de VE \" verbatim end
  .ft R
  .fi
  ..

Format:

  .VB
  verbatim text set in courier
  .VE

Example:

  .VB
  #
  # /etc/hosts - internet hosts list
  #
  # [00] 01.01.2000 CWa   Initial Version 
  #
  127.0.0.1        localhost
  192.168.75.1     w2mzv7t001
  192.168.75.129   fc4mzv7t001
  .VE

Result:

#
# /etc/hosts - internet hosts list
#
# [00] 01.01.2000 CWa   Initial Version 
#
127.0.0.1        localhost
192.168.75.1     w2mzv7t001
192.168.75.129   fc4mzv7t001

.LS .LI .LE

List Start, List Item, List End. Create a unnumbered indented list with list items preceded by a dash (-).

Definition:

  .de LS \" List Start
  .PD 0
  .RS 10
  ..

  .de LI \" List Item
  .IP - 2
  ..

  .de LE \" List End
  .RE
  .PP
  ..

Format:

  .LS
  .LI
  first list item
  .LI
  another list item
  .LI
  one more list item
  .LE

Example:

  .LS
  .LI
  Bern is the capital of Switzerland.
  .LI
  Berlin is  the capital of Germany.
  .LI
  Paris is the capital of France.
  .LI
  Rome is the capital of Italy.
  .LE

Result:

-

Bern is the capital of Switzerland.

-

Berlin is the capital of Germany.

-

Paris is the capital of France.

-

Rome is the capital of Italy.

 

SEE ALSO

NOTES

BUGS

AUTHOR

COPYRIGHT

This is free software; see edrc/doc/COPYING for copying conditions. There is ABSOLUTELY NO WARRANTY; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.