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



## grahamperrin@ (Dec 5, 2021)

Hint

The first two or three posts here might be mind-bending.

Post #10 puts things in context.


beadm



Erichans said:


> … 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 pages for beadm; consequences

closed
works as intended – Wolfram Schneider's comment 13 was key to understanding, after which I edited the summary line of the bug.
Effective:

beadm(1) (2012-09-04) relates to sysutils/beadm-devel/
beadm(8) (2020-12-01) relates to sysutils/beadm/


----------



## grahamperrin@ (Dec 5, 2021)

rm



grahamperrin said:


> rm(1) … <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 …



<https://www.freebsd.org/cgi/man.cgi?query=rm&sektion=1&manpath=FreeBSD+Ports+13.0#SOURCE> shows this, somewhat ambiguous:

/src/cmd/rm.c

At <https://www.freebsd.org/cgi/man.cgi?query=rm&sektion=1&manpath=FreeBSD+Ports+8.2#SOURCE> for _FreeBSD Ports 8.2_ we have less ambiguous /usr/local/plan9/src/cmd/rm.c.

SEE ALSO <https://www.freebsd.org/cgi/man.cgi?query=remove&sektion=3&apropos=0&manpath=FreeBSD+Ports+8.2> for _FreeBSD *Ports* 8.2_ remove(3) is not found, lazily removing `+8.2` from the tail of the URL results in ☑ a *non*-ports manual page.

rm(1) for _FreeBSD Ports 8.3_ was:



> npm-rm -- Remove a package



rm(1) for _FreeBSD Ports 8.4_ was, again, from /usr/local/plan9/src/cmd/rm.c.

rm(1) for _FreeBSD Ports 11.2_ was a longer page, unrelated to npm and no mention of plan9.

rm(1) for _FreeBSD Ports 12.1_ a shorter page, the source is different: /src/cmd/rm.c.

For _FreeBSD Ports 12.2_ a longer page; for _FreeBSD Ports 13.0_ a shorter page; and so on.

For the recent shorter page, less ambiguously:


```
% pkg provides /src/cmd/rm.c
Name    : plan9port-20200816
Desc    : Plan 9 from User Space
Repo    : FreeBSD
Filename: usr/local/plan9/src/cmd/rm.c
%
```

The longer page for e.g. _FreeBSD Ports 12.2_ remains a mystery. Not a problem, just a curiosity.


```
grahamperrin@freebsd:~ % uname -KU
1202000 1202000
grahamperrin@freebsd:~ % pkg -vv | grep url
    url             : "pkg+http://pkg.FreeBSD.org/FreeBSD:12:amd64/latest",
grahamperrin@freebsd:~ % pkg provides man1/rm.1.gz
Name    : linux_base-c7-7.9.2009
Desc    : Base set of packages needed in Linux mode (Linux CentOS 7.9.2009)
Repo    : FreeBSD
Filename: compat/linux/usr/share/man/man1/rm.1.gz

Name    : ja-man-doc-5.4.20050911_3
Desc    : Japanese translation of FreeBSD manual pages
Repo    : FreeBSD
Filename: usr/local/man/ja/man1/rm.1.gz

Name    : bitkeeper-7.3.3_6
Desc    : Scalable Distributed Source Management System
Repo    : FreeBSD
Filename: usr/local/bitkeeper/man/man1/rm.1.gz
grahamperrin@freebsd:~ %
```


----------



## grahamperrin@ (Dec 20, 2021)

Spun off from:









						Coding for MAN and PMAN markup
					

Example A    currently exists beadm – beadm currently finds the FreeBSD 13.0-RELEASE and Ports page, should find nothing beadm – beadm currently finds the FreeBSD 12.1-RELEASE and Ports page, should not find a page for an end of life release.  Example B    currently exists beadm – beadm...




					forums.freebsd.org
				







astyle said:


> … a distinction between `man` and `pman` …



Distinctive menu options, preselected, as a result:










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








grahamperrin said:


> The page for zlib(n) from lang/tcl86/ must not be confused with the page for zlib(3) in FreeBSD



The ports-related page to which I linked is headed _Tcl Built-In Commands_.



astyle said:


> … play with PMAN markup: zlib(3) = zlib(3)
> 
> Edit: Yeah, *n* was the problem for you, _*[FONT=monospace]grahamperrin[/FONT]*_ . Should be 3.



The ports-related page to which you linked is headed _Erlang Module Definition_, its content is entirely different. Not a problem with FreeBSD Forums.




astyle said:


> So, if I get you correctly, I linked to the Erlang module, while grahamperrin linked to the TCL command. And yet, both versions seem to be called up with the exact same `man zlib` (or `man 3 zlib`) command.
> 
> `PMAN` is making even less sense to me at this point.  If I want to quote programming language documentation (as opposed to manpages for userland utilities in the base FreeBSD install), I would just avoid using the [MAN][/MAN] markup altogether.




