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