Hello Ingo,
Thanks for all your feedback, It s very much appreciated.
Re mandoc(1) vs mdoc(7) thanks for the clarification for me, I will
try to use mdoc(7) when referring to the manpage language
Your formatting advice was very helpful
I have tried to fully implement your feedback as best I can with a couple of
exceptions.
.Ss section overuse for trivial commands have been removed but I propose
to retain .Ss for commands with a large subset of commands / sub menu
of commands
is this appropiate use of the .Ss sections ?
regarding Sorting ...I agree it needs to be improved,
Im caught between 3 conflicting methods
1) I think certain commands should be presented in the manual sooner
rather than later
(eg enable, show , ip , ip6 and interface )
2) anything else alphabetically
3) match the ordering of commands in the nsh program ... (some of the
commands probably should be re-ordered Ill discuss
this with Chris,
I think a hybrid between 1 and 2 options is probably best ...
(aphabetical by default and then present important basic commands
first (as an exception))
I will look at the tg macro again (i missed this completely but I
plan to incorporate your advice below shortly
.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).
Re Upstream Inclusion of the manual I have been discussing with Chris
and once I get a final draft (with current features documented) it
will be checked by Chris and included in the nsh source.
Attached is the updated version
any other feedback / adivce would be appreciated
Thanks again
Tom
On Mon, 25 Apr 2022 at 21:59, Ingo Schwarze <schwarze@usta.de> wrote:
>
> 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
--
Kindest regards,
Tom Smyth.
No comments:
Post a Comment