contrib/groffer/README_SH

   1 Description of groffer.sh, the shell version of groffer
   2
   3 Display groff files and man pages on X or tty, even when compressed.
   4
   5
   6 Usage
   7
   8 Input comes from either standard input or command line parameters that
   9 represent names of exisiting roff files or standardized specifications
  10 for searching man pages.  All of these can be compressed in a format
  11 that is decompressible by `gzip', including `.gz', `bz2', and `.Z'.
  12
  13 The following displaying modes are available:
  14 - Display formatted input with the X roff viewer `gxditview',
  15 - with a Prostcript viewer,
  16 - with a dvi viewer,
  17 - with a web browser.
  18 - Display formatted input in plain text mode.
  19 - Run a pager on the formatted input in a text terminal (tty).
  20 - Generate output for some groff device on stdout without a viewer.
  21 - Output only the source code without any groff processing.
  22 - Generate the troff intermediate output on standard output
  23   without groff postprocessing.
  24 By default, the program tries to display with `gxditview' as graphical
  25 device, `tty' mode with a pager is tried as text display.
  26
  27
  28 Several File Arguments
  29
  30 So far, `groffer' bundles all filespec parameters into a single output
  31 file in the same way as `groff'.  The disadvantage of this is that all
  32 file name arguments must have the same groff language.
  33
  34 To change this, the option parsing must be revised for large parts.
  35 It seems that this would create incompatibilities, so the actual
  36 option strategy is kept.
  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 Shell Compatibility
  48
  49 This shell script is compatible to the both the GNU and the POSIX
  50 shell and utilities.  Care was taken to restrict the programming
  51 technics used here in order to achieve POSIX compatibility as far
  52 back as POSIX P1003.2 Draft 11.2 of September 1991.
  53
  54 The only non-builtin used here is POSIX `sed'.  This script was
  55 tested under `bash', `ash', and `ksh'.  The speed under `ash' is
  56 more than double when compared to the larger shells.
  57
  58 This script provides its own option parser.  It is compatible to the
  59 usual GNU style command line (option clusters, long options, mixing
  60 of options and non-option file names), except that it is not
  61 possible to abbreviate long option names.
  62
  63 The mixing of options and file names can be prohibited by setting
  64 the environment variable `$POSIXLY_CORRECT' to a non-empty value.
  65 This enables the rather wicked POSIX behavior to terminate option
  66 parsing when the first non-option command line argument is found.
  67
  68
  69 Survey of Functions defined in groffer.sh
  70
  71 The elements specified within paranthesis `(<>)' give hints to what
  72 the arguments are meant to be; the argument names are irrelevant.
  73 <>?     0 or 1
  74 <>*     arbitrarily many such arguments, incl. none
  75 <>+     one or more such arguments
  76 <>      exactly 1
  77
  78 A function that starts with an underscore `_' is an internal
  79 function for some function.  The internal functions are defined just
  80 after their corresponding function; they are not mentioned in the
  81 following.
  82
  83 abort (text>*)
  84 base_name (path)
  85 catz (<file>)
  86 clean_up ()
  87 diag (text>*)
  88 dirname_append (<path> [<dir...>])
  89 dirname_chop (<path>)
  90 do_filearg (<filearg>)
  91 do_nothing ()
  92 echo2 (<text>*)
  93 echo2n (<text>*)
  94 error (<text>*)
  95 get_first_essential (<arg>*)
  96 is_dir (<name>)
  97 is_empty (<string>)
  98 is_equal (<string1> <string2>)
  99 is_file (<name>)
 100 is_non_empty_file (<name>)
 101 is_not_dir (<name>)
 102 is_not_empty (<string>)
 103 is_not_equal (<string1> <string2>)
 104 is_not_file (<name>)
 105 is_not_prog (<name>)
 106 is_not_writable (<name>)
 107 is_not_yes (<string>)
 108 is_prog (<name>)
 109 is_yes (<string>)
 110 leave ()
 111 landmark (<text>)
 112 list_append (<list> <element>...)
 113 list_from_cmdline (<s_n> <s_a> <l_n> <l_n> [<cmdline_arg>...])
 114 list_from_split (<string> <separator>)
 115 list_get (<list>)
 116 list_has (<list> <element>)
 117 list_has_not (<list> <element>)
 118 main_*(), see after the functions
 119 man_do_filespec (<filespec>)
 120 man_setup ()
 121 man_register_file (<file> [<name> [<section>]])
 122 man_search_section (<name> <section>)
 123 man_set()
 124 manpath_add_lang(<path> <language>)
 125 manpath_add_system()
 126 manpath_from_path ()
 127 normalize_args (<shortopts> <longopts> <arg>*)
 128 path_chop (<path>)
 129 path_clean (<path>)
 130 path_contains (<path> <dir>)
 131 path_not_contains (<path> <dir>)
 132 path_split (<path>)
 133 register_file (<filename>)
 134 register_title (<filespec>)
 135 res (<var_name> <function_name> <arg>...)
 136 reset ()
 137 save_stdin ()
 138 string_contains (<string> <part>)
 139 string_not_contains (<string> <part>)
 140 tmp_cat ()
 141 tmp_create (<suffix>?)
 142 to_tmp (<filename>)
 143 trap_clean ()
 144 trap_set (<functionname>)
 145 usage ()
 146 version ()
 147 warning (<string>)
 148 whatis (<filename>)
 149 where (<program>)
 150
 151
 152 External non-groffer Environment Variables
 153
 154 If these variables are exported in the script the `ash' shell coughs
 155 when calling `groff' in `main_display()'.
 156
 157 external system environment variables that are explicitly used
 158 $DISPLAY:               Presets the X display.
 159 $LANG:                  For language specific man pages.
 160 $LC_ALL:                For language specific man pages.
 161 $LC_MESSAGES:           For language specific man pages.
 162 $PAGER:                 Paging program for tty mode.
 163 $PATH:                  Path for the programs called (: list).
 164
 165 groffer native environment variables
 166 $GROFFER_OPT            preset options for groffer.
 167
 168 all groff environment variables are used, see groff(1)
 169 $GROFF_BIN_PATH:        Path for all groff programs.
 170 $GROFF_COMMAND_PREFIX:  '' (normally) or 'g' (several troffs).
 171 $GROFF_FONT_PATH:       Path to non-default groff fonts.
 172 $GROFF_TMAC_PATH:       Path to non-default groff macro files.
 173 $GROFF_TMPDIR:          Directory for groff temporary files.
 174 $GROFF_TYPESETTER:      Preset default device.
 175
 176 all GNU man environment variables are used, see man(1).
 177 $MANOPT:                Preset options for man pages.
 178 $MANPATH:               Search path for man pages (: list).
 179 $MANROFFSEQ:            Ignored because of grog guessing.
 180 $MANSECT:               Search man pages only in sections (:).
 181 $SYSTEM:                Man pages for different OS's (, list).
 182
 183
 184 Object-oriented Functions
 185
 186 The groffer script provides an object-oriented construction (OOP).  In
 187 object-oriented terminology, a type of object is called a `class'; a
 188 function that handles objects from a class is named `method'.
 189
 190 In the groffer script, the object is a variable name whose content is
 191 the object's data.  Methods are functions that have an object as first
 192 argument.
 193
 194 The basic functions for object handling are obj_*().
 195
 196 The class `list' represents an array structure, see list_*().
 197
 198
 199 ####### License
 200
 201 Copyright (C) 2003,2004 Free Software Foundation, Inc.
 202 Written by Bernd Warken
 203
 204 This file is part of groffer, which is part of groff.
 205
 206 groff is free software; you can redistribute it and/or modify it
 207 under the terms of the GNU General Public License as published by
 208 the Free Software Foundation; either version 2, or (at your option)
 209 any later version.
 210
 211 groff is distributed in the hope that it will be useful, but WITHOUT
 212 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 213 or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
 214 License for more details.
 215
 216 You should have received a copy of the GNU General Public License
 217 along with groff; see the files COPYING and LICENSE in the top
 218 directory of the groff source.  If not, write to the Free Software
 219 Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.