/[groff]/groff/contrib/groffer/README_SH
ViewVC logotype

Diff of /groff/contrib/groffer/README_SH

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.11 by wl, Wed Aug 3 06:32:11 2005 UTC revision 1.12 by wl, Tue Aug 23 09:57:09 2005 UTC
# Line 20  unchanged into @libdir@/groff/groffer, w Line 20  unchanged into @libdir@/groff/groffer, w
20  different shell, using the `groffer' option `--shell'.  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  Shell Compatibility
117    
118  The `groffer' shell scripts are compatible to both the GNU and the  The `groffer' shell scripts are compatible to both the GNU and the
# Line 36  name.  These quasi-local variables are u Line 129  name.  These quasi-local variables are u
129  function.  function.
130    
131  The `groffer' scripts were tested under the shells `ash', `bash',  The `groffer' scripts were tested under the shells `ash', `bash',
132  `dash', 'ksh', `mksh', `pdksh', 'posh', and `zsh' without problems in  `bash-minimal', `dash', 'ksh', `mksh', `pdksh', 'posh', and `zsh'
133  Linux Debian.  A shell can be tested by the `groffer' option  without problems in Linux Debian.  A shell can be tested by the
134  `--shell', but that will run only with groffer2.sh.  To start it  `groffer' option `--shell', but that will run only with groffer2.sh.
135  directly from the beginning under this shell the following command can  To start it directly from the beginning under this shell the following
136  be used.  command can be used.
137    
138    <shell-name> groffer.sh --shell=<shell-name> <argument>...    <shell-name> groffer.sh --shell=<shell-name> <argument>...
139    
# Line 135  umask Line 228  umask
228  unset  unset
229    
230    
231  Options  Bugs
   
 The `groffer' script provides its own option parser.  It is compatible  
 to the usual GNU style command line This includes long option names  
 with two signs such as `--option', clusters of short options, the  
 mixing of options and non-option file names, the option `--' to close  
 the option handling, and it is possible to abbreviate the long option  
 names.  
   
 The flexible mixing of options and file names in GNU style is always  
 possible, even if the environment variable `$POSIXLY_CORRECT' is set  
 to a non-empty value.  This disables the rather wicked POSIX behavior  
 to terminate option parsing when the first non-option command line  
 argument is found.  
   
   
 Error Handling  
   
 Error handling and exit behavior is complicated by the fact that  
 `exit' can only escape from the current shell; trouble occurs in  
 subshells.  This was solved by sending kill signals, see $_PROCESS_ID  
 and error().  
   
   
 Function Definitions in `groffer2.sh'  
   
 Each funtion in groffer2.sh has a description that starts with the  
 function name and symbols for its arguments in paranthesis `()'.  Each  
 `<>' construction gives an argument name that just gives a hint on  
 what the argument is meant to be; these argument names are otherwise  
 irrelevant.  The `>' sign can be followed by another character that  
 shows how many of these arguments are possible.  
232    
233  <arg>      exactly 1 of this argument  If the `groffer' run is interrupted by Crtl-C the clean up is not done
234  <arg>?     0 or 1 of these arguments  by all shells.  The `trap' commands work for the shells `bash',
235  <arg>*     arbitrarily many such arguments, incl. none  `bash-minimal', and 'ksh'; they do not work for `ash', `dash',
236  <arg>+     one or more such arguments  `pdksh', `posh', and `zsh'.
 <arg>...   one or more such arguments  
 [...]      optional arguments  
   
 A function that starts with an underscore `_' is an internal function  
 for some other function.  The internal functions are defined just  
 after their corresponding function.  
   
   
 External Environment Variables  
   
 The groffer.sh script uses the following external system variables.  
 It is supposed that these variables are already exported outside of  
 groffer.sh; otherwise they do not have a value within the script.  
   
 external system environment variables that are explicitly used  
 $DISPLAY:               Presets the X display.  
 $LANG:                  For language specific man pages.  
 $LC_ALL:                For language specific man pages.  
 $LC_MESSAGES:           For language specific man pages.  
 $PAGER:                 Paging program for tty mode.  
 $PATH:                  Path for the programs called (`:' separated list).  
   
 groffer native environment variables  
 $GROFFER_OPT            preset options for groffer.  
   
 all groff environment variables are used, see groff(1)  
 $GROFF_BIN_PATH:        Path for all groff programs.  
 $GROFF_COMMAND_PREFIX:  '' (normally) or 'g' (several troffs).  
 $GROFF_FONT_PATH:       Path to non-default groff fonts.  
 $GROFF_TMAC_PATH:       Path to non-default groff macro files.  
 $GROFF_TMPDIR:          Directory for groff temporary files.  
 $GROFF_TYPESETTER:      Preset default device.  
   
 all GNU man environment variables are used, see man(1).  
 $MANOPT:                Preset options for man pages.  
 $MANPATH:               Search path for man pages (: list).  
 $MANROFFSEQ:            Ignored because of grog guessing.  
 $MANSECT:               Search man pages only in sections (:).  
 $SYSTEM:                Man pages for different OS's (, list).  
   
   
 Object-oriented Functions  
   
 The groffer script provides an object-oriented construction (OOP).  In  
 object-oriented terminology, a type of object is called a `class'; a  
 function that handles objects from a class is named `method'.  
   
 In the groffer script, the object is a variable name whose content is  
 the object's data.  Methods are functions that have an object as first  
 argument.  
   
 The basic functions for object handling are obj_*().  
   
 The class `list' represents an array structure, see list_*().  
237    
238    
239  ####### License  ####### License
240    
241  Last update: 2 August 2005  Last update: 19 August 2005
242    
243  Copyright (C) 2003,2004,2005 Free Software Foundation, Inc.  Copyright (C) 2003,2004,2005 Free Software Foundation, Inc.
244  Written by Bernd Warken  Written by Bernd Warken

Legend:
Removed from v.1.11  
changed lines
  Added in v.1.12

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26