contrib.doc

NAME

SYNOPSIS

AVAILABILITY

DESCRIPTION

The documentation is compiled out of commented sections of a recovery script or menu title.

A documentation is structured into several sections similar to Unix man pages. To place text into a documentation section, each line has to be preceded by a section tag consisting of a capital letter and a colon.

To write text for the DESCRIPTION section, the recovery script looks like this:

:
#
# D: This is an example that is displayed as
# D: justified text in the DESCRIPTION section
# D: of the documentation when displayed
# D: with the 'doc' contributed command.
#
:

It is not necessary that all your documentation is done at the beginning of a recovery script. Suppose your script conducts several steps; it might make sense that you enter the documentation near the single steps to ensure an update if the code changes in the future.

PREDEFINED DOCUMENTATION SECTIONS

NAME

The name and short description of a menu point as shown when the menu is displayed using the menu command in edrc. This section is dynamically generated.

AVAILABILITY

This section contains information about the SCRIPTS_BASEDIR you are currently in.

A second line prints the logical menu path where you are in, i.e. which menus you have to enter to go to the menu or menupoint. This section is dynamically generated.

D: DESCRIPTION

Description text. The output format is justified. If you want to set an empty line, simply enter a D: without text.

Example:

#
# D: The database to be refreshed has been
# D: stopped and removed by the Storage Mgmt group.
# D:
# D: If the "oracle server" or "oracle instance" is 
# D: "up", contact the Storage Mgmt group.
#

R: RE-RUN ALLOWED?

The intention of this sections is to either enter YES or NO or some other text to document if a menu point can be restarted immediately without side effects.

Example:

#
# R: YES
#

O: OUTPUT-EXAMPLE

Verbatim output of entered text. Here no text formatting takes place.

Example 1:

#
# O: PERMISSION  OWNER   GROUP  DIRECTORY
# O: drwxr-x---  oracle  dba    /ora01/oradata/DWHPROD
# O: drwxr-x---  oracle  dba    /ora02/oradata/DWHPROD
# O: drwxr-x---  oracle  dba    /ora03/oradata/DWHPROD
#

Example 2 (using .SS SubSection Title to create two output sub-sections):

#
# O: .SS If host acme007 is up:
# O: 22:26:53 up  3:51,  1 user,  load average: 0.09, 0.15, 0.22
#
# O: .SS If host acme007 is not up: 
# O: ssh-exec-ERROR: remote system 'acme007' is not up, aborting.
#

To efficiently get data from a log file, use the outex(1) command from within the vi session, using:

#
#
~
~
~
:. !outex 2009-09-22_13.10.22__list_db_files.log

L: LIMITATIONS

Document limitations (or bugs) of the recovery script. The output format is justified. If you want to set an empty line, simply enter a L: without text.

Example:

#
# L: The UID (User-ID) and UNAME (User-name)
# L: cannot be changed in this tool.
#

N: NOTES

Additional information to the menu point that is not to be documented in the DESCRIPTION section. If you want to set an empty line, simply enter a N: without text.

Example

#
# N: Special character input is not
# N: allowed (Control-Characters, Umlaut, etc.)
#

F: FILES

List of files. Each text line in this section is printed on a separate line.

Example:

#
# F: /etc/passwd 
# F: /etc/nsswitch.conf
# F: /var/spool/cron/atjobs/<at-job-file>
#

S: SEE ALSO

Reference to other documentation etc. If the first element of the line is a reference in quare brackets (as: [REFER], [1], etc.), it is taken as a reference marker, the following text until the next reference is taken as the reference text.

It is not needed to indent the text as done in the example below for the [AWK] and [CHA] references. The text following a reference can be written as shown for [SSP], the output will be identical for all.

Example:

#
# S: [AWK] The AWK Programming Language, October 1988,
# S:    Aho Alfred V., Weinberger Peter J.,
# S:    Kernighan Brian W., ISBN 0-201-07981-X
# S: [CHA] Clusters, For High Availability,
# S:    2nd Edition 2001, Weygant Peter S.,
# S:    HP-Part No: B3936-90047, ISBN 0-13-089355-2
# S: [SSP] Shellscript Programmierung, Sun Service,
# S: Revision C21 February 1994, Sun Microsystems Inc.,
# S: Sun Part No: 8xx-xxxx-xx
#

T: DURATION

Document the approximate runtime duration of the menu point.

Example:

#
# T: ~7 minutes 
#

If using the scripttitle(3) command, the duration text given here is displayed as expected duration in braces.

