Hi Tom,
Tom Smyth wrote on Mon, Apr 25, 2022 at 11:08:26AM +0100:
> I have been translating the txt of MANUAL of nsh port to mandoc
In fact, you have started translating it to mdoc(7) - which is a markup
language - rather than to mandoc(1) - which is a parsing and formatting
program for multiple markup languages including mdoc(7).
> there is quite alot of features and syntax to document
Wow, indeed. What a beast!
> so I figured that before I complete the first redraft (that is fit for
> human consumption) I would get feedback on what I have done so far.
>
> do you like the bullets are they too much
My impression is that bullet lists are indeed overused.
> what I should do more of?
> what i should do less of?
I suggest making sure that features are described completely and
consisely and not only demonstrated by examples. You certainly
do not need to add more examples. Wording, grammar, and punctuation
might profit from some polishing throughout. Some text feels rather
wordy and repetitive for a manual page but somewhat vague at the
same time.
In a manual page, the DESCRIPTION needs particular attention because
it's the first part readers look at. Choosing a good order and
weeding out repetions is particularly important in that section.
> any advice comments would be appreciated
OK, let's have a stab at it:
> .\" NSH is BSD licensed
Instead of this line, insert the complete text of the license that
applies to the manual page file, including a "Copyright" line.
Look in /usr/share/man/man8/ for examples.
> .Nd Network configuration shell
Use lower case instead of sentence case in the .Nd line.
> .Bk -words ... .Ek
No need for that, just delete both the .Bk and the .Ek line.
> .Op Fl i Ar rcfile
> .Op Fl c Ar rcfile
Use different placeholder names for different option arguments.
Make them as descriptive as possible.
> for other daemons into one place, providing an alternative
> to /etc/netstart and parts of /etc/rc.
Make that
an alternative to
.Xr netstart 8
and parts of
.Xr rc 8 .
> .sp
Never use .sp in manual pages. Use .Pp instead.
> .Nm
> encapsulates the following daemons and services:
Very subtle markup bug here: outside literal context, you almost never
want to start a line in roff(7) code with a space character.
In roff(7), a leading space character means "break the output line
and indent the next line by a space character - look at the output:
nsh
encapsulates the following daemons and services:
That's very ugly and a bit confusing. Search your file for lines
starting with spaces, there are several more examples.
> pf, ospfd, ospf6d, bgpd, ripd, ldpd, relayd, ipsecctl, iked, rtadvd,
> dvmrpd, sasyncd, dhcpd, snmpd, sshd, ntpd, ifstated, tftp-proxy,
> ftp-proxy, tftpd, npppd, resolv.conf, inetd, smtpd, ldapd, ifstated
Ouch, what a monster. I'd probably do something like this:
.Bd -ragged -offset indent
.Xr pfctl 8 ,
.Xr ospfd 8 ,
.Xr ospf6d 8 ,
.Xr bgpd 8 ,
.Xr ripd 8 ,
...
.Ed
Consider some kind of sorting, maybe alphabetically.
This is bad because it destroys conciseness of the DESCRIPTION.
Maybe say something like
.Nm
encapsulates the functionality of more than two dozen
network-related programs.
See the
.Sx SEE ALSO
section for a complete list.
> .sp
> .Sh COMMAND LINE ARGUMENTS
No .Pp is needed right before .Sh.
Besides, command line options must *not* get their own .Sh. The list
of command line options is crucial content of the DESCRIPTION section
and must never be moved elsewhere.
> .Bl -tag -width 4
For the option list, ".Bl -tag -width Ds" is customary.
I see no reason to be different here.
> nsh will operate with verbose output
Missing full stop (not only here, there are several more instances).
Avoid future tense if you can (not only here, the document is full of
"will"). No need to repeat the command name here. This would be better:
.It Fl v
Produce verbose output.
The description of -c and -i needs to be improved. I don't understand
what the difference between the two might be.
> .Nm
> when run with out any arguments
When run without any command line arguments,
.Nm
does foobar...
> left right keys allow for
Is it using the editline library? In that case, consider .Xr'ing
to editline(7) rather than re-explaining how command line editing
works. If it uses some other library, link to that.
> .Bl -bullet
> .It
> nshprompt/show i
> .It
> % Ambigious argument i
> .El
Code examples and examples of interactive use should not use bullet
lists but ".Bd -unfilled" or ".Bd -literal". I guess "nshprompt/"
is the prompt? That's exceedingly ugly. Can you use a better prompt
for the manual page, ideally one that ends in a space character and is
much shorter? For example:
.Bd -unfilled -offset indent
nsh/ show i
% Ambigious argument i
.Ed
The bullet list after "commandline completion display"
could be formatted like this:
.Bd -literal -offset indent
nsh(p)/ i<Tab>
ifstate inet ip ipsec
ike interface ip6
.Ed
I don't think you want blank lines in there.
There are many examples that can be improved in this way.
> .sp
> .Ss Command History
Again, don't use .sp, and in particular not before .Sh and .Ss.
This needs fixing at many places.
> Any affirmative commands that do not contain 'enable' keyword
Any affirmative commands that do not contain the
.Ic enable
keyword can be reversed with the
.Ic no
keyword in front of ...
Don't use the word "prefix" here; to me, that sound as if i would
have to write
noip forwarding
It appears "no" really is a separate (key)word, not a prefix.
> .Nm
> shell starts as an unprivileged prompt which displays as the text
> of the FQDN (fully qualfied domain name) of the machine followed
> by a forward slash.
That needs to be said earlier such that readers can understand
the examples.
> .Bl -dash
> .It
> E.g. standard prompt of the device firewall.machine.com
> .Bl -bullet
> .It
> firewall.machinename.com/
> .El
> .El
Usually, do not write a list when there is only a single entry,
except in standard cases like the list of command line options
or the ERRORS section. Besides, i think the example is pointless.
What could possibly be unclear about "FQDN followed by a slash"?
> .Sh INTERACTIVE COMMANDS
> .Ss ? | help
> .Ic ? | help
That's redundant and ugly, get rid of the .Ss'es.
Command lists are a typical use case for .Bl -tag, for example:
.Sh INTERACTIVE COMMANDS
.Bl -tag -width Ds
.It Ic help | \&? Op Ar command
Display a one-line description of the given
.Ar command .
If the
.Ar command
argument is omitted, display the list of commands that can be used
in the current
.Nm
mode.
.It Ic hostname Op Ar fqdn
Set the hostname to
.Ar fqdn .
When the argument is omitted, display the currently configured hostname.
.It Ic ...
The commands should probably be sorted alphabetically, both in the manual
page and in the help output. When there are many command, this matters
even more than usual for readability.
> .Ss enable
.Tg rtable
.It Oo Ic no Oc Ic rtable Oo Ar table-id Oc Op name
In such cases, the .Tg macro is useful to make ":t rtable" work in man(1).
> .Sh FILES
> .Bl -bullet -compact
> .It
> .Pa /etc/nshrc
> Global configuration file.
FILES does not use .Bl.
.Sh FILES
.Bl -tag -width /etc/suid_profile -compact
.It Pa /etc/nshrc
global configuration file
...
No capitalization and no full stop here, these are not complete sentences.
> .Sh VERSION
This section seems pointless to me. A manual page is always distributed
together with the software, so it goes without saying which version it
refers to: the installed version. Trivial to find out with pkg_info(1),
for example.
> .Sh AUTHORS
.Sh AUTHORS
.An -nosplit
This shell was originally designed and written by
.An Chris Cappuccio Aq Mt chris@nmedia.net
and is now co-maintained by
.An Tom Smyth Aq Mt tom.smyth@wirelessconnect.eu .
Licensing information does not belong into this section but into
a comment at the top of the file.
> .Sh CONTRIBUTORS
That's an utterly non-standard section, delete it.
I don't see a need to mention the file in the manual page at all,
but if you really want to mention it, you could put this at the
end of the AUTHORS section:
.Pp
The
.Pa CONTRIBUTORS
file in the source distribution contains a more complete list of people
and their part in the shell's development.
But i doubt the usefulness in a manual page because end-users typically
won't have the sources installed, so they won't have the file.
I guess that's already a lot for now... When you finish the above,
there is likely more work to do. But i think getting this manual
into shape is likely to succeed, you seem to have most of the
content in place already and some of the formatting is already good.
> before we push the diff into ports / upstream nsh
If at all possible, try to get the manual page into the upstream
distribution rather than putting it into the port only. That is
much better for maintainability on both sides.
Yours,
Ingo
No comments:
Post a Comment