20 |
different shell, using the `groffer' option `--shell'. |
different shell, using the `groffer' option `--shell'. |
21 |
|
|
22 |
|
|
23 |
|
Options |
24 |
|
|
25 |
|
The `groffer' script provides its own option parser. It is compatible |
26 |
|
to the usual GNU style command line This includes long option names |
27 |
|
with two signs such as `--option', clusters of short options, the |
28 |
|
mixing of options and non-option file names, the option `--' to close |
29 |
|
the option handling, and it is possible to abbreviate the long option |
30 |
|
names. |
31 |
|
|
32 |
|
The flexible mixing of options and file names in GNU style is always |
33 |
|
possible, even if the environment variable `$POSIXLY_CORRECT' is set |
34 |
|
to a non-empty value. This disables the rather wicked POSIX behavior |
35 |
|
to terminate option parsing when the first non-option command line |
36 |
|
argument is found. |
37 |
|
|
38 |
|
|
39 |
|
Error Handling |
40 |
|
|
41 |
|
Error handling and exit behavior is complicated by the fact that |
42 |
|
`exit' can only escape from the current shell; trouble occurs in |
43 |
|
subshells. This was solved by sending kill signals, see $_PROCESS_ID |
44 |
|
and error(). |
45 |
|
|
46 |
|
|
47 |
|
Function Definitions in `groffer2.sh' |
48 |
|
|
49 |
|
Each funtion in groffer2.sh has a description that starts with the |
50 |
|
function name and symbols for its arguments in paranthesis `()'. Each |
51 |
|
`<>' construction gives an argument name that just gives a hint on |
52 |
|
what the argument is meant to be; these argument names are otherwise |
53 |
|
irrelevant. The `>' sign can be followed by another character that |
54 |
|
shows how many of these arguments are possible. |
55 |
|
|
56 |
|
<arg> exactly 1 of this argument |
57 |
|
<arg>? 0 or 1 of these arguments |
58 |
|
<arg>* arbitrarily many such arguments, incl. none |
59 |
|
<arg>+ one or more such arguments |
60 |
|
<arg>... one or more such arguments |
61 |
|
[...] optional arguments |
62 |
|
|
63 |
|
A function that starts with an underscore `_' is an internal function |
64 |
|
for some other function. The internal functions are defined just |
65 |
|
after their corresponding function. |
66 |
|
|
67 |
|
|
68 |
|
External Environment Variables |
69 |
|
|
70 |
|
The groffer.sh script uses the following external system variables. |
71 |
|
It is supposed that these variables are already exported outside of |
72 |
|
groffer.sh; otherwise they do not have a value within the script. |
73 |
|
|
74 |
|
external system environment variables that are explicitly used |
75 |
|
$DISPLAY: Presets the X display. |
76 |
|
$LANG: For language specific man pages. |
77 |
|
$LC_ALL: For language specific man pages. |
78 |
|
$LC_MESSAGES: For language specific man pages. |
79 |
|
$PAGER: Paging program for tty mode. |
80 |
|
$PATH: Path for the programs called (`:' separated list). |
81 |
|
|
82 |
|
groffer native environment variables |
83 |
|
$GROFFER_OPT preset options for groffer. |
84 |
|
|
85 |
|
all groff environment variables are used, see groff(1) |
86 |
|
$GROFF_BIN_PATH: Path for all groff programs. |
87 |
|
$GROFF_COMMAND_PREFIX: '' (normally) or 'g' (several troffs). |
88 |
|
$GROFF_FONT_PATH: Path to non-default groff fonts. |
89 |
|
$GROFF_TMAC_PATH: Path to non-default groff macro files. |
90 |
|
$GROFF_TMPDIR: Directory for groff temporary files. |
91 |
|
$GROFF_TYPESETTER: Preset default device. |
92 |
|
|
93 |
|
all GNU man environment variables are used, see man(1). |
94 |
|
$MANOPT: Preset options for man pages. |
95 |
|
$MANPATH: Search path for man pages (: list). |
96 |
|
$MANROFFSEQ: Ignored because of grog guessing. |
97 |
|
$MANSECT: Search man pages only in sections (:). |
98 |
|
$SYSTEM: Man pages for different OS's (, list). |
99 |
|
|
100 |
|
|
101 |
|
Object-oriented Functions |
102 |
|
|
103 |
|
The groffer script provides an object-oriented construction (OOP). In |
104 |
|
object-oriented terminology, a type of object is called a `class'; a |
105 |
|
function that handles objects from a class is named `method'. |
106 |
|
|
107 |
|
In the groffer script, the object is a variable name whose content is |
108 |
|
the object's data. Methods are functions that have an object as first |
109 |
|
argument. |
110 |
|
|
111 |
|
The basic functions for object handling are obj_*(). |
112 |
|
|
113 |
|
The class `list' represents an array structure, see list_*(). |
114 |
|
|
115 |
|
|
116 |
Shell Compatibility |
Shell Compatibility |
117 |
|
|
118 |
The `groffer' shell scripts are compatible to both the GNU and the |
The `groffer' shell scripts are compatible to both the GNU and the |
129 |
function. |
function. |
130 |
|
|
131 |
The `groffer' scripts were tested under the shells `ash', `bash', |
The `groffer' scripts were tested under the shells `ash', `bash', |
132 |
`dash', 'ksh', `mksh', `pdksh', 'posh', and `zsh' without problems in |
`bash-minimal', `dash', 'ksh', `mksh', `pdksh', 'posh', and `zsh' |
133 |
Linux Debian. A shell can be tested by the `groffer' option |
without problems in Linux Debian. A shell can be tested by the |
134 |
`--shell', but that will run only with groffer2.sh. To start it |
`groffer' option `--shell', but that will run only with groffer2.sh. |
135 |
directly from the beginning under this shell the following command can |
To start it directly from the beginning under this shell the following |
136 |
be used. |
command can be used. |
137 |
|
|
138 |
<shell-name> groffer.sh --shell=<shell-name> <argument>... |
<shell-name> groffer.sh --shell=<shell-name> <argument>... |
139 |
|
|
228 |
unset |
unset |
229 |
|
|
230 |
|
|
231 |
Options |
Bugs |
|
|
|
|
The `groffer' script provides its own option parser. It is compatible |
|
|
to the usual GNU style command line This includes long option names |
|
|
with two signs such as `--option', clusters of short options, the |
|
|
mixing of options and non-option file names, the option `--' to close |
|
|
the option handling, and it is possible to abbreviate the long option |
|
|
names. |
|
|
|
|
|
The flexible mixing of options and file names in GNU style is always |
|
|
possible, even if the environment variable `$POSIXLY_CORRECT' is set |
|
|
to a non-empty value. This disables the rather wicked POSIX behavior |
|
|
to terminate option parsing when the first non-option command line |
|
|
argument is found. |
|
|
|
|
|
|
|
|
Error Handling |
|
|
|
|
|
Error handling and exit behavior is complicated by the fact that |
|
|
`exit' can only escape from the current shell; trouble occurs in |
|
|
subshells. This was solved by sending kill signals, see $_PROCESS_ID |
|
|
and error(). |
|
|
|
|
|
|
|
|
Function Definitions in `groffer2.sh' |
|
|
|
|
|
Each funtion in groffer2.sh has a description that starts with the |
|
|
function name and symbols for its arguments in paranthesis `()'. Each |
|
|
`<>' construction gives an argument name that just gives a hint on |
|
|
what the argument is meant to be; these argument names are otherwise |
|
|
irrelevant. The `>' sign can be followed by another character that |
|
|
shows how many of these arguments are possible. |
|
232 |
|
|
233 |
<arg> exactly 1 of this argument |
If the `groffer' run is interrupted by Crtl-C the clean up is not done |
234 |
<arg>? 0 or 1 of these arguments |
by all shells. The `trap' commands work for the shells `bash', |
235 |
<arg>* arbitrarily many such arguments, incl. none |
`bash-minimal', and 'ksh'; they do not work for `ash', `dash', |
236 |
<arg>+ one or more such arguments |
`pdksh', `posh', and `zsh'. |
|
<arg>... one or more such arguments |
|
|
[...] optional arguments |
|
|
|
|
|
A function that starts with an underscore `_' is an internal function |
|
|
for some other function. The internal functions are defined just |
|
|
after their corresponding function. |
|
|
|
|
|
|
|
|
External Environment Variables |
|
|
|
|
|
The groffer.sh script uses the following external system variables. |
|
|
It is supposed that these variables are already exported outside of |
|
|
groffer.sh; otherwise they do not have a value within the script. |
|
|
|
|
|
external system environment variables that are explicitly used |
|
|
$DISPLAY: Presets the X display. |
|
|
$LANG: For language specific man pages. |
|
|
$LC_ALL: For language specific man pages. |
|
|
$LC_MESSAGES: For language specific man pages. |
|
|
$PAGER: Paging program for tty mode. |
|
|
$PATH: Path for the programs called (`:' separated list). |
|
|
|
|
|
groffer native environment variables |
|
|
$GROFFER_OPT preset options for groffer. |
|
|
|
|
|
all groff environment variables are used, see groff(1) |
|
|
$GROFF_BIN_PATH: Path for all groff programs. |
|
|
$GROFF_COMMAND_PREFIX: '' (normally) or 'g' (several troffs). |
|
|
$GROFF_FONT_PATH: Path to non-default groff fonts. |
|
|
$GROFF_TMAC_PATH: Path to non-default groff macro files. |
|
|
$GROFF_TMPDIR: Directory for groff temporary files. |
|
|
$GROFF_TYPESETTER: Preset default device. |
|
|
|
|
|
all GNU man environment variables are used, see man(1). |
|
|
$MANOPT: Preset options for man pages. |
|
|
$MANPATH: Search path for man pages (: list). |
|
|
$MANROFFSEQ: Ignored because of grog guessing. |
|
|
$MANSECT: Search man pages only in sections (:). |
|
|
$SYSTEM: Man pages for different OS's (, list). |
|
|
|
|
|
|
|
|
Object-oriented Functions |
|
|
|
|
|
The groffer script provides an object-oriented construction (OOP). In |
|
|
object-oriented terminology, a type of object is called a `class'; a |
|
|
function that handles objects from a class is named `method'. |
|
|
|
|
|
In the groffer script, the object is a variable name whose content is |
|
|
the object's data. Methods are functions that have an object as first |
|
|
argument. |
|
|
|
|
|
The basic functions for object handling are obj_*(). |
|
|
|
|
|
The class `list' represents an array structure, see list_*(). |
|
237 |
|
|
238 |
|
|
239 |
####### License |
####### License |
240 |
|
|
241 |
Last update: 2 August 2005 |
Last update: 19 August 2005 |
242 |
|
|
243 |
Copyright (C) 2003,2004,2005 Free Software Foundation, Inc. |
Copyright (C) 2003,2004,2005 Free Software Foundation, Inc. |
244 |
Written by Bernd Warken |
Written by Bernd Warken |