Discussion about switching the default manpage viewer in openSUSE

Discussion about switching the default manpage viewer in openSUSE

[Matěj Cepl]

[-- Attachment #1.1.1: Type: text/plain, Size: 818 bytes --]

Hello,

I am a maintainer of mandoc for openSUSE (and SLE), and I started
a discussion about switch of the default manpage viewer yesterday
[1]. It was on Saturday, so I have so far just a few replies, but
some of them are interesting. If anybody here who is much more
knowledgeable about mandoc than this overworked Python maintainer
could chime in, it would be helpful. Or you can post your reply
to this thread and I will forward it to the openSUSE list as
well.

Best,

Matěj

[1] https://lists.opensuse.org/archives/list/factory@lists.opensuse.org/thread/2JONCA47J7WK3Z3MXS7A5MGFKTD72T4X/
-- 
http://matej.ceplovi.cz/blog/, @mcepl@en.osm.town
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
If in desperation, read the documentation!
    -- Brian D. Ripley, on R-help list

[-- Attachment #1.2: E09FEF25D96484AC.asc --]
[-- Type: application/pgp-keys, Size: 3102 bytes --]

-----BEGIN PGP PUBLIC KEY BLOCK-----

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
wwCdEnRlCGlvnO78R0FgKXlt3RyzGuE=
=sxoW
-----END PGP PUBLIC KEY BLOCK-----

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 216 bytes --]

Re: Discussion about switching the default manpage viewer in openSUSE

[Ingo Schwarze]

Hello Matej,

Matej Cepl wrote on Sun, Apr 06, 2025 at 02:42:52PM +0200:

> I am a maintainer of mandoc for openSUSE (and SLE),

Yes, i'm aware of that, thank you for your good work in that area.

> and I started a discussion about switch of the default manpage viewer
> yesterday [1].

That is interesting, thanks for the heads-up.

Note that while it is possible to switch from the man+groff combo
to mandoc only in one step (and some operating systems have done
just that), that actually amounts to doing two steps in one leap.

The first step is to keep the manual page viewer (for example, man-db)
unchanged and to only switch the formatter from groff to mandoc.
For that step, compatibility concerns are usually rather small
because "mandoc -T ascii" and "mandoc -T utf8" aim for detailed
output compatibility with groff.  In this context, the fact that
"mandoc -T html" output is vastly superior to groff and
"mandoc -T pdf" output is vastly inferior to groff is usually
not very relevant, but interesting to know anyway.

The second step is switching the manual page viewer from man-db
to mandoc.  That is typically more controversial because mandoc
does *not* aim for compatibility with man-db.

A few examples do exist where where features have been added to mandoc
because they have proven useful in man-db (for example, the -l option).
But most features of man-db are clearly not desired in mandoc.

I claim that the manual page searching and viewing functionality
of mandoc is vastly superior to man-db, among other aspects
due to the apropos(1) and "mandoc -O tag=" functionality.
But compatibility is definitely not a goal.  Any feature you want
in mandoc has to be argued individually, "that's what man-db does"
may help a tiny bit in cases of doubt, but will not help very much
in general.

> It was on Saturday, so I have so far just a few replies, but
> some of them are interesting.

I agree.  Also, a number of well-known people have spoken up,
i read quite a few famous names in that thread.

> If anybody here who is much more
> knowledgeable about mandoc than this overworked Python maintainer
> could chime in, it would be helpful. Or you can post your reply
> to this thread and I will forward it to the openSUSE list as
> well.

I intend to read the thread (so far, i have only read parts),
add entries to the mandoc TODO file as appropriate, and ask
for clarification as needed.

I should probably post a short message to that thread to show my
appreciation for taking the topic into consideration and for
providing lots of useful feedback, and to indicate that i'm generally
willing to help, even though i can hardly commit to doing any
specific amount of work.  I sometimes do consulting work when
things need to be sped up, but i'm not sure this would be appropriate
in this area.

Since the thread is already long, i'm a bit hesitant to try and
answer every point in the thread, among other reasons to prevent
the conversation in the thread from spiralling out of control.
So if you are OK with that, i would prefer to work through the thread
and send my comments to you, because i suspect you are more familiar
with the working culture at SUSE and can more effectively communicate
in that setting.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Discussion about switching the default manpage viewer in openSUSE

[Steffen Nurpmeso]

Ingo Schwarze wrote in
 <Z_VWXzQNCmD1-wNd@isnote.usta.de>:
 |Hello Matej,
 |
 |Matej Cepl wrote on Sun, Apr 06, 2025 at 02:42:52PM +0200:
 |
 |> I am a maintainer of mandoc for openSUSE (and SLE),
 |
 |Yes, i'm aware of that, thank you for your good work in that area.
 |
 |> and I started a discussion about switch of the default manpage viewer
 |> yesterday [1].
 |
 |That is interesting, thanks for the heads-up.
 |
 |Note that while it is possible to switch from the man+groff combo
 |to mandoc only in one step (and some operating systems have done
 |just that), that actually amounts to doing two steps in one leap.
 |
 |The first step is to keep the manual page viewer (for example, man-db)
 |unchanged and to only switch the formatter from groff to mandoc.
 |For that step, compatibility concerns are usually rather small
 |because "mandoc -T ascii" and "mandoc -T utf8" aim for detailed
 |output compatibility with groff.  In this context, the fact that
 |"mandoc -T html" output is vastly superior to groff and
 |"mandoc -T pdf" output is vastly inferior to groff is usually
 |not very relevant, but interesting to know anyway.
 |
 |The second step is switching the manual page viewer from man-db
 |to mandoc.  That is typically more controversial because mandoc
 |does *not* aim for compatibility with man-db.
 |
 |A few examples do exist where where features have been added to mandoc
 |because they have proven useful in man-db (for example, the -l option).
 |But most features of man-db are clearly not desired in mandoc.
 |
 |I claim that the manual page searching and viewing functionality
 |of mandoc is vastly superior to man-db, among other aspects
 |due to the apropos(1) and "mandoc -O tag=" functionality.
 |But compatibility is definitely not a goal.  Any feature you want
 |in mandoc has to be argued individually, "that's what man-db does"
 |may help a tiny bit in cases of doubt, but will not help very much
 |in general.
 |
 |> It was on Saturday, so I have so far just a few replies, but
 |> some of them are interesting.
 |
 |I agree.  Also, a number of well-known people have spoken up,
 |i read quite a few famous names in that thread.

I am neither famous nor have i read the thread (your reply misses
the url), but new groff supports OSC 8 creation in the text mode,
and newer less(1) (except for the fork used by OpenBSD i think (i
track it via github .. last commit there was in 2021) supports OSC
8 URL browsing, which in combination gives you are fantastic
manual browsing experience.  (Though my mdoc extender did not made
it upstream, until now, its first and main and largest product
made it into the less unit test, hahaha!)  Ie

  ^O^N  ^On         *  Search forward for (N-th) OSC8 hyperlink.
  ^O^P  ^Op         *  Search backward for (N-th) OSC8 hyperlink.
  ^O^L  ^Ol            Jump to the currently selected OSC8 hyperlink.
..
  ^O^O                 Open the currently selected OSC8 hyperlink.

No more need for HTML or any such!  It is so fine.
I am still hoping that all the manual converters detect this
fantastic feature, then UNIX manuals become my hero.

 |> If anybody here who is much more
 |> knowledgeable about mandoc than this overworked Python maintainer
 |> could chime in, it would be helpful. Or you can post your reply
 |> to this thread and I will forward it to the openSUSE list as
 |> well.
 |
 |I intend to read the thread (so far, i have only read parts),
 |add entries to the mandoc TODO file as appropriate, and ask
 |for clarification as needed.
 |
 |I should probably post a short message to that thread to show my
 |appreciation for taking the topic into consideration and for
 |providing lots of useful feedback, and to indicate that i'm generally
 |willing to help, even though i can hardly commit to doing any
 |specific amount of work.  I sometimes do consulting work when
 |things need to be sped up, but i'm not sure this would be appropriate
 |in this area.
 |
 |Since the thread is already long, i'm a bit hesitant to try and
 |answer every point in the thread, among other reasons to prevent
 |the conversation in the thread from spiralling out of control.
 |So if you are OK with that, i would prefer to work through the thread
 |and send my comments to you, because i suspect you are more familiar
 |with the working culture at SUSE and can more effectively communicate
 |in that setting.
 --End of <Z_VWXzQNCmD1-wNd@isnote.usta.de>

--steffen
|
|Der Kragenbaer,                The moon bear,
|der holt sich munter           he cheerfully and one by one
|einen nach dem anderen runter  wa.ks himself off
|(By Robert Gernhardt)
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Discussion about switching the default manpage viewer in openSUSE

[Ingo Schwarze]

Hello Matej,

here are some specific details regarding the thread on the factory
at openSuSE mailing list.  Feel free to use all this however you see fit,
in changed or unchanged form.

I'm not replying to every single point in the discussion.
If i do not address a specific point, the reason may be:
 * Somebody already answered the point.
 * I did not understand the point.
 * I simply overlooked the point.

If you desire my feedback on any specific point, please simply ask
here on the mandoc list.

Some of the answers below state that i do not want certain features.
Experience shows that even in such cases, it is sometimes possible
to find a compromise if it is better explained why a certain
feature is needed.

So let's go ahead with some questions that stood out to me:


> David C Rankin:
> If it ain't broke, why fix it?

Apart from what you said, the main advantages of mandoc as a formatter are:

 1) simplicity and smaller size of the code
 2) better error messages in -T lint mode
    (more relevant, fewer false positives)
 3) free software in the sense of 100% avoiding the non-free GPL license
    (item 3 is likely not relevant for Linux)
 4) vastly superior HTML output
 5) mandoc is faster, typically a factor 3 for mdoc(7),
    and a smaller speedup for man(7)
    (mostly relevant for very large pages on slow hardware)

