/contrib/groff/contrib/groffer/README_SH

https://bitbucket.org/freebsd/freebsd-head/ · #! · 268 lines · 201 code · 67 blank · 0 comment · 0 complexity · 6081e850935eb2f7c3e1cc2c6c16de65 MD5 · raw file

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