Factor trim format function out

[mmh] / man / prompter.man1

diff --git a/man/prompter.man1 b/man/prompter.man1
index f83a9db..e4738db 100644 (file)
--- a/man/prompter.man1
+++ b/man/prompter.man1
@@ -3,33 +3,29 @@
 .\"
 .TH PROMPTER %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
 .SH NAME
 .\"
 .TH PROMPTER %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
 .SH NAME

-prompter \- prompting editor front-end for nmh
+prompter \- prompting editor front-end for mmh

 .SH SYNOPSIS
 .HP 5
 .na
 .B prompter
 .SH SYNOPSIS
 .HP 5
 .na
 .B prompter

-.RB [ \-erase
-.IR chr ]
-.RB [ \-kill
-.IR chr ]

 .RB [ \-prepend " | " \-noprepend ]
 .RB [ \-rapid " | " \-norapid ]
 .RB [ \-prepend " | " \-noprepend ]
 .RB [ \-rapid " | " \-norapid ]

-.RB [ \-doteof " | " \-nodoteof ]
+.RB [ \-body " | " \-nobody ]

 .I file
 .RB [ \-Version ]
 .RB [ \-help ]
 .ad
 .SH DESCRIPTION
 .B Prompter
 .I file
 .RB [ \-Version ]
 .RB [ \-help ]
 .ad
 .SH DESCRIPTION
 .B Prompter

-is an editor front\-end for
-.B nmh
+is an editor front-end for
+.B mmh

 which allows rapid
 composition of messages.  This program is not normally invoked directly by
 which allows rapid
 composition of messages.  This program is not normally invoked directly by

-users but takes the place of an editor and acts as an editor front\-end.
-It operates on an RFC\-822 style message draft skeleton specified by
+users but takes the place of an editor and acts as an editor front-end.
+It operates on an RFC-822 style message draft skeleton specified by

 .IR file ,
 normally provided by the
 .IR file ,
 normally provided by the

-.B nmh
+.B mmh

 commands
 .BR comp ,
 .BR dist ,
 commands
 .BR comp ,
 .BR dist ,

@@ -39,9 +35,7 @@ or
 .PP
 .B Prompter
 is particularly useful when composing messages over slow
 .PP
 .B Prompter
 is particularly useful when composing messages over slow

-network or modem lines.  It is an
-.B nmh program in that it can have
-its own profile entry with switches, but it is not invoked directly by
+network or modem lines.  It is hardly invoked directly by

 the user.  The commands
 .BR comp ,
 .BR dist ,
 the user.  The commands
 .BR comp ,
 .BR dist ,

@@ -49,33 +43,43 @@ the user.  The commands
 and
 .B repl
 invoke
 and
 .B repl
 invoke

-.B prompter as an editor, either when invoked with
+.B prompter
+as an editor, either when invoked with

 .B \-editor
 .IR prompter ,
 .B \-editor
 .IR prompter ,

