1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
Additional description for groffer.sh, the shell version of groffer
Shell Compatibility
This shell script is compatible to both the GNU and the POSIX shell
and utilities. Care was taken to restrict the programming technics
used here in order to achieve POSIX compatibility as far back as POSIX
P1003.2 Draft 11.2 of September 1991, but including the local
variables in functions that were eliminated only in this draft. This
draft is available at http://www.funet.fi/pub/doc/posix/p1003.2/d11.2
in the internet. So `groffer' should be compatible to most actual
Bourne style shells.
The `groffer' script provides its own option parser. It is compatible
to the usual GNU style command line (option clusters, long option
names with 2 `-' signs, mixing of options and non-option file names),
except that it is not possible to abbreviate 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().
Survey of Functions defined in groffer.sh
The elements specified within paranthesis `(<>)' give hints to what
the arguments are meant to be; the argument names are irrelevant.
<>? 0 or 1
<>* arbitrarily many such arguments, incl. none
<>+ one or more such arguments
<> exactly 1
A function that starts with an underscore `_' is an internal function
for some function. The internal functions are defined just after
their corresponding function; they are not mentioned in the following.
abort (<text>*)
base_name (<path>)
catz (<file>)
clean_up ()
diag (<text>*)
dirname_append (<path> [<dir...>])
dirname_chop (<path>)
do_filearg (<filearg>)
do_nothing ()
echo2 (<text>*)
echo2n (<text>*)
error (<text>*)
get_first_essential (<arg>*)
is_dir (<name>)
is_empty (<string>)
is_equal (<string1> <string2>)
is_existing (<name>)
is_file (<name>)
is_non_empty_file (<name>)
is_not_dir (<name>)
is_not_empty (<string>)
is_not_equal (<string1> <string2>)
is_not_file (<name>)
is_not_prog (<name>)
is_not_writable (<name>)
is_not_yes (<string>)
is_prog (<name>)
is_writable (<name>)
is_yes (<string>)
leave ()
landmark (<text>)
list_append (<list> <element>...)
list_from_cmdline (<pre_name_of_opt_lists> [<cmdline_arg>...])
list_from_split (<string> <separator>)
list_get (<list>)
list_has (<list> <element>)
list_has_not (<list> <element>)
main_*(), see after the functions
man_do_filespec (<filespec>)
man_setup ()
man_register_file (<file> [<name> [<section>]])
man_search_section (<name> <section>)
man_set()
manpath_add_lang(<path> <language>)
manpath_add_system()
manpath_from_path ()
normalize_args (<shortopts> <longopts> <arg>*)
obj (<object> <call_name> <arg>...)
obj_data (<object>)
obj_from_output (<object> <call_name> <arg>...)
obj_set (<object> <data>)
path_chop (<path>)
path_clean (<path>)
path_contains (<path> <dir>)
path_not_contains (<path> <dir>)
path_split (<path>)
register_file (<filename>)
register_title (<filespec>)
res (<var_name> <function_name> <arg>...)
reset ()
save_stdin ()
string_contains (<string> <part>)
string_not_contains (<string> <part>)
tmp_cat ()
tmp_create (<suffix>?)
to_tmp (<filename>)
trap_clean ()
trap_set (<functionname>)
usage ()
version ()
warning (<string>)
whatis (<filename>)
where (<program>)
External non-groffer Environment Variables
If these variables are exported in the script the `ash' shell coughs
when calling `groff' in `main_display()'.
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 (: 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_*().
####### License
Copyright (C) 2003,2004,2005 Free Software Foundation, Inc.
Written by Bernd Warken
This file is part of groffer, which is part of groff.
groff is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
groff is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
License for more details.
You should have received a copy of the GNU General Public License
along with groff; see the files COPYING and LICENSE in the top
directory of the groff source. If not, write to the Free Software
Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
|
