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

Cath O'Deray

Cath O'Deray

 
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 …?
Click to expand...

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:
 
Last edited:
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 …
Click to expand...

<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
Click to expand...

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:

Code: 
% 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.

Code: 
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:~ %
 
Spun off from:

forums.freebsd.org

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 forums.freebsd.org


astyle said:
… a distinction between man and pman …
Click to expand...

Distinctive menu options, preselected, as a result:

1640329994005.png


1640330024329.png


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

1640330053253.png



grahamperrin said:
The page for zlib(n) from lang/tcl86/ must not be confused with the page for zlib(3) in FreeBSD
Click to expand...

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, grahamperrin . Should be 3.
Click to expand...

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.
Click to expand...

Code: 
% 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 …
Click to expand...

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.
 
Last edited:
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:

Hints

FreeBSD+12.3-RELEASE within the URL above results in pre-selection of a specific menu option:
Click to expand...

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

1640330367251.png


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:
No customisation within the URL, however the result is automatically customised and there's greater draw of attention to essential customisation:

1640330970034.png

Retrospective

2020, two points in time:


  • 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.
 
Last edited:
Another comparison

Representation of manual pages in OpenZFS documentation.

<{link removed}>, for example:

1640332286542.png

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.
 
Last edited:
RFD: disambiguating online manual page name collisions between different ports

From {link removed} (2021-12-02):

…

Suggested design:

In addition to the current restriction fields (section, FreeBSD base version, and architecture), have a category/port field or field group. If left unfilled or with the default value, this would search across whatever non-conflicting subset of all port manual pages is currently accessible, for compatibility. If the user selects a given port, only manual pages for that port are searched.

What do others think?
Click to expand...
 
Last edited:
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.
 
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.
 
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.
 
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.
 
Thanks, certainly I'll feed back using one or both of those methods.

danger@ said:
… raise this issue on docs@ …
Click to expand...

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 ?…
 
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.
Click to expand...
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.
 
You must log in or register to reply here.
Back
Top