-or by the profile entry \*(lqEditor:\ prompter\*(rq,
+or by the profile entry `Editor:\ prompter',

 or when given the command
 or when given the command

-.B edit
-.B prompter
-at the \*(lqWhat now?\*(rq prompt.
+.B edit prompter
+at the `What now?' prompt.

 .PP
 For each empty component
 .PP
 For each empty component

-.B prompter finds in the draft, the user
-is prompted for a response; A <RETURN> will cause the whole component
-to be left out.  Otherwise, a `\\' preceding a <RETURN> will continue
+.B prompter
+finds in the draft, the user
+is prompted for a response. An empty response will cause the whole component
+to be left out.  Otherwise, a `\\' preceding the Newline will continue

 the response on the next line, allowing for multiline components.
 Continuation lines
 .B must
 begin with a space or tab.
 .PP
 the response on the next line, allowing for multiline components.
 Continuation lines
 .B must
 begin with a space or tab.
 .PP

-Each non\-empty component is copied to the draft and displayed on the
+Each non-empty component is copied to the draft and displayed on the

 terminal.
 .PP
 The start of the message body is denoted by a blank line or a line
 terminal.
 .PP
 The start of the message body is denoted by a blank line or a line

-of dashes.  If the body is non\-empty, the prompt, which isn't written
-to the file, is
+of dashes.
+Unless
+.B \-nobody
+is specified, the user is queried to enter the message body.
+If the body of the draft is non-empty, the typed-in text will be prepended
+or appended to the existing body, depending on the
+.B \-prepend
+and
+.B \-noprepend
+switches.
+In these cases, the prompt (which isn't written to the file) is

 .PP
 .RS 5
 .PP
 .RS 5

---------Enter additional text
+\-\-\-\-\-\-\-\-Enter additional text

 .RE
 .PP
 or (if
 .RE
 .PP
 or (if

@@ -83,60 +87,61 @@ or (if
 was given)
 .PP
 .RS 5
 was given)
 .PP
 .RS 5

---------Enter initial text
+\-\-\-\-\-\-\-\-Enter initial text

 .RE
 .PP
 .RE
 .PP

-Message\-body typing is terminated with an end\-of\-file (usually
-CTRL\-D).  With the
-.B \-doteof
-switch, a period on a line all by itself
-also signifies end\-of\-file.  At this point control is returned to
-the calling program, where the user is asked \*(lqWhat now?\*(rq.
+Message-body typing is terminated with an end-of-file (usually
+CTRL-D).
+At this point control is returned to
+the calling program, where the user is asked `What now?'.

 See
 .B whatnow (1)
 for the valid options to this query.
 .PP
 By using the
 See
 .B whatnow (1)
 for the valid options to this query.
 .PP
 By using the

+.B \-nobody
+switch, the user is only queried to fill in header fields, but not to enter
+any body text.
+Note, that the
+.BR \-body and \-nobody
+switches had already existed already in
+.B nmh
+in undocumented/hidden form,
+but with a slightly different meaning.
+Back then,
+.B "prompter \-nobody
+would change the draft to have an empty body,
+by ignoring any existing body and not querying the user for body text.
+.PP
+By using the

 .B \-prepend
 .B \-prepend

-switch, the user can add type\-in to the
+switch, the user can add type-in to the

 beginning of the message body and have the rest of the body follow.
 beginning of the message body and have the rest of the body follow.

-This is useful for the
-.B forw
-command.
+With
+.B \-noprepend
+the typed-in text is appended to the message body.

 .PP
 By using the
 .B \-rapid
 switch, if the draft already contains text in
 .PP
 By using the
 .B \-rapid
 switch, if the draft already contains text in

-the message\-body, it is not displayed on the user's terminal.  This is
-useful for low\-speed terminals.
+the message-body, it is not displayed on the user's terminal.  This is
+useful for low-speed terminals.

 .PP
 .PP

-The line editing characters for kill and erase may be specified by the
-user via the arguments
-.B \-kill
-.I chr
-and
-.B \-erase
-.IR chr ,
-where
-.I chr
-may be a character; or `\\nnn', where \*(lqnnn\*(rq is the octal value for
-the character.
-.PP
-An interrupt (usually CTRL\-C) during component typing will abort
+An interrupt (usually CTRL-C) during component typing will abort

 .B prompter
 and the
 .B prompter
 and the

-.B nmh
+.B mmh

 command that invoked it.  An interrupt
 command that invoked it.  An interrupt

-during message\-body typing is equivalent to CTRL\-D, for historical
-reasons.  This means that
+during message-body typing is equivalent to CTRL-D, for historical
+reasons and to avoid losing the typed-in message text.  This means that

 .B prompter
 .B prompter

-should finish up and exit.
+should finish up and exit, usually putting the user back to the
+Whatnow prompt.

 .PP
 .PP

-The first non\-flag argument to
-.B prompter is taken as the name of
-the draft file, and subsequent non\-flag arguments are ignored.
-.\" (\fIRepl\fR invokes editors with two file arguments:
-.\" the draft file name and the replied\-to message file name.)
+The first non-flag argument to
+.B prompter
+is taken as the name of
+the draft file, and subsequent non-flag arguments are ignored.

 
 .SH FILES
 .fc ^ ~
 
 .SH FILES
 .fc ^ ~

@@ -151,7 +156,7 @@ the draft file, and subsequent non\-flag arguments are ignored.
 .nf
 .ta 2.4i
 .ta \w'ExtraBigProfileName  'u
 .nf
 .ta 2.4i
 .ta \w'ExtraBigProfileName  'u

-prompter\-next:        To name the editor to be used on exit from .B prompter
+prompter\-next:        The editor to be used on exit from \fBprompter\fP

 ^Msg\-Protect:~^To set mode when creating a new draft
 .fi
 
 ^Msg\-Protect:~^To set mode when creating a new draft
 .fi
 

@@ -160,9 +165,9 @@ comp(1), dist(1), forw(1), repl(1), whatnow(1)
 
 .SH DEFAULTS
 .nf
 
 .SH DEFAULTS
 .nf

+.RB ` \-body '

 .RB ` \-prepend '
 .RB ` \-norapid '
 .RB ` \-prepend '
 .RB ` \-norapid '

-.RB ` \-nodoteof '

 .fi
 
 .SH CONTEXT
 .fi
 
 .SH CONTEXT

@@ -170,26 +175,40 @@ None
 
 .SH "HELPFUL HINTS"
 The
 
 .SH "HELPFUL HINTS"
 The

-.B \-rapid
-option is particularly useful with
-.BR forw ,
-and

 .B \-noprepend
 .B \-noprepend

-is useful with
+switch is particularly useful with

 .B comp
 .BR \-use .
 .PP
 The user may wish to link
 .B comp
 .BR \-use .
 .PP
 The user may wish to link

-.B prompter under several names (e.g.,
-\*(lqrapid\*(rq) and give appropriate switches in the profile entries
-under these names (e.g., \*(lqrapid: -rapid\*(rq).  This facilitates
+.B prompter
+under several names (e.g.,
+`rapid') and give appropriate switches in the profile entries
+under these names (e.g., `rapid: \-rapid').  This facilitates

 invoking prompter differently for different
 invoking prompter differently for different

-.B nmh
+.B mmh

 commands (e.g.,
 commands (e.g.,

-\*(lqforw: -editor rapid\*(rq).
-
-.SH BUGS
-.B Prompter
-uses
-.BR stdio (3),
-so it will lose if you edit files with nulls in them.
+`forw: \-editor rapid').
+.PP
+Former
+.B mutt
+users might find it useful to create a shell script
+.B hprompter
+containing:
+.PP
+.RS 5
+.nf
+prompter \-nobody \-rapid "$1"
+vi "$1"
+.fi
+.RE
+.LP
+and use that as the default editor for
+.B comp
+by adding a profile entry like:
+.PP
+.RS 5
+.nf
+comp: \-editor hprompter
+.fi
+.RE