contrib/groffer/README_SH

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