Re: Proposal to remove catman(8)

[Robert Elz <kre%munnari.OZ.AU@localhost>]

    Date:        Tue, 10 Nov 2020 23:31:12 +0100
    From:        Kamil Rytarowski <kamil%netbsd.org@localhost>
    Message-ID:  <21b45496-5aec-ac45-b9d7-e7680b7d883b%netbsd.org@localhost>

  | .0 is since ever. I couldn't grep any other suffixes in projects, thus
  | one BSD4.3 Reno snapshot has a bunch of files with custom endings.
  | Assuming that this knowledge is from Reno times, it was not refreshed
  | since 1990.

No, I just have a lousy memory.   Always have had.   I don't bother
trying to remember details like that, I either work it out (trial
and error, or reading manuals or sources) when it is important, or
just guess at what seems most likely when it doesn't (like here).
In a few weeks or so I will have forgotten the .0 convention again,
it simply isn't important enough to try to remember.

  | I inform you that you were happy to render your cat page with mandoc(1).

That could easily have been what happened - there were no macro calls
left in it of course, so all that happens is reflowing already formatted
text (not much change) and blank line paragraph breaks (not much change).
So it looked close enough to working ... (you might remember that I mentioned
that I'd need to look at -T args for groff to find the right one, as even
I could see it wasn't perfect).

  | groff is not compatible.

Even in compat mode?   If you want, send me your source file (or enough
of it - but starting from the beginning, you can edit out anything that
you don't want to distribute which is just text, but leave all the macro
calls and enough text to actually be formatted) and I'll take a look.

If you can point out (if it isn't obvious, like an error message) what
groff does incorrectly (or doesn't do at all) that would help.

  | I am surprised that the proposal to remove MK${FOO} is read as removal
  | of the Makefile conditionals and keep ${FOO} in the base.

Why?   That's a perfectly rational thing to do.   You're probably
surprised as your motivation for doing it isn't what most people
thought it was - we thought that you were removing it because it
(MKCATPAGES) isn't ever used in practice, and because the implementation
had been buggy.   That's the way your initial message read.

The bit about MANWIDTH I considered just random rambling about things
that may happen - there wasn't even any context about what that meant
to explain how that was in any way related to cat pages.

  | With that
  | bizarre interpretation the whole proposal renders into useless idea.

Not at all, it simplifies the build infrastructure, potentially allows
mandoc to no longer be required as a build tool, and reduces the workload
(and probably more importantly) build failures that can happen when the
set lists weren't properly updated to include the cat pages.

  | I would be very surprised to interpret that e.g. proposal to remove
  | MKX11 would not mean to remove X11 from the base but to enable it by
  | default.

That isn't the same thing, but "enable looking to see if it has been installed
and use it if it has" would be an entirely reasonable thing to do.

But a better example would be once the sanitisers have finally stopped
finding any new bugs in our code, and have been doing nothing useful for
a few years.   At that point someone might propose deleting the sanitiser
builds from the released sets (from the build infrastructure).   But
surely we should keep them, not just delete everything that isn't used
in release builds?   That is, give users the option to use them if
they have some reason for doing so.

There are two issues - one is what we include in the releases, and for
that no-one (I'm aware of) is arguing that the cat pages should be there.

The other is what we allow the users to do, and what we prevent (or at
least very strongly discourage) by deleting all support.   Sure one could
put catman(8) in pkgsrc, that wouldn't be too much of a problem, but the
support in man(1) and man.conf for reading the cat pages can't so easily
just be moved away.   If users want to run catman (or populate the catN
directories some other way) how does that harm you?   Why are you so
compelled to make everyone else act the way you want?   If cat pages are
incompatible with some other feature (say MANWIDTH) then the user concerned
gets to decide which one is more important.  Or possibly write some code
and make both work together (in ways that maybe you won't imagine, or
write code for, because you don't see the need - and that's fine).

kre

ps: since you were looking for man pages that mandoc can't handle, then
aside for the groff man pages (no big surprise that groff expects to
format its own man pages, even other *roff's won't handle those) I happened
to try reading the man page for mhshow (from pkgsrc/mail/nmh) - that's
another than mandoc does a lousy job of:

PROFILE COMPONENTS
       ^Path:~^To determine the user's nmh directory
       ^Current-Folder:~^To find the default current folder
[...]

Those ^ and ~ chars are because mandoc doesn't handle the (ancient)
*roff .fc macro call.

The formatting is also poor, because mandoc also doesn't handle

	.ta \w'cdispo-<PARAM>  'u +\w'Returns   'u

Note that you don't get to say "Don't do that" - this is another
project's work, and they do it the way that suits them (in this case,
because MH is extremely ancient - and nmh is just MH with some
cleanups, and is now also very old itself) and sometimes inertia (and lack
of manpower) simply win ... and requests to change things so that mandoc
(which is hardly a universal tool) can cope aren't likely to be favourably
received.

Similarly, just adding every roff feature that anyone ever uses in a man
page to mandoc would turn mandoc into being just another roff clone, except
with lots of the macros built in, rather than read from a file.
I doubt that's a productive way to go either.

The compromise is to use cat pages to handle the files that mandoc
cannot, format those with groff (or for mhshow, any *roff) and leave
mandoc to handle the normal -man or -mdoc man pages, that don't need
to delve into lower level roff to achieve the desired results.