The main advantages of mandoc as a viewer are:

 1) vastly superior apropos(1) including semantic searching
    (less relevant in a Linux environment because while extremely
     powerful with mdoc(7) pages, it is much less powerful
     with man(7) pages, and most pages in Linux systems are man(7))
 2) tagging support with "-O tag" and with less ":t"
    (less relevant in a Linux environment for the same reason)
 3) the user interface is much less bloated than in man-db
    (though a less bloated interface may be perceived as a
     downside in Linux culture)

> Jan Engelhardt:
> mandoc on openSUSE ignores $COLUMNS and always renders to 80 columns.

That's intentional.

 1) We hate configurability, we believe in sane defaults.
    Very wide text is hard to read, so more than 80 columns
    makes no sense to us.  If you want less than 80 columns,
    you can simply use a narrower terminal window, mandoc
    respects TIOCGWINSZ.
 2) We hate environment variables even more than command line
    options because they make behaviour inconsistent in subtle
    and non-obvious ways.  So while a "-O width=" option is provided
    and respected even with absurdly large or small values
    like -O width=200 or -O width=20, ignoring COLUMNS is a
    feature, not a bug.

> Jan Engelhardt:
> With mandoc, the pager shows "/tmp/man.XXXXOrG1jk lines 1-28/2239 1%"
> in the bottom line, rather than "Manual page ls(1p) line 1
> (press h for help or q to quit)".

