diplodocus.org Git - nmh/blob - docs/historical/mh-jun-1982/man/mhl.1

   1 .TH MHL 1 RAND(DRAFT)
   2 .SH NAME
   3 mhl \- Produce formatted listings of MH messages
   4 .SH SYNOPSIS
   5 \fBmhl
   6 [
   7 \fB\-clear\fR]
   8 [\fB\-noclear\fR]
   9 [\fB\-folder\fR\ folder]
  10 [\fB\-form\fR\ formfile]
  11 [\fB\-length\fR\ length]
  12 [\fB\-width\fR\ width]
  13 [\fB\-help\fR]
  14 [file ...]
  15 .SH DESCRIPTION
  16 .I Mhl
  17 is a formatted message listing program. It can be used as a
  18 replacement for "c" (the default message lister). As with c, each of
  19 the messages specified as arguments (or stdin) will be output.  If more
  20 than one message file is specified, the user will be prompted prior to
  21 each one, and a <return> or <eot> will begin the output, with <return>
  22 clearing the screen (if appropriate), and <eot> suppressing the screen
  23 clear.  An <interrupt> will abort the current message ouput, prompting
  24 for the next message (if there is one), and a <quit> will terminate the
  25 program (without core dump).
  26 .PP
  27 As in all MH programs, mhl looks for a line "mhl: args" in the user's
  28 profile, and thus allows tailored defaults.  The switches are:
  29 .PP
  30 .ta 1.5i
  31 .br
  32 \-clear Clear screen each page
  33 .br
  34 \-noclear       Don't clear screen each page
  35 .br
  36 \-folder folder Use this "folder" name
  37 .br
  38 \-form formfile Name of the format file
  39 .br
  40 \-length length Screen length
  41 .br
  42 \-width width   Screen width
  43 .br
  44 \-help  Standard help message
  45 .PP
  46 All of the functions these switches perform are affected or controlled
  47 by information elsewhere.  That is, the format file can specify "clear",
  48 in which case, the command line switches will override.  Also, the
  49 length and width can be specified in the format file, or default to
  50 40x80.  The folder is used in constructing a message name (see special
  51 component "MessageName" below).  If it is not specified in a switch, it
  52 is taken from the environment variable "mhfolder", which show, next,
  53 prev, and pick initialize appropriately.
  54 .PP
  55 If the form file is not specified, it is taken from the file
  56 "mhl.format" in the user's MH directory, and if that file doesn't exist,
  57 it is taken from "/etc/mh/mhl.format". (Same evaluation hierarchy as the
  58 compose form file.)
  59 .PP
  60 Mhl operates in two phases: 1) read and parse the format file, and 2)
  61 process each message (file).  During phase 1, an internal description of
  62 the format is produced as a structured list.  In phase 2, this list is
  63 walked for each message, outputing message information under the format
  64 constraints from the format file.
  65 .PP
  66 The "mhl.format" file contains information controlling screen clearing,
  67 screen size, wraparound control, transparent text, component ordering,
  68 and component formatting.  Also, a list of components to ignore may be
  69 specified, and a couple of "special" components are defined  to  provide
  70 added  functionality.  Message  output will be in the order specified by
  71 the order in the format file.
  72 .PP
  73 Each line of mhl.format has one of the formats:
  74 .PP
  75         ;comment
  76 .br
  77         :cleartext
  78 .br
  79         variable[,variable...]
  80 .br
  81         component:[variable,...]
  82 .PP
  83 A line beginning with a ";"  is  a  comment,  and  is  ignored.  A  line
  84 beginning with a ":" is clear text, and is output exactly as is. (A line
  85 containing only a ":" produces a blank  line  in  the  output.)  A  line
  86 beginning  with  "component:"  defines  the  format  for  the  specified
  87 component, and finally, remaining lines define the global environment.
  88 .PP
  89 For example, the line:
  90 .PP
  91 width=80,length=40,clearscreen,overflowtext=***,overflowoffset=5
  92 .PP
  93 defines the screen size to be 80 columns by 40 rows, specifies that  the
  94 screen  should  be  cleared  prior  to  each  page,  that  the  overflow
  95 indentation is 5, and that overflow text should be flagged with "***".
  96 .PP
  97 Following are all of the current  variables  and  their  argmuments.  If
  98 they  follow  a component, they apply only to that component, otherwise,
  99 their affect is global.  Since the whole format  is  parsed  before  any
 100 output processing, the last global switch setting for a variable applies
 101 to the whole message.
 102 .TP 15
 103 width=#
 104 Screen width, component width
 105 .TP
 106 overflowtext=t
 107 Text to use at the beginning of an overflow line
 108 .TP
 109 overflowoffset=#
 110 Positions to indent overflow lines
 111 .TP
 112 compwidth=#
 113 Positions to indent component text after first line
 114 .TP
 115 nocomponent
 116 Don't output "component: " for this component
 117 .TP
 118 uppercase
 119 Output text of this component in all upper case
 120 .TP
 121 center
 122 Center component on line (works for one-line components only)
 123 .TP
 124 clearscreen
 125 Clear the screen (form feed) prior to each page
 126 .TP
 127 leftadjust
 128 Strip off leading spaces & tabs on each line of text
 129 .TP
 130 compress
 131 Change newlines in text to spaces
 132 .PP
 133 Where "=#" indicates a number must be specified, and "=t" indicates that
 134 arbitrary  text  up  to  end  of line or "," is required.  The variables
 135 without arguments are ON indicators, with the default in all cases  OFF.
 136 The  variables  "nocomponent",  center,  leftadjust and compress have no
 137 affect globally, and clearscreen only affects the global environment.
 138 .PP
 139 A line of the form:
 140 .PP
 141 ignores=component,...
 142 .PP
 143 specifies a list of components which are never output.
 144 .PP
 145 The component "MessageName" (case is unimportant) will output the actual
 146 message  name  (file  name) preceded by "folder:" if one is specified or
 147 found in the environment.
 148 .PP
 149 The component "Extras" will output all of the components of the  message
 150 which were not matched by explicit components, or included in the ignore
 151 list.  If this component is not specified, an ignore list is not  needed
 152 since all non-specified components will be ignored.
 153 .PP
 154 If "nocomponent" is NOT specified, then the component name will be output
 155 as it appears in the format file.
 156 .PP
 157 The current default format is:
 158 .PP
 159 width=80,length=40,overflowtext=***,overflowoffset=5
 160 .br
 161 ignores=msgid,message-id
 162 .br
 163 Date:leftadjust,offset=40
 164 .br
 165 To:leftadjust
 166 .br
 167 Cc:leftadjust
 168 .br
 169 :
 170 .br
 171 From:leftadjust
 172 .br
 173 Subject:leftadjust
 174 .br
 175 :
 176 .br
 177 extras:leftadjust,nocomponent
 178 .br
 179 :
 180 .br
 181 body:nocomponent
 182 .SH FILES
 183 .SH SEE ALSO
 184 c(1),