Re: Review of new man page of sensible-editor

Bastien Roucariès wrote:
> Could you review/improve sensible-editor new man page ?

Mostly fixing up the grammar, but I do have a couple of questions
about what it's trying to say.

First here's a commented diff; corresponding revised version attached.

 --- sensible-editor.man 2022-08-16 12:36:45.476514262 +0100
 +++ sensible-editor.man.new     2022-08-16 13:55:15.152497001 +0100
 @@ -11,74 +11,75 @@
  as their default editor.
  .nr step 1 1

(I don't remember the details of groff well enough to be sure there
aren't subtle bugs in the markup, but it seems to work.)

  .B sensible-editor
 -try to do in the following order:
 +looks for an editor in various places in the following order:

There's a recurring number-agreement error, but I've also rephrased it
slightly.

  .IP \n[step]
 -if
 +if the

Recurring article shortage.

  .B VISUAL
  environment variable exists, execute
  .B $VISUAL [OPTIONS...];
 -if fail continue to next step
 +if this fails, it continues to the next step
  .IP \n+[step]
 -if
 +if the
  .B EDITOR
  environment variable exists, execute
  .B $EDITOR [OPTIONS...]; 
 -if fail continue to next step
 +if this fails, it continues to the next step

Converting from pseudocode to English sentences throughout...

  .IP \n+[step]
 -if
 +if the
  .B SENSIBLE_EDITOR
  environment variable exists, execute
  .B $SENSIBLE_EDITOR [OPTIONS...];
 -if fail continue to next step
 +if this fails, it continues to next step
  [...]

And so on.  By the way, I've always wondered why it bothers doing
anything beyond checking /usr/bin/editor; after all, if nano is
installed but there's no editor symlink, the sysadmin must have broken
it, presumably to stop things like this working!

  .SH "NOTES"
 -This script executes environment variable using as specicified by 
 +This script executes environment variables as specified in
  .BR environ (7):
  .I
  sh\ \-c "$CMD \\"\\$@\\"" "CMD" "$@"

Whatever this is trying to explain, I can't believe it's the clearest
way of doing it (since for a start the reader has to understand the
difference between $@, "$@", and "\"$@\"", and is never told where $@
comes from).  Does it perhaps all boil down to "when sensible-editor
runs a command, variable substitutions are unquoted, but the script's
arguments are passed on as individually double-quoted strings"?

 -command. Any string acceptable as a command-string operand to the
 +where any string acceptable as a command-string operand to the
  .I
  sh\ \-c
 -command is wherefore valid as

what do you mean by "wherefore" here?

 +command is valid as
  .I $CMD.
 -Moroever

Spelled "moreover", except that the word doesn't really fit here.

 +The
  .I $0
 -variable will contains the name of the variable used, respectively

This is a bit obscure, since no $0 has been mentioned.  If I'm fluent
in shell and want to know exactly how sensible-editor is implemented,
can't I just read it?

Also, the English word "respectively" never behaves like this.

 +variable will contain the name of the variable used, whether that's

  .B VISUAL,
  .B EDITOR,
 +or
  .B SENSIBLE_EDITOR

(Wait, the *names* of those variables are used as $0?  What good does
that do?)

  .PP
 -Exit status of 126 (command is found but is not executable) and 127 (given command is not found within your
 +An exit status of 126 (command is found but is not executable) or 127 (given command is not found within your
  .B $PATH)
 -are considered as failure of command, for the purpose of sensible-editor.
 +are considered as indicating the failure of a command, for the purposes of sensible-editor.

Inserting various missing words.

  .SH "SEE ALSO"
  .BR environ (7)
  for documentation of the
 @@ -92,10 +93,10 @@
  .BR editor (1)
  for default system wide editor.
  .SH BUGS
 -This command is protected against trivial fork bomb, when user set
 +This command is protected against the trivial fork bomb when a user sets
  .B EDITOR=sensible-editor
 -wider loops are still possible.
 +but wider loops are still possible.
  .SH "STANDARD"
 -Documentation of behavior of sensible-utils under a debian system is available under
 -section 11.4 of debian-policy usually installed under
 +Documentation for the behavior of sensible-utils under a Debian system is available under
 +section 11.4 of Debian-Policy, usually installed under
  /usr/share/doc/debian-policy (you might need to install debian-policy)

It's a bit odd to expect users to install a package that's aimed at
Debian developers when they could just read it online at
	https://www.debian.org/doc/debian-policy/
but I suppose man pages tend to prefer pointers to local resources.
-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package

.\" -*- nroff -*-
.TH SENSIBLE-EDITOR 1 "14 Nov 2018" "Debian"
.SH NAME
sensible-editor \- sensible editing
.SH SYNOPSIS
.BR sensible-editor " [OPTIONS...]"
.br
.SH DESCRIPTION
.BR sensible-editor " makes sensible decisions on which editor to call.
Programs in Debian can use this script
as their default editor.
.nr step 1 1
.B sensible-editor
looks for an editor in various places in the following order:
.IP \n[step]
if the
.B VISUAL
environment variable exists, execute
.B $VISUAL [OPTIONS...];
if this fails, it continues to the next step
.IP \n+[step]
if the
.B EDITOR
environment variable exists, execute
.B $EDITOR [OPTIONS...]; 
if this fails, it continues to the next step
.IP \n+[step]
if the
.B SENSIBLE_EDITOR
environment variable exists, execute
.B $SENSIBLE_EDITOR [OPTIONS...];
if this fails, it continues to next step
.IP \n+[step]
source the contents of file
.I ~/.selected_editor
and, if the
.B SELECTED_EDITOR
environment variable exists, execute
.B $SELECTED_EDITOR [OPTIONS...];
if this fails, it continues to the next step
.IP \n+[step]
run the
.B editor [OPTIONS...]
command; 
if this fails, it continues to the next step
command
.IP \n+[step] run
run the
.B nano [OPTIONS...]
command;
if this fails, it continues to the next step
.IP \n+[step]
run the
.B nano-tiny [OPTIONS...]
command;
if this fails, it continues to the next step
.IP \n+[step]
finally run the
.B vi [OPTIONS...]
command;
if this fails, it errors out.
.SH "NOTES"
This script executes environment variables as specified in
.BR environ (7):
.I
sh\ \-c "$CMD \\"\\$@\\"" "CMD" "$@"
where any string acceptable as a command-string operand to the
.I
sh\ \-c
command is valid as
.I $CMD.
The
.I $0
variable will contain the name of the variable used, whether that's
.B VISUAL,
.B EDITOR,
or
.B SENSIBLE_EDITOR
.PP
An exit status of 126 (command is found but is not executable) or 127 (given command is not found within your
.B $PATH)
are considered as indicating the failure of a command, for the purposes of sensible-editor.
.SH "SEE ALSO"
.BR environ (7)
for documentation of the
.B EDITOR,
.B VISUAL
variables
.br
.BR select-editor (1)
for changing a user's default editor.
.br
.BR editor (1)
for default system wide editor.
.SH BUGS
This command is protected against the trivial fork bomb when a user sets
.B EDITOR=sensible-editor
but wider loops are still possible.
.SH "STANDARD"
Documentation for the behavior of sensible-utils under a Debian system is available under
section 11.4 of Debian-Policy, usually installed under
/usr/share/doc/debian-policy (you might need to install debian-policy)