/contrib/groff/contrib/groffer/README_SH

  1Additional description for the shell version of `groffer'
  2
  3
  4Scripts
  5
  6The shell version of `groffer' contains two files, `groffer.sh' and
  7`groffer2.sh'.
  8
  9`groffer.sh' is a short introductory script without any functions.  I
 10can be run with a very poor Bourne shell.  It just contains some basic
 11variables, the reading of the configuration files, and the
 12determination of the shell for `groffer2.sh'.  This script is
 13transformed by `make' into `groffer' which will be installed into
 14@bindir@, which is usually /usr/local/bin.
 15
 16`groffer2.sh' is a long main script with all functions; it is called
 17by `groffer.sh' (`groffer' after installation).  It is installed
 18unchanged into @libdir@/groff/groffer, which is usually
 19/usr/local/lib/groff/groffer.  This script can be called with a
 20different shell, using the `groffer' option `--shell'.
 21
 22
 23Options
 24
 25The `groffer' script provides its own option parser.  It is compatible
 26to the usual GNU style command line This includes long option names
 27with two signs such as `--option', clusters of short options, the
 28mixing of options and non-option file names, the option `--' to close
 29the option handling, and it is possible to abbreviate the long option
 30names.
 31
 32The flexible mixing of options and file names in GNU style is always
 33possible, even if the environment variable `$POSIXLY_CORRECT' is set
 34to a non-empty value.  This disables the rather wicked POSIX behavior
 35to terminate option parsing when the first non-option command line
 36argument is found.
 37
 38
 39Error Handling
 40
 41Error handling and exit behavior is complicated by the fact that
 42`exit' can only escape from the current shell; trouble occurs in
 43subshells.  This was solved by sending kill signals, see $_PROCESS_ID
 44and error().
 45
 46
 47Function Definitions in `groffer2.sh'
 48
 49Each funtion in groffer2.sh has a description that starts with the
 50function name and symbols for its arguments in paranthesis `()'.  Each
 51`<>' construction gives an argument name that just gives a hint on
 52what the argument is meant to be; these argument names are otherwise
 53irrelevant.  The `>' sign can be followed by another character that
 54shows 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
 63A function that starts with an underscore `_' is an internal function
 64for some other function.  The internal functions are defined just
 65after their corresponding function.
 66
 67
 68External Environment Variables
 69
 70The groffer.sh script uses the following external system variables.
 71It is supposed that these variables are already exported outside of
 72groffer.sh; otherwise they do not have a value within the script.
 73
 74external 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
 82groffer native environment variables
 83$GROFFER_OPT		preset options for groffer.
 84
 85all 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
 93all 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
