Coding for MAN and PMAN markup

Cath O'Deray

Cath O'Deray

 
Example A

<https://www.freebsd.org/cgi/man.cgi?query=beadm&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>
  • currently exists
  • [MAN=1]beadm[/MAN] – beadm(1) currently finds the FreeBSD 13.0-RELEASE and Ports page, should find nothing
  • [PMAN=1]beadm[/PMAN] – beadm(1) currently finds the FreeBSD 12.1-RELEASE and Ports page, should not find a page for an end of life release.
Example B

<https://www.freebsd.org/cgi/man.cgi?query=beadm&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>
  • currently exists
  • [MAN=8]beadm[/MAN] – beadm(8) currently finds the FreeBSD 13.0-RELEASE and Ports page, should find nothing
  • [PMAN=8]beadm[/PMAN] – beadm(8) finds nothing, should find a manual page.
Since PMAN is for manual pages for ports, I assume that MAN is intended to exclude pages for ports.

Example A is unusual, but good for now; the page might (properly) disappear after the bug below is fixed.

254466 – sysutils/beadm-devel section (1) and sysutils/beadm section (8) for the two manual pages for beadm; consequences

bugs.freebsd.org bugs.freebsd.org
 

Relation between MAN PMAN and its mappings​

It seems that the web page interface for FreeBSD man pages offers the following main three options:
  1. for FreeBSD base install (no ports included). URL example:
    https://www.freebsd.org/cgi/man.cgi?query=ls&manpath=freebsd-release
  2. for FreeBSD base install and ports. URL example:
    https://www.freebsd.org/cgi/man.cgi?query=ls&manpath=freebsd-release-ports
  3. for FreeBSD, for ports only. URL example:
    https://www.freebsd.org/cgi/man.cgi?query=rsync&manpath=freebsd-ports
It seems that not all those three options can be selected by BBC on the FreeBSD forum; available are:
  • [MAN]ls[/MAN] and [MAN=1]ls[/MAN]
  • [PMAN=1]rsync[/PMAN]
Having only two BBC options available, a working compromise seems:
  1. [MAN]ls[/MAN] and [MAN=1]ls[/MAN] mapped to the base-install and ports.
  2. [PMAN=1]rsync[/PMAN] mapped to ports.
As described in Formatting Guidelines and BBC-MAN, MAN is not precisely defined as to its intended targets but, it refers to manual pages in general terms, making the choice for #1 more likely. The current implementation on the FreeBSD forum is as described in #1. In the Formatting Guidelines and more officially in BBC-PMAN however, choice #2 suggests it should be mapped to ports only:
Create a link to a Ports Collection manual page.
Click to expand...

Problems​

BBC PMAN, for example [PMAN=1]rsync[/PMAN]—as in rsync(1)—is being mapped to the man page for the base install and ports, and is hard-coded to 12.1-RELEASE; URL:
https://www.freebsd.org/cgi/man.cgi...+and+Ports&arch=default&format=html&sektion=1

Proposed solution​

Taking [PMAN=1]rsync[/PMAN] as an example, BBC PMAN should be mapped to ports accompanying the highest_major-highest_minor-RELEASE that is being supported; at the moment that would be FreeBSD Ports 13.0 accompanying 13.0-RELEASE. Without a hard-coded reference to any specific X.Y-RELEASE and in line with BBC-PMAN, it seems that this can be achieved by mapping [PMAN=1]rsync[/PMAN] to ports only by generating for example the following URL:
https://www.freebsd.org/cgi/man.cgi?query=rsync&sektion=1&manpath=freebsd-ports

Currently, other extra options as part of the target URL (e.g. apropos and arch) are being generated as well. Specifically with regard to the BBC it seems that those are not relevant but, perhaps there are good reasons for those to be present.

Additional notes on mappings​

Given that only MAN and PMAN are available as BBC, another possibility would be to map MAN to man pages of the FreeBSD base install only and map PMAN to ports only. This would mean a mutual exclusive use of MAN & PMAN as to their intended targets.

This would have the advantage for the reader of a forum message that it is quickly clear if the man page in question (and its related command) is part of the base install and as a consequence should be available on the FreeBSD installation of the user. Or, alternatively, is in ports and may require the user to install it from ports, for example as a package.

The writer of a forum message on the other hand has to specifically select either MAN or PMAN.

Personally, I would welcome this mutual exclusive usage of MAN & PMAN for its intended targets; preferences may differ. There's also such a thing as backwards compatibility for all the written MAN references on this forum so far.

___
P.S. this thread seems somewhat intertwined with Coding for MAN and PMAN markup. However, there the issue seems mainly about the actual FreeBSD website of the man pages and about the dual existence of beadm(1) and beadm(8); those are outside the purview of the FreeBSD forum sec as I understand it.
 
Last edited:
Erichans said:

Proposed Solution​

[PMAN=1]rsync[/PMAN] should be mapped to the highest_major-highest_minor-RELEASE that is being supported; at the moment that would be 13.0-RELEASE. It seems that this can be achieved—without a hard-coded reference to any specific X.Y-RELEASE—by:
[PMAN=1]rsync[/PMAN] mapping only to ports, URL:
https://www.freebsd.org/cgi/man.cgi?query=rsync&sektion=1&manpath=freebsd-ports

Currently, other extra URL options (e.g. apropos and arch) are being generated as well. Specifically with regard to the BBC it seems that those are not relevant but, perhaps there are good reasons for those to be present.
Click to expand...
I like your proposal, but I usually don't know off-hand what is in base and what is not. Maybe have PMAN mapped to base + ports for ignorant fools like me?
 
Jose said:
I like your proposal, but I usually don't know off-hand what is in base and what is not. Maybe have PMAN mapped to base + ports for ignorant fools like me?
Click to expand...
Apart from the issue of backwards compatibility, the (extra) burden is there.

Currently, MAN maps to base + ports (I suspect PMAN is used far less). Therefore, MAN can be used indiscriminately, even by an "ignorant fool". That means the writer can use the general MAN in a catch all manner and the readers (a.o. all the newbies) have to sort things out. For example after clicking on rsync(1) by then selecting the appropriate pull-down option on the web page for the man pages: probably trying FreeBSD 13.0-RELEASE first and—agonizingly—not forgetting to set the pull-down for section to all sections to prepare for all eventualities ;). Because no resulting match, after that, by deduction, concluding that rsync(1) must be in ports. Alternatively, by explicitly selecting from the pull-down menu FreeBSD Ports 13.0; quite a few entries down stream by the way ...

Putting more responsibility towards the writer means, in the most extreme situation, the mutual exclusive use of MAN & PMAN.

One has to choose an option either geared more towards the sole writer of a message or the many readers of that message; you, as I, will be in either role at one time or another ;)
 
Last edited:
grahamperrin said:
More specifically, it should find the content that's here:

<https://www.freebsd.org/cgi/man.cgi?query=beadm&manpath=Ports&sektion=8>
Click to expand...
At the moment, both beadm(1) and beadm(8) exist: that should be fixed at the FreeBSD website page of the man pages, as per your PR. (At the time of 12.1-RELEASE only beadm(1) existed.) According to PMAN this BBC should point to the relevant ports man pages (of ports only IMO); currently it does not.

I don't know the code how the generated URL for the FreeBSD man pages is parsed but, it seems that of the manpath query option, the value of that option should be different from your last URL reference (i.e. manpath=Ports). For the ports man pages only manpath=freebsd-ports seems to work. For [PMAN=8]beadm[/PMAN], it should work like this: beadm(8) with a full URL as an example:
https://www.freebsd.org/cgi/man.cgi?query=beadm&sektion=8&manpath=freebsd-ports&format=html

For the FreeBSD Forum website part of it, I've made a seperate thread
 
I am not sure if I entirely understood your request, but I made a simple change to the pman bbcode, let me know if that is what you requested.
 
Man bbcode currently generates links to man pages of freebsd-base and ports, hence false.
 
OK, thanks. If there's no intention for MAN to exclude ports – as can be done with the CGI – then we might be done here.

Test:
  1. rm(1) with MAN not excluding ports produces <https://www.freebsd.org/cgi/man.cgi?query=rm&sektion=1&manpath=freebsd-release-ports> (2018-11-10 for FreeBSD 13.0)
  2. rm(1) in FreeBSD condensed URL <https://www.freebsd.org/cgi/man.cgi?query=rm&sektion=1&manpath=FreeBSD> (again, 2018-11-10 for FreeBSD 13.0)
  3. rm(1) with PMAN produces <https://www.freebsd.org/cgi/man.cgi?query=rm&apropos=0&sektion=1&manpath=freebsd-ports&format=html> – an extraordinarily short page (undated, port origin not stated – these things can't be fixed on the XenForo side).
Extraordinary, but proper, so I think I'll draw a line. Solved. Thanks, everyone.


danger@ if you'd like to ice the cake, maybe add = for MAN (as you have for PMAN). More of a hint that the writer can/should add a section number before posting.


Spin-off (not feedback about the Forums):

forums.freebsd.org

Manual pages online: RFD – share your thoughts on changes to design

Hint The first two or three posts here might be mind-bending. Post #10 puts things in context. beadm … both beadm(1) and beadm(8) exist: that should be fixed at the FreeBSD website …? FreeBSD bug 254466 – sysutils/beadm-devel section (1) and sysutils/beadm section (8) for the two manual...
forums.freebsd.org forums.freebsd.org
 
Reading the few previous comments on this thread - PMAN seems to make very little sense, compared to MAN. We have [MAN=8]poudriere[/MAN] for what's clearly a port: ports-mgmt/poudriere. Section 6 of the manpages is Games, Section 8 is Maintenance Commands, and Section n is 'New Commands' (Gleaned from https://www.freebsd.org/cgi/man.cgi). Why not just stuff all the PMAN content into Section 'n' (or even Section 10/11/whatever)?
 
5xmcfs.jpg
 
I guess what I'm trying to say is:
--
The base system just uses man for all manual pages anyway, so why do the Forums make a distinction between man and pman? I mean, try running pman poudriere in Konsole. You'll get an error, because there's no separate pman utility.
--
And if documentation is not in the manpages, we just share links, no special markup needed.
--
I would think that does qualify as Feedback about Forums.
 
grahamperrin said:
Distinctive menu options, preselected, as a result:

View attachment 12302

View attachment 12301

Also very useful, although it's not a result of any predefined markup here:

View attachment 12300
Click to expand...
These 3 options look kind of redundant. Another option that I found in that same drop-down menu is FreeBSD 13-stable. To be consistent with the markup scheme employed by the Forums here, shouldn't pman point to the FreeBSD Ports NN.N (like FreeBSD Ports 13.0)?
--
FWIW, zlib manpage is present in all 4 options. The version for FreeBSD Ports 13.0 does in fact look different than zlib(3) (which points to FreeBSD 13.0-RELEASE and Ports). The manpages' DESCRIPTION section looks very different.
--
We already have FreeBSD NN.X-RELEASE and Ports, this is where manpages go for both base system. Some ports also make use of that same place to install their own manpages. So why make the markup more complicated with PMAN?
--
Just for the heck of it, I'm gonna play with PMAN markup: [PMAN=3]zlib[/PMAN] = zlib(3)

Edit: Yeah, n was the problem for you, grahamperrin . Should be 3.
 
You must log in or register to reply here.
Back
Top