Hello Ingo,
thanks for your time on this your comments and advice were very helpful
just one follow up
the :t functionality in man did not seem to work unless I had the
.Tg telnet
line added
Thanks for the tip on the writing side... ( I must of gone to the
school were I learnend why say something in 10 words when you can say
the exact same thing in 100 words...
Im taking the lessons learned from the telnet command and applying it
else where in the man page thanks
here is what I ended up with for the telnet command in nsh
.Tg telnet
.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.
If the port is not specified the IANA assigned port 23 for telnet will be
used.
The
.Ar options
are documented in the
.Xr telnet 1
manual page.
Thanks again Ingo
Tom Smyth
On Mon, 2 May 2022 at 02:36, Ingo Schwarze <schwarze@usta.de> wrote:
>
> 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
--
Kindest regards,
Tom Smyth.
No comments:
Post a Comment