SPECIAL BEHAVIOR

-

If you start a line with a dash ( - ) the line containing the dash and following text not preceded by a dash are set with an indent of 2 characters. I.e. an unsorted list is created.

Example:

#
# D: Why go fishing in Canada? 
# D: - vast area of wild nature where
# D: the big fish can be caught. 
# D: - peaceful lakes and streams invite to 
# D: relax and recover from daily hassles. 
#

/-

End an unordered list started with the dash ( - ). This is needed if you like to quit the indented text because the following text does not relate to the list point any more. If the next text you write is assigned to another section, it is not needed to add an /- at the end of the list.

Example:

#
# D: Why go fishing in Canada? 
# D: - vast area of non touched nature where
# D: the big fish can be caught. 
# D: - peaceful lakes and streams invite to 
# D: relax and recover from daily problems. 
# D: /-
# D: Of course there are other places to
# D: experience similar landscape as ...
#

preformatted text

<pre>
text
</pre>

unformatted output of text.

Example:

#
# D: To efficiently rename many menu points, use: 
# D: <pre>
# D: lsmv > a; vi a; sh ./a; rm a; \
# D:    scriptheadersync -execute 
# D: </pre> 
# D: This loads the 'mv' commands into 'vi' and
#

section tag without text

If any section tag without text is set, a line break with a line feed occurs. Therefore in the example below, between the whale and the bear part of the text will be a one line gap in the output.

Example:

#
# D: Beside orcas you can see humpback whales and
# D: if you are lucky you will catch a view of a
# D: gray whale.
# D: 
# D: It might be the case that you are more
# D: interested in bears, those fellows can be
# D: seen near ...  
#

<br>

force a line break without setting a whole empty line.

Example:

#
# D: Hint: 
# D: <br>
# D: The 'Be Bear Aware Campaign' is a national, 
# D: non-profit conservation organization ... 
#

<b>text</b>

set text in bold font.

This formatting cannot be used in sections: F: FILES, O: OUTPUT-EXAMPLE, F: FILES and S: SEE ALSO.

Example:

#
# D: Bears are not mean or malicous - <b>they 
# D: are wild</b> - and all wild animals need 
# D: their space.
#

<i>text</i>

set text underlined on the terminal and in italic font when producing a HTML output.

This formatting cannot be used in sections: F: FILES, O: OUTPUT-EXAMPLE, F: FILES and S: SEE ALSO.

Example:

#
# D: Blackbears, grizzly bears, polar bears,
# D: oh <i>wonderful</i> bears! 
#

<u>text</u>

set text underlined on the terminal and in italic font when producing a HTML output.

Basically the <u>text</u> is identical to the <i>text</i> specification, but to show that the underlining is important to your documenting, this control can be used.

The <u>text</u> can be used to "document" that a text is underlined.

This formatting cannot be used in sections: F: FILES, O: OUTPUT-EXAMPLE, F: FILES and S: SEE ALSO.

Example:

#
# D: To see more information about bears, 
# D: visit the 'Be Bear Aware Campaign': 
# D: 
# D: <u>https://bebearaware.org</u> 
#

USER DEFINED DOCUMENTATION SECTIONS

However, it is possible to define additional sections and documentation tags.

To do so you have to list it using the &: tag in each recovery script or menu title where you need special sections.

A section definition has the format:

# &: specification [{ specification }]

specification::= tag:section

The tag is a lowercase letter (a-z), the section is the section title. Spaces and tabs are not allowed between the tag, the colon ( : ) and the section and within the section text. If spaces in the section title output are needed, they have to be replaced by a % character in the definition.

Example:

#
# &: e:EMERGENCY%CONTACTS w:WORKAROUNDS
#
#

The sections can then be used:

#
# e: +41 12 345 67 89, 7x24 hour operations
#
# w: If you cannot log on to the host dcdbsi20 any more
# w: try to connect via the lan console dcdbsi20cons from
# w: another server in the farm.
#

The new defined sections EMERGENCY CONTACTS and WORKAROUNDS will be listed after the predefined sections. The output is justified.

ENVIRONMENT

EXIT STATUS

FILES

Recovery Script (=menupoint)

The recovery script can contain the documentation tags as explained above.

Menu Title (=menu)

The title files of menus can contain documentation tags as explained above to add documentation to a menu.

Be aware that the first line of a menu title file contains the title of the menu which is displayed when you invoke the menu command in edrc. The following lines can contain the documentation tags.

Create/edit/remove the menu title file using the title command in edrc.

EXAMPLES

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.