101Object-oriented Functions
102
103The groffer script provides an object-oriented construction (OOP).  In
104object-oriented terminology, a type of object is called a `class'; a
105function that handles objects from a class is named `method'.
106
107In the groffer script, the object is a variable name whose content is
108the object's data.  Methods are functions that have an object as first
109argument.
110
111The basic functions for object handling are obj_*().
112
113The class `list' represents an array structure, see list_*().
114
115
116Shell Compatibility
117
118The `groffer' shell scripts are compatible to both the GNU and the
119POSIX shell and utilities.  Care was taken to restrict the programming
120technics used here in order to achieve POSIX compatibility as far back
121as POSIX P1003.2 Draft 11.2 of September 1991.  This draft is
122available at http://www.funet.fi/pub/doc/posix/p1003.2/d11.2 in the
123internet.
124
125The POSIX draft does not include `local' variables for functions.  So
126this concept was replaced by global variables with a prefix that
127differs for each function.  The prefix is chosen from the function
128name.  These quasi-local variables are unset before each return of the
129function.
130
131The `groffer' scripts were tested under the shells `ash', `bash',
132`bash-minimal', `dash', 'ksh', `mksh', `pdksh', 'posh', and `zsh'
133without problems in Linux Debian.  A shell can be tested by the
134`groffer' option `--shell', but that will run only with groffer2.sh.
135To start it directly from the beginning under this shell the following
136command can be used.
137
138  <shell-name> groffer.sh --shell=<shell-name> <argument>...
139
140
141Some shells are not fully POSIX compatible.  For them the following
142restrictions were done.  For more information look at the
143documentation `Portable shells' in the `info' page of `autoconf'
144(look-up in Emacs-Help-Manuals_Info).
145
146- The command parts `then', `else', and `do' must be written each on a
147  line of their own.
148
149- Replace `for i in "$@"' by `for i' and remove internal `;' (kah).
150
151- Replace `set -- ...' by `set x ...; shift'.  After the first
152  non-option argument, all arguments including those starting with `-'
153  are accepted as non-option.  For variables or `$()' constructs with
154  line-breaks, use `eval set' without quotes.  That transforms a
155  line-break within a variable to a space.
156
157- The name of the variable in `for' is chosen as a single character
158  (old ash).  The content of such variables is not safe because it can
159  also occur in other functions.  So it is often stored in an
160  additional quasi-local variable.
161
162- `echo' is not portable on options; some `echo' commands have many
163  options, others have none.  So `echo -n' cannot be used, such that
164  the output of each function has complete lines.  There are two
165  methods to avoid having `-' as the first character of any argument.
166  Either a character such as `x' can be prepended to the argument;
167  this must later on be removed by `sed'.  Otherwise, `echo' can be
168  replaced by `cat <<EOF'.
169
170- `ls' has problems.  Old UNIX systems echoed the error message to
171  standard output.  So handle the output with `sed'.  If the output
172  contains `not found' map it to an empty string.
173
174- As `test -e' is not available in Solaris 2.5 replace it by
175  `test -f || test -d'.
176
177- As `unset' is not supported by all shells replace it by `eval
178  ${_UNSET}' where this variable is `unset' if it exists and `:'
179  otherwise.
180
181- Some shells have problems with options in `eval'.  So quoting must
182  be done right to hide the options from `eval'.
183
184- In backquote calls `` avoid the backquote ` in comments.
185
186- Replace `true' by `:', `false' isn't used.
187
188- Do not redefine builtins as functions (ash).
189
190- Avoid `[^...]' in `case' patterns (ash).
191
192- `trap' does not allow error code 127.
193
194The scripts call the following commands with all options used:
195.
196:
197apropos
198break
199bzip2 -c -d -t
200cat
201catz
202cd
203continue
204echo
205eval
206expr
207grep
208groff -v
209grog -T -X -Z
210gs -c -d -f -q -s
211gzip -c -d -f
212less -r -R
213ls
214man -k --apropos
215mkdir
216mv
217pwd
218return
219rm -f -r
220rmdir
221sed -e -n
222set -e
223sh -c
224shift
225test -c -d -f -r -s -w -x
226trap
227umask
228unset
229
230
231Bugs
232
233If the `groffer' run is interrupted by Crtl-C the clean up is not done
234by all shells.  The `trap' commands work for the shells `bash',
235`bash-minimal', and 'ksh'; they do not work for `ash', `dash',
236`pdksh', `posh', and `zsh'.
237
238
239####### License
240
241Last update: 19 August 2005
242
243Copyright (C) 2003,2004,2005 Free Software Foundation, Inc.
244Written by Bernd Warken
245
246This file is part of `groffer', which is part of `groff'.
247
248`groff' is free software; you can redistribute it and/or modify it
249under the terms of the GNU General Public License as published by
250the Free Software Foundation; either version 2, or (at your option)
251any later version.
252
253`groff' is distributed in the hope that it will be useful, but WITHOUT
254ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
255or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
256License for more details.
257
258You should have received a copy of the GNU General Public License
259along with `groff'; see the files COPYING and LICENSE in the top
260directory of the `groff' source.  If not, write to the Free Software
261Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
262
263
264####### Emacs settings
265
266Local Variables:
267mode: text
268End: