Re: Is there a way to display the block of another man page inside a man page
The point is that anyone reading the manual can look up a reference on the fly. No need for full text inclusion or fancy schemes. tilo
Re: Is there a way to display the block of another man page inside a man page
Hi, Tilo Stritzky wrote on Tue, May 03, 2022 at 08:45:05AM +0200: > On 02/05/22 01:46 Tom Smyth wrote: >> while documenting nsh and its features, >> I wanted to display the command switches of telnet command inside the >> manual page for nsh, > Within more/less you can get a shell by typing: > |.command > [pipe + period + command] > > That way you can nest as many manpages as you like in a single terminal. I have rarely seen worse advice regarding the design and writing of manual pages. To start with, Tom's idea of including substantial parts of the text of one manual page into another one was a bad idea, and he already admitted as much and settled for a much better solution for his actual task. Then, even if your idea worked, it would include the whole manual, including even headers and footers, and not just the parts Tom asked for. Most importantly, the mdoc(7) source code of a manual page obviously cannot issue less(1) commands. If it could, that would be a major security hole in mandoc(1), so massive that it would probably be the first time ever that a mandoc bug would have to be fixed by an OpenBSD erratum. Or would that be a bug in less(1)? Likely, but probably an erratum either way. To go on, for security reasons, the OpenBSD version of less(1) does not support escaping to a shell. If you press the "exclamation mark" key in OpenBSD less(1), it just beeps and does nothing. Even on Linux, your advice does not work: $ uname -a Linux login-1 4.19.0-13-amd64 #1 SMP Debian 4.19.160-2 (2020-11-28) x86_64 GNU/Linux $ man man [...] [ optionally hit the space bar here ] [ now type !.ls as you suggested and hit RETURN ] /bin/sh: 1: .ls: not found !done (press RETURN) [ press the RETURN KEY] [...] Manual page man(1) line 80 (press h for help or q to quit) [ now type !ls (without the dot) and hit RETURN ] [ it now displays a list of my files, then ] !done (press RETURN) [ press the RETURN KEY] [...] Manual page man(1) line 80 (press h for help or q to quit) Of course, even without your "period" (no idea where you got that from), it does not display anything "inside the manual page" but switches back and forth between either displaying the manual page or displaying the result of the shell command. Please guys, when you provide advice to others on our mailing lists, you should at least bother to test your own advice before posting. Yours, Ingo
Re: Is there a way to display the block of another man page inside a man page
On 02/05/22 01:46 Tom Smyth wrote: > Hello, > while documenting nsh and its features, > I wanted to display the command switches of telnet command inside the > manual page for nsh, Within more/less you can get a shell by typing: |.command [pipe + period + command] That way you can nest as many manpages as you like in a single terminal. tilo
Re: Is there a way to display the block of another man page inside a man page
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 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.
Re: Is there a way to display the block of another man page inside a man page
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
Is there a way to display the block of another man page inside a man page
Hello, while documenting nsh and its features, I wanted to display the command switches of telnet command inside the manual page for nsh, 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 .Ic telnet .Op -a .Op -b host-alias .Op -l user-name .Ar host-name .Op Ar port .Pp Open a telnet client session to the remote host host-name. 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 .Xr telnet 1 man page for a comprehensive list of telnet command options. .Bd -literal -offset indent nsh(p)/!man telnet .Ed any thoughts / advice welcome -- Kindest regards, Tom Smyth.
