1 Additional description for the shell version of `groffer' 2 3 4 Scripts 5 6 The 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 10 can be run with a very poor Bourne shell. It just contains some basic 11 variables, the reading of the configuration files, and the 12 determination of the shell for `groffer2.sh'. This script is 13 transformed 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 17 by `groffer.sh' (`groffer' after installation). It is installed 18 unchanged into @libdir@/groff/groffer, which is usually 19 /usr/local/lib/groff/groffer. This script can be called with a 20 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 117 118 The `groffer' shell scripts are compatible to both the GNU and the 119 POSIX shell and utilities. Care was taken to restrict the programming 120 technics used here in order to achieve POSIX compatibility as far back 121 as POSIX P1003.2 Draft 11.2 of September 1991. This draft is 122 available at http://www.funet.fi/pub/doc/posix/p1003.2/d11.2 in the 123 internet. 124 125 The POSIX draft does not include `local' variables for functions. So 126 this concept was replaced by global variables with a prefix that 127 differs for each function. The prefix is chosen from the function 128 name. These quasi-local variables are unset before each return of the 129 function. 130 131 The `groffer' scripts were tested under the shells `ash', `bash', 132 `bash-minimal', `dash', 'ksh', `mksh', `pdksh', 'posh', and `zsh' 133 without problems in Linux Debian. A shell can be tested by the 134 `groffer' option `--shell', but that will run only with groffer2.sh. 135 To start it directly from the beginning under this shell the following 136 command can be used. 137 138 <shell-name> groffer.sh --shell=<shell-name> <argument>... 139 140 141 Some shells are not fully POSIX compatible. For them the following 142 restrictions were done. For more information look at the 143 documentation `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 194 The scripts call the following commands with all options used: 195 . 196 : 197 apropos 198 break 199 bzip2 -c -d -t 200 cat 201 catz 202 cd 203 continue 204 echo 205 eval 206 expr 207 grep 208 groff -v 209 grog -T -X -Z 210 gs -c -d -f -q -s 211 gzip -c -d -f 212 less -r -R 213 ls 214 man -k --apropos 215 mkdir 216 mv 217 pwd 218 return 219 rm -f -r 220 rmdir 221 sed -e -n 222 set -e 223 sh -c 224 shift 225 test -c -d -f -r -s -w -x 226 trap 227 umask 228 unset 229 230 231 Bugs 232 233 If the `groffer' run is interrupted by Crtl-C the clean up is not done 234 by 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 241 Last update: 19 August 2005 242 243 Copyright (C) 2003,2004,2005 Free Software Foundation, Inc. 244 Written by Bernd Warken 245 246 This file is part of `groffer', which is part of `groff'. 247 248 `groff' is free software; you can redistribute it and/or modify it 249 under the terms of the GNU General Public License as published by 250 the Free Software Foundation; either version 2, or (at your option) 251 any later version. 252 253 `groff' is distributed in the hope that it will be useful, but WITHOUT 254 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 255 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public 256 License for more details. 257 258 You should have received a copy of the GNU General Public License 259 along with `groff'; see the files COPYING and LICENSE in the top 260 directory of the `groff' source. If not, write to the Free Software 261 Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA. 262 263 264 ####### Emacs settings 265 266 Local Variables: 267 mode: text 268 End: 269
Indexes created Thu Oct 01 00:25:45 UTC 2026