Hi Tom,
Tom Smyth wrote on Mon, May 02, 2022 at 01:46:50AM +0100:
> while documenting nsh and its features,
> I wanted to display the command switches of telnet command inside the
> manual page for nsh,
Don't.
This is not a technical problem: "how can i technically do this"
is the wrong question to ask.
This is a problem of manual page design and content organisation.
Having a large amount of identical text in two manual pages is a
bad idea because readers will wonder whether the text is indeed
identical or whether there are subtle differences. They will likely
waste time by starting to compare the two pages to track down the
differences.
Besides, displaying lots of content from one page in another is
bad documentation design because it detracts from the topic of
the other page. Instead, explain in the other page which content
of the first page also applies here, as precisely as possible.
> I would like to display , the contents of the
> telnet , name synopsis and description sections from the telnet
> manpage in the nsh man page without copying the contents of the man
> page. (so that the command line switches / arguments are up to date
> for a given OpenBSD version
>
> for now i have done telnet client documentation in nsh as follows
> .Tg telnet
Most likely, .Tg is not needed right in front of .Ic with the same
argument. Does :t telnet not work without it?
> .Ic telnet
> .Op -a
That should be ".Op Fl a"; the same applies below.
> .Op -b host-alias
> .Op -l user-name
> .Ar host-name
Just ".Ar host" is enough; it may not even be a name.
> .Op Ar port
> .Pp
> Open a telnet client session to the remote host host-name.
Better:
Open a
.Xr telnet 1
session to the remote server
.Ar host ,
which can be specified by name or IP address.
> Where host-name can be a name or IP address of the remote host.
> port is the TCP port on the remote host which you wish to connect and port
> can be within the range 0-65535.
> The
> .Ic -a
> switch will attempt an automatic login if the setup permits it.
> The
> .Ic -b host-alias
> will bind the source IP telnet client session to a specific ip address alias
> rather than the primary ip address on a given interface.
> See
the
> .Xr telnet 1
> man page for a comprehensive list of telnet command options.
Yes, that is how to do it.
Nits: s/man/manual/; s/command/command line/
I think i would trim this down even more.
The -a and -l options are unimportant because nobody should use
telnet(1) with authentication. The -b option is unimportant because
the automatically selected source address is almost always just fine.
So just
.Ic telnet
.Op Ar options
.Op Ar host Op port
.Pp
Open a
.Xr telnet 1
session to the given TCP
.Ar port
on the remote server
.Ar host ,
specified by name or IP address.
The
.Ar options
are documented in the
.Xr telnet 1
manual page.
seems better to me: precise and concise.
> .Bd -literal -offset indent
> nsh(p)/!man telnet
> .Ed
This example is probably superfluous at this point.
Escaping to a shell (i guess that is what "!" means)
ought to be documented in a different part of this manual page,
and apart from that, the example is trivial.
> any thoughts / advice welcome
Hope this helps,
Ingo
No comments:
Post a Comment