269 lines
8.9 KiB
Plaintext
269 lines
8.9 KiB
Plaintext
Additional description for the shell version of `groffer'
|
|
|
|
|
|
Scripts
|
|
|
|
The shell version of `groffer' contains two files, `groffer.sh' and
|
|
`groffer2.sh'.
|
|
|
|
`groffer.sh' is a short introductory script without any functions. I
|
|
can be run with a very poor Bourne shell. It just contains some basic
|
|
variables, the reading of the configuration files, and the
|
|
determination of the shell for `groffer2.sh'. This script is
|
|
transformed by `make' into `groffer' which will be installed into
|
|
@bindir@, which is usually /usr/local/bin.
|
|
|
|
`groffer2.sh' is a long main script with all functions; it is called
|
|
by `groffer.sh' (`groffer' after installation). It is installed
|
|
unchanged into @libdir@/groff/groffer, which is usually
|
|
/usr/local/lib/groff/groffer. This script can be called with a
|
|
different shell, using the `groffer' option `--shell'.
|
|
|
|
|
|
Options
|
|
|
|
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.
|
|
|
|
<arg> exactly 1 of this argument
|
|
<arg>? 0 or 1 of these arguments
|
|
<arg>* arbitrarily many such arguments, incl. none
|
|
<arg>+ one or more such arguments
|
|
<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_*().
|
|
|
|
|
|
Shell Compatibility
|
|
|
|
The `groffer' shell scripts are 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. This draft is
|
|
available at http://www.funet.fi/pub/doc/posix/p1003.2/d11.2 in the
|
|
internet.
|
|
|
|
The POSIX draft does not include `local' variables for functions. So
|
|
this concept was replaced by global variables with a prefix that
|
|
differs for each function. The prefix is chosen from the function
|
|
name. These quasi-local variables are unset before each return of the
|
|
function.
|
|
|
|
The `groffer' scripts were tested under the shells `ash', `bash',
|
|
`bash-minimal', `dash', 'ksh', `mksh', `pdksh', 'posh', and `zsh'
|
|
without problems in Linux Debian. A shell can be tested by the
|
|
`groffer' option `--shell', but that will run only with groffer2.sh.
|
|
To start it directly from the beginning under this shell the following
|
|
command can be used.
|
|
|
|
<shell-name> groffer.sh --shell=<shell-name> <argument>...
|
|
|
|
|
|
Some shells are not fully POSIX compatible. For them the following
|
|
restrictions were done. For more information look at the
|
|
documentation `Portable shells' in the `info' page of `autoconf'
|
|
(look-up in Emacs-Help-Manuals_Info).
|
|
|
|
- The command parts `then', `else', and `do' must be written each on a
|
|
line of their own.
|
|
|
|
- Replace `for i in "$@"' by `for i' and remove internal `;' (kah).
|
|
|
|
- Replace `set -- ...' by `set x ...; shift'. After the first
|
|
non-option argument, all arguments including those starting with `-'
|
|
are accepted as non-option. For variables or `$()' constructs with
|
|
line-breaks, use `eval set' without quotes. That transforms a
|
|
line-break within a variable to a space.
|
|
|
|
- The name of the variable in `for' is chosen as a single character
|
|
(old ash). The content of such variables is not safe because it can
|
|
also occur in other functions. So it is often stored in an
|
|
additional quasi-local variable.
|
|
|
|
- `echo' is not portable on options; some `echo' commands have many
|
|
options, others have none. So `echo -n' cannot be used, such that
|
|
the output of each function has complete lines. There are two
|
|
methods to avoid having `-' as the first character of any argument.
|
|
Either a character such as `x' can be prepended to the argument;
|
|
this must later on be removed by `sed'. Otherwise, `echo' can be
|
|
replaced by `cat <<EOF'.
|
|
|
|
- `ls' has problems. Old UNIX systems echoed the error message to
|
|
standard output. So handle the output with `sed'. If the output
|
|
contains `not found' map it to an empty string.
|
|
|
|
- As `test -e' is not available in Solaris 2.5 replace it by
|
|
`test -f || test -d'.
|
|
|
|
- As `unset' is not supported by all shells replace it by `eval
|
|
${_UNSET}' where this variable is `unset' if it exists and `:'
|
|
otherwise.
|
|
|
|
- Some shells have problems with options in `eval'. So quoting must
|
|
be done right to hide the options from `eval'.
|
|
|
|
- In backquote calls `` avoid the backquote ` in comments.
|
|
|
|
- Replace `true' by `:', `false' isn't used.
|
|
|
|
- Do not redefine builtins as functions (ash).
|
|
|
|
- Avoid `[^...]' in `case' patterns (ash).
|
|
|
|
- `trap' does not allow error code 127.
|
|
|
|
The scripts call the following commands with all options used:
|
|
.
|
|
:
|
|
apropos
|
|
break
|
|
bzip2 -c -d -t
|
|
cat
|
|
catz
|
|
cd
|
|
continue
|
|
echo
|
|
eval
|
|
expr
|
|
grep
|
|
groff -v
|
|
grog -T -X -Z
|
|
gs -c -d -f -q -s
|
|
gzip -c -d -f
|
|
less -r -R
|
|
ls
|
|
man -k --apropos
|
|
mkdir
|
|
mv
|
|
pwd
|
|
return
|
|
rm -f -r
|
|
rmdir
|
|
sed -e -n
|
|
set -e
|
|
sh -c
|
|
shift
|
|
test -c -d -f -r -s -w -x
|
|
trap
|
|
umask
|
|
unset
|
|
|
|
|
|
Bugs
|
|
|
|
If the `groffer' run is interrupted by Crtl-C the clean up is not done
|
|
by all shells. The `trap' commands work for the shells `bash',
|
|
`bash-minimal', and 'ksh'; they do not work for `ash', `dash',
|
|
`pdksh', `posh', and `zsh'.
|
|
|
|
|
|
####### License
|
|
|
|
Last update: 19 August 2005
|
|
|
|
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, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
|
|
|
|
|
|
####### Emacs settings
|
|
|
|
Local Variables:
|
|
mode: text
|
|
End:
|