Return to mhl.rf CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / mh / conf / doc

Annotation of 43BSD/contrib/mh/conf/doc/mhl.rf, revision 1.1

1.1     ! root        1: .\"    @(MHWARNING)
        !             2: .TH MHL 1 "April 22, 1986" MH [mh.6]
        !             3: .UC 6
        !             4: .SH NAME
        !             5: mhl \- produce formatted listings of MH messages
        !             6: .SH SYNOPSIS
        !             7: .in +.5i
        !             8: .ti -.5i
        !             9: @(MHETCPATH)/mhl
        !            10: \%[\-bell] \%[\-nobell]
        !            11: \%[\-clear] \%[\-noclear]
        !            12: \%[\-folder\ +folder]
        !            13: \%[\-form\ formfile]
        !            14: \%[\-length\ lines] \%[\-width\ columns] 
        !            15: \%[\-moreproc\ program] \%[\-nomoreproc]
        !            16: \%[files\ ...]
        !            17: \%[\-help] 
        !            18: .in -.5i
        !            19: .SH DESCRIPTION
        !            20: \fIMhl\fR is a formatted message listing program.
        !            21: It can be used as a replacement for \fImore\fR\0(1)
        !            22: (the default \fIshowproc\fR\0).
        !            23: As with \fImore\fR,
        !            24: each of the messages specified as arguments (or the standard input) will be
        !            25: output.
        !            26: If more than one message file is specified,
        !            27: the user will be prompted prior to each one,
        !            28: and a <RETURN> or <EOT> will begin the output,
        !            29: with <RETURN> clearing the screen (if appropriate),
        !            30: and <EOT> (usually CTRL\-D) suppressing the screen clear.
        !            31: An <INTERRUPT> (usually CTRL\-C) will abort the current message output,
        !            32: prompting for the next message (if there is one),
        !            33: and a <QUIT> (usually CTRL-\\) will terminate the program (without core dump).
        !            34: 
        !            35: The `\-bell' option tells \fImhl\fR to ring the terminal's bell at the end of each page,
        !            36: while the `\-clear' option tells \fImhl\fR to clear the scree at the end of
        !            37: each page (or output a formfeed after each message).
        !            38: Both of these switches (and their inverse counterparts)
        !            39: take effect only if the profile entry \fImoreproc\fR is defined but empty,
        !            40: and \fImhl\fR is outputting to a terminal.
        !            41: If the \fImoreproc\fR entry is defined and non-empty,
        !            42: and \fImhl\fR is outputting to a terminal,
        !            43: then \fImhl\fR will cause the \fImoreproc\fR to be placed between the
        !            44: terminal and \fImhl\fR and the switches are ignored.
        !            45: Furthermore,
        !            46: if the `\-clear' switch is used and \fImhl's\fR output is directed to a
        !            47: terminal,
        !            48: then \fImhl\fR will consult the \fB$TERM\fR and \fB$TERMCAP\fR
        !            49: envariables to determine the user's
        !            50: terminal type in order to find out how to clear the screen.
        !            51: If the `\-clear' switch is used and \fImhl's\fR output is not directed to
        !            52: a terminal (e.g., a pipe or a file),
        !            53: then \fImhl\fR will send a formfeed after each message.
        !            54: 
        !            55: To override the default \fImoreproc\fR and the profile entry,
        !            56: use the `\-moreproc\ program' switch.
        !            57: 
        !            58: The `\-length\ length' and `\-width\ width' switches set the screen length and
        !            59: width, respectively.
        !            60: These default to the values indicated by \fB$TERMCAP\fR,
        !            61: if appropriate,
        !            62: otherwise they default to 40 and 80, respectively.
        !            63: 
        !            64: The default format file used by \fImhl\fR is called \fImhl.format\fR
        !            65: (which is first searched for in the user's \fIMH\fR directory,
        !            66: and then sought in the \fI@(MHETCPATH)\fR directory),
        !            67: this can be changed by using the `\-form\ formatfile' switch.
        !            68: 
        !            69: Finally,
        !            70: the `\-folder\ +folder' switch sets the \fIMH\fR folder name,
        !            71: which is used for the \*(lqmessagename:\*(rq field described below.
        !            72: The envariable \fB$mhfolder\fR is consulted for the default value,
        !            73: which \fIshow\fR, \fInext\fR, and \fIprev\fR initialize appropriately.
        !            74: 
        !            75: \fIMhl\fR operates in two phases:
        !            76: 1) read and parse the format file,
        !            77: and 2) process each message (file).
        !            78: During phase 1,
        !            79: an internal description of the format is produced as a structured list.
        !            80: In phase 2,
        !            81: this list is walked for each message,
        !            82: outputting message information under the format constraints from the format
        !            83: file.
        !            84: 
        !            85: The \*(lqmhl.format\*(rq form file contains information controlling
        !            86: screen clearing, screen size, wrap\-around control, transparent text,
        !            87: component ordering, and component formatting.
        !            88: Also, a list of components to ignore may be specified,
        !            89: and a couple of \*(lqspecial\*(rq components are defined to provide added
        !            90: functionality.
        !            91: Message output will be in the order specified by the order in the format file.
        !            92: 
        !            93: Each line of mhl.format has one of the formats:
        !            94: 
        !            95:      ;comment
        !            96:      :cleartext
        !            97:      variable[,variable...]
        !            98:      component:[variable,...]
        !            99: 
        !           100: A line beginning with a `;' is a comment, and is ignored.
        !           101: A line beginning with a `:' is clear text,
        !           102: and is output exactly as is.
        !           103: A line containing only a `:' produces a blank line in the output.
        !           104: A line beginning with \*(lqcomponent:\*(rq defines the format for the specified
        !           105: component,
        !           106: and finally, remaining lines define the global environment.
        !           107: 
        !           108: For example, the line:
        !           109: 
        !           110: .ti +.5i
        !           111: width=80,length=40,clearscreen,overflowtext="***",overflowoffset=5
        !           112: 
        !           113: defines the screen size to be 80 columns by 40 rows,
        !           114: specifies that the screen should be cleared prior to each page,
        !           115: that the overflow indentation is 5,
        !           116: and that overflow text should be flagged with \*(lq***\*(rq.
        !           117: 
        !           118: Following are all of the current variables and their arguments.
        !           119: If they follow a component,
        !           120: they apply only to that component,
        !           121: otherwise, their affect is global.
        !           122: Since the whole format is parsed before any output processing,
        !           123: the last global switch setting for a variable applies to the whole message
        !           124: if that variable is used in a global context
        !           125: (i.e., bell, clearscreen, width, length).
        !           126: 
        !           127: .nf
        !           128: .in +.5i
        !           129: .ta \w'noclearscreen  'u +\w'integer/G  'u
        !           130: \fIvariable\fR \fItype\fR      \fIsemantics\fR
        !           131: width  integer screen width or component width
        !           132: length integer screen length or component length
        !           133: offset integer positions to indent \*(lqcomponent: \*(rq
        !           134: overflowtext   string  text to use at the beginning of an
        !           135:                overflow line
        !           136: overflowoffset integer positions to indent overflow lines
        !           137: compwidth      integer positions to indent component text
        !           138:                after the first line is output
        !           139: uppercase      flag    output text of this component in all
        !           140:                upper case
        !           141: nouppercase    flag    don't uppercase
        !           142: clearscreen    flag/G  clear the screen prior to each page
        !           143: noclearscreen  flag/G  don't clearscreen
        !           144: bell   flag/G  ring the bell at the end of each page
        !           145: nobell flag/G  don't bell
        !           146: component      string/L        name to use instead of \*(lqcomponent\*(rq for
        !           147:                this component
        !           148: nocomponent    flag    don't output \*(lqcomponent: \*(rq for this
        !           149:                component
        !           150: center flag    center component on line (works for
        !           151:                one\-line components only)
        !           152: nocenter       flag    don't center
        !           153: leftadjust     flag    strip off leading whitespace on each
        !           154:                line of text
        !           155: noleftadjust   flag    don't leftadjust
        !           156: compress       flag    change newlines in text to spaces
        !           157: nocompress     flag    don't compress
        !           158: formatfield    string  format string for this component
        !           159: addrfield      flag    field contains addresses
        !           160: datefield      flag    field contains dates
        !           161: .re
        !           162: .in -.5i
        !           163: .fi
        !           164: 
        !           165: To specify the value of integer\-valued and string\-valued variables,
        !           166: follow their name with an equals\-sign and the value.
        !           167: Integer\-valued variables are given decimal values,
        !           168: while string\-valued variables are given arbirtray text bracketed by
        !           169: double\-quotes.
        !           170: If a value is suffixed by \*(lq/G\*(rq or \*(lq/L\*(rq,
        !           171: then its value is useful in a global\-only or local\-only context
        !           172: (respectively).
        !           173: 
        !           174: A line of the form:
        !           175: 
        !           176:     ignores=component,...
        !           177: 
        !           178: specifies a list of components which are never output.
        !           179: 
        !           180: The component \*(lqMessageName\*(rq (case\-insensitive)
        !           181: will output the actual message name (file name) preceded by
        !           182: the folder name if one is specified or found in the environment.
        !           183: The format is identical to that produced by the `\-header' option to
        !           184: \fIshow\fR.
        !           185: 
        !           186: The component \*(lqExtras\*(rq will output all of the components of the message
        !           187: which were not matched by explicit components,
        !           188: or included in the ignore list.
        !           189: If this component is not specified,
        !           190: an ignore list is not needed since all non\-specified components will be
        !           191: ignored.
        !           192: 
        !           193: If \*(lqnocomponent\*(rq is NOT specified, then the component name will be
        !           194: output as it appears in the format file.
        !           195: 
        !           196: The default format is:
        !           197: 
        !           198: .nf
        !           199: .in +.5i
        !           200: .ne 15
        !           201: .eo
        !           202: .so @(MHETCPATH)/mhl.format
        !           203: .ec
        !           204: .in -.5i
        !           205: .fi
        !           206: 
        !           207: The variable \*(lqformatfield\*(rq specifies a format string
        !           208: (see \fImh\-format\fR(5)).
        !           209: The variables \*(lqaddrfield\*(rq and \*(lqdatefield\*(rq
        !           210: (which are mutually exclusive),
        !           211: control the interpretation of the escapes.
        !           212: 
        !           213: By default,
        !           214: \fImhl\fR does not apply any formatting string to fields containing address or
        !           215: dates (see \fImh\-mail\fR\0(5) for a list of these fields).
        !           216: Note that this results in faster operation
        !           217: since \fImhl\fR must parse both addresses and dates in order to apply a
        !           218: format string to them.
        !           219: If desired,
        !           220: \fImhl\fR can be given a default format string for either address or date
        !           221: fields (but not both).
        !           222: To do this,
        !           223: on a global line
        !           224: specify either the variable addrfield or the variable datefield,
        !           225: along with the variable formatfield.
        !           226: .Fi
        !           227: ^@(MHETCPATH)/mhl.format~^The message template
        !           228: ^or <mh\-dir>/mhl.format~^Rather than the standard template
        !           229: ^$HOME/\&.mh\(ruprofile~^The user profile
        !           230: .Pr
        !           231: ^moreproc:~^Program to use as interactive front\-end
        !           232: .Sa
        !           233: show(1), ap(8), dp(8)
        !           234: .De
        !           235: `\-bell'
        !           236: .Ds
        !           237: `\-noclear'
        !           238: .Ds
        !           239: `\-length 40'
        !           240: .Ds
        !           241: `\-width 80'
        !           242: .Co
        !           243: None
        !           244: .Bu
        !           245: There should be some way to pass `bell' and `clear' information to the 
        !           246: front\-end.
        !           247: 
        !           248: On hosts where \fIMH\fR was configured with the BERK option,
        !           249: address parsing is not enabled.
        !           250: .En

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.