I added the following TODO entry:

- When calling less(1), specify -P to print "name(sec) lines ..."
  in the bottom line instead of "/tmp/man..." 
  Jan Engelhardt (SuSE) via Matej Cepl 06 Apr 2025 14:42:52 +0200
  loc *  exist *  algo *  size *  imp **

The following aspects feel undesirable:

 * Putting "Manual page " before the page name is pointless,
   the user knows that they typed man(1).
 * Showing the first and last line numbers displayed and the total
   number of lines being paged is more useful than showing only
   a single line number.
 * Putting "(press h for help or q to quit)" is totally pointless
   and insulting the user.  The user did not ask for the manual
   page for less(1), but for some other manual page.

> Jan Engelhardt:
> In mandoc, `man awk ls` does not bring up the ls manpage
> at any point, despite mandoc's man(1) documentation saying
> that multiple names can be presented.

Cannot reproduce, works for me on OpenBSD-current.

Note that mandoc(1) displays the concatenation of both manial pages
in a single less(1) buffer, such that you can search with commands
like / and :t across both manual pages, forwards and backwards.

By contrast, man-db displays both manual pages separately and
requires the user to manually switch from one to the other, which
is less useful.

> Jan Engelhardt:
> What manual page do you want?

I very strongly hate that misfeature.
That definitely won't be im|plemented.

A patch to mandoc exists that prints a one-line indication above
the manual page in this case.  However, that patch was vetoed by
other OpenBSD developers because it was considered too chatty,
so it did not go in.

> Jan Engelhardt:
> mandoc does not know the \m[blue] syntax

It does support the syntax, in the sense of correctly parsing it.
It is intentional that this escape sequnece has no effect.
The mandoc output does not use ANSI escape sequences (for
security reasons), so it cannot produce colored output.
Also, i consider colored terminal output highly undesirable,
because it is very bad for readability.

The roff(7) manual says:

  \m[name]
    Set glyph drawing color (groff extension); ignored by mandoc(1).
    For short names, there are variants \mc and \m(cc.

I'm not willing to look at mkv files and try to guess what the
person posting the mkv file means.  I think a bug report or
feature request is better served by explaining the desired
behaviour verbally.

> Matej Cepl
> Detected 3 file conflicts:
> File /usr/bin/soelim
> File /usr/share/man/man1/soelim.1.gz
> File /usr/share/man/man7/roff.7.gz

In configure.local, set BINM_SOELIM and MANM_ROFF
such that the conflict goes away.
See the file configure.local.example for details.

I have no opinion regarding the SUSE "alternatives" mechanisms,
but i do try to provide compile-time configuration options to
avoid conflicts with groff on systems that want to avoid such
conflicts.

> H.Merijn Brand
> man -k compiler

That certainly works with mandoc.  It's actually one of the areas
where mandoc is much more powerful than man-db.  Then again,
i'm not sure whether the poster thinks of any particular feature
of man -k.  His remark is not very specific.

> H.Merijn Brand
> mandoc --help

The chance of mandoc ever supporting *any* long option is exactly
zero.  POSIX specifically forbids all long options, and man(1)
is a POSIX utility.  While mandoc supports many extensions to the
standard, adding anything that violates the standard is a non-starter.

On top of that, i believe adding any option merely for the purpose
of printing help text or version information is a bad idea.
For help text, use man(1).  For version infornation, use the
package manager provided by the operating system.

In general, i understand less of half that H.Merijn Brand
is saying, so i have likely missed some points in his remarks.

If you have any additional questions or suggestions, please ask.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv