README_SH revision 151498
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: 269