```
% apropos zlib | tail -n 2
zlib(3) - compression/decompression library
zlib.tcl86, zlib(n) - compression and decompression operations
%
```

– two different pages. YMMV, depending on what's _installed_.



astyle said:


> … `PMAN` is making even less sense to me …



For HTML representations at <https://www.freebsd.org/cgi/man.cgi> to make more sense, there'll be something at <https://bugs.freebsd.org/> in due course.


----------



## grahamperrin@ (Dec 24, 2021)

Orientation within representation of manual pages at www.freebsd.org



grahamperrin said:


> There's a manual page, *wsp(4)* …
> 
> 
> … for that version of the operating system:
> ...



Compare the screenshot at <https://forums.freebsd.org/posts/547974> with this:




The different content for two manual pages with the same name:

wsp(4)
wsp(4)
– goes some way to demonstrating the value of a web page design that will *draw attention to the relevant menu option*.

IMHO the current design lacks some of the draw that's required.

Comparisons

Web page design at Mozilla. An example:

<https://support.mozilla.org/en-US/kb/keyboard-shortcuts-perform-firefox-tasks-quickly>
No customisation within the URL, however the result is automatically customised *and* there's greater draw of attention to *essential customisation*:



Retrospective

2020, two points in time:

14th April | 16th April​

14th April was the final capture of inferior web design, with which the customisation was obscured (the detected version of Firefox, and the detected operating system, were hidden within the _Editing Tools_ menu)
on 16th April we have the superior design, which *draws attention* to the version and OS.


----------



## grahamperrin@ (Dec 24, 2021)

Another comparison

Representation of manual pages in OpenZFS documentation.

<https://openzfs.github.io/openzfs-docs/man/7/zfsconcepts.7.html>, for example:



Nice, however I don't imagine the design working so well for a project such as FreeBSD, where we have so many man pages for the base system alone.


----------



## grahamperrin@ (Dec 25, 2021)

RFD: disambiguating online manual page name collisions between different ports

From Pau Amma's request for discussion (2021-12-02): 



> …
> 
> Suggested design:
> 
> ...


----------



## drhowarddrfine (Dec 25, 2021)

I don't understand what the purpose of this thread is.


----------



## drhowarddrfine (Dec 26, 2021)

I see there is a request for discussion on that other page but is that what you are asking for here? Or are you asking us to go there and discuss it? It's not clear why you are posting all that here.


----------



## Alain De Vos (Dec 26, 2021)

It's off-topic. Maybe it's a riddle. Or spam . Or an err. Or not so good way to attract attention.
Sometimes i have difficulty in following what was the message. But that must be me.


----------



## grahamperrin@ (Dec 26, 2021)

If I recall correctly, this topic was originally specific to manual pages for beadm. When I broadened its scope, to include pages for rm, and so on, I *edited the title*, made it less specific: 

Manual pages​
Post #3 was, as mentioned, spun off from another topic. (The other is for feedback about FreeBSD Forums.)

Generally

There is, I think, *room for improvement* to FreeBSD's online representations of man pages. 

Posts *#4* and *#5* were comparisons; to *provoke thought about how things might be improved*. 

I did not realise that Pau Amma had parallel thoughts, about improvements, until some weeks after my thoughts began forming. 


Parts of posts #1, #2 and #3 are potentially mind-bending, so *if you have an interest in sharing thoughts about manual pages*, maybe ignore those three posts.


----------



## danger@ (Dec 29, 2021)

as I understand this thread I suggest you report this upstream through freebsd bugzilla or raise this issue on docs@ mailing list as this is beyond the scope of this forum.


----------



## grahamperrin@ (Dec 29, 2021)

Thanks, certainly I'll feed back using one or both of those methods. 



danger@ said:


> … raise this issue on docs@ …



Already raised there, around four weeks ago (2nd December), by someone else. No response there, and I wasn't aware of the RFD until 25th December.

I imagined that one of the many members of FreeBSD Forums would take an interest in design changes, and might prefer to share thoughts (discuss) here in the forums. 

I'll edit the title. This topic was not originally a request for discussion (RFD), but that's what it became 𠄶…


----------



## grahamperrin@ (Jan 5, 2022)

Erichans said:


> a namespace where the port name is included,



That's much like what I had in mind, Pau Amma's thoughts seem to be along the same lines.


----------



## grahamperrin@ (May 18, 2022)

FreeBSD bug 264054 – Man page display on web site is confusing


----------



## getopt (May 18, 2022)

danger@ said:


> as I understand this thread I suggest you report this upstream through freebsd bugzilla or raise this issue on docs@ mailing list as this is beyond the scope of this forum.


grahamperrin

danger@ told you where to work on this. Why do you still use the forums for this?
Your work may be valuable, which honestly I cannot evaluate, but high frequency posting here in the forums may be percepted as spamming, as the forums are not the right place for that.

Maybe more clear words need to be spoken as some more threads are affected by this kind of "usage" by grahamperrin.


----------

