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

grahamperrin

Son of Beastie

Reaction score: 1,010
Messages: 3,422

Hint

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

Post #11 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 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:
OP
grahamperrin

grahamperrin

Son of Beastie

Reaction score: 1,010
Messages: 3,422

rm

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:

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:~ %
 
OP
grahamperrin

grahamperrin

Son of Beastie

Reaction score: 1,010
Messages: 3,422

Spun off from:




… a distinction between man and pman

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




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.

… 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.



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.

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.

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

grahamperrin

Son of Beastie

Reaction score: 1,010
Messages: 3,422

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

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:

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:
OP
grahamperrin

grahamperrin

Son of Beastie

Reaction score: 1,010
Messages: 3,422

RFD: disambiguating online manual page name collisions between different ports

From Pau Amma's request for discussion (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?
 
OP
grahamperrin

grahamperrin

Son of Beastie

Reaction score: 1,010
Messages: 3,422

Is the request for discussion (in its entirety, not just the quote) understandable?
 

drhowarddrfine

Son of Beastie

Reaction score: 2,490
Messages: 4,436

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

Son of Beastie

Reaction score: 869
Messages: 2,826

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.
 
OP
grahamperrin

grahamperrin

Son of Beastie

Reaction score: 1,010
Messages: 3,422

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@

Administrator
Staff member
Administrator
Moderator
Developer

Reaction score: 425
Messages: 1,022

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.
 
OP
grahamperrin

grahamperrin

Son of Beastie

Reaction score: 1,010
Messages: 3,422

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

… 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 𠄶…
 
Top