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 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: