Re: groff in openSUSE

Re: groff in openSUSE

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 6030 bytes --]

[CC += linux-man@ & groff@, as we're discussing packaging of both]

Hi Michael!

On 2023-08-25 14:05, Michael Vetter wrote:
> Hi Alejandro!
> 
>> Are you a SUSE maintainer?  I'd like to know who is the maintainer of
>> the groff(1) package in openSUSE.  They released a new version a couple
>> of months ago (the first release in several years), and SUSE seems to
>> be the only distro that hasn't yet even started packaging it.
> 
> Yep! And thanks for letting me know.

:)

> 
> Just for your curiousity:
> 
> You can see the maintainers here: 
> https://build.opensuse.org/package/users/M17N/groff from there you would 
> have to click on the users to see their email.

Ahh, I tried many times to find that info without luck; I'm quite dumb
with clicky web UIs.

I now found this with a browser search, which points me at least to
someone who I could have contacted back then:

<https://build.opensuse.org/package/users/openSUSE:Current/groff-full>

> On openSUSE there exists 
> the commandline tool `osc` which can give the information via `osc 
> maintainer -e groff`.

Debian user here.  And I was too lazy to install a VM with openSUSE
just for that :)

> 
> I messaged Antonio now.

Thanks!

> As far as I know he just became a maintainer 
> recently. I think it is a good task for him to get more familar with the 
> project so I asked him to update groff. If he has any issues or no time 
> then I will update the package myself next week.

Heh, he might.  It's a huge release, so he'll very likely stumble upon
it.  But it'll probably be interesting for him.  If you need help,
you can ask <groff@gnu.org>.  Branden, the current maintainer, is quite
friendly and responsive.

> 
>> As a maintainer of the Linux man-pages, that's a small problem to me,
>> as my project has a dependency on groff, and I'm willing to upgrade the
>> dep on the new 1.23.0 version of groff(1).  However, I'd like it to
>> have ample support by distros before doing it.
> 
> After Antonio or I did the upgrade in the (so called) devel project it 
> will go through some reviews and then should land in our repos in a 
> couple of days :-)

Nice!  :-)

> 
> BTW:
> 
> I'm not sure but maybe this is the Linux man-pages package that that we 
> have: 
> https://build.opensuse.org/package/view_file/Documentation/man-pages/man-pages.spec?expand=1

Yes, it's that one.  I am now the maintainer of the project, since a
couple of years ago the previous maintainer, Michael Kerrisk, retired
from it.

> 
> I'm not sure whether it should, but I see that there is no groff 
> dependency or usage in our package?

Hmm.  The dependency is probably indirect through man(1) (from man-db).
Debian has this problem, which I need to fix for the next release.  In
openSUSE, I don't even find the dependency on man(1), so it seems it is
working just because you happen to install man(1) and groff(1) or
mandoc(1) on every system, but the dependency is missing.

man(1) (from man-db) calls groff(1) internally to format the pages, as
man(1) is only a librarian, a program that finds the page in the system
and pipes it to groff(1) to actually format it.

An alternative system is mandoc, which provides in the same package
their own implementation of man(1), and the proper mandoc(1) program,
which can format man(7) pages without resorting to groff(1).  So the
dependency of the Linux man-pages is one of man-db & groff or mandoc.

I documented these dependencies recently in the ./INSTALL file in the
repository:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/INSTALL#n124>

Since our pages do need those systems for being formatted, I think it
would be good to specify them directly on our package.  Also, since
I'm going to require specific versions soon, independent of which
version man(1) requires, I think it's even more appropriate to specify
them directly.

> Do you use this upstream and we just 
> use the result maybe?

We're already using groff-1.23.0 upstream for linting the project,
which BTW would be interesting if you'd like to add it to your package.
That is specified as Build-Depends (similar to the Debian meaning of
it).
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/INSTALL#n73>

I've prepared patches to use that linting in the Debian packaging.
<https://salsa.debian.org/debian/manpages/-/merge_requests/4>
<https://salsa.debian.org/debian/manpages/-/merge_requests/4/diffs?commit_id=87a8494a0d8349c79eaf29956646ae5cb8d64980>
<https://salsa.debian.org/debian/manpages/-/merge_requests/4/diffs?commit_id=db036e589538c04373b7b23d95f5e54bb66efa92>
<https://salsa.debian.org/debian/manpages/-/merge_requests/4/diffs?commit_id=8581562446ed73d3318ae13c95d4100eb6ed6cc5>
Maybe you can add something similar for openSUSE.

For formatting the pages, however, we only require groff (or mandoc),
at any version.

Here goes some review of your package:

> # remove .so link to bzero.3, conflicts with libbsd
> rm man3/explicit_bzero.3

Do you move libbsd pages to section 3?  Upstream libbsd has them in
3bsd precisely to avoid those conflicts.

> # already in bpftool package
> rm man7/bpf-helpers.7

Where does that package get that page from?  Is it from the Linux
man-pages upstream?  If not, where does it come from?  Just curious.

> # conflicts with mandoc
> mkdir man7mp
> mv man7/man.7 man7mp/man.7mp

Since you use man-db as your primary man(1) implementation --or I
thought you do--, having man(7) provided by mandoc makes no sense.
You should have groff's groff_man(7) be your man(7) --maybe via a
link page (.so), or via a symlink--.

BTW, we're in the process of removing man(7) provided by the Linux
man-pages project, so that groff_man(7) becomes the new king, as
it deserves.

Cheers,

Alex

> 
> Best,
> 
> Michael
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: groff in openSUSE

[Ingo Schwarze]

Hi Michael,

Alejandro Colomar wrote on Fri, Aug 25, 2023 at 02:56:15PM +0200:
> On 2023-08-25 14:05, Michael Vetter wrote:

>> # conflicts with mandoc
>> mkdir man7mp
>> mv man7/man.7 man7mp/man.7mp

Creating a subdirectory for the Linux Man Pages Project sounds
like a bad idea to me.  I would expect that to confuse users
because the Linux Man Pages Project is arguably the most important
documentation on Linux, so relegating even part of that to a
subdirectory feels at least surprising.

> Since you use man-db as your primary man(1) implementation --or I
> thought you do--, having man(7) provided by mandoc makes no sense.
> You should have groff's groff_man(7) be your man(7) --maybe via a
> link page (.so), or via a symlink--.

As the upstream maintainer of the mandoc(1) toolkit, i concur.

The man(7) manual page included in the mandoc toolkit documents
how mandoc implements the man(7) language.  That is only useful
for operating systems regarding man(7) as an obsolete historical
language, which isn't the case for Linux because Linux still
sticks to the 1979 tradition of using man(7) for most manual pages
and even supports writing new manual pages in man(7) - even though
i understand that Alejandro is now also willing to accept new
manual pages written in the younger mdoc(7) language which is more
powerful, easier to write, and less susceptible to compatibility
problems nowadays.

If you want to install the mandoc version of the man(7) manual page
on openSUSE - which may occasionally be useful for very experienced
manual page users on openSUSE who wonder what exactly mandoc implements -,
you should probably pick a different name like mandoc_man(7) by
assigning to the MANM_MAN configuration variable in configure.local
as documented in configure.local.example, for example by adding a
line similar to this to configure.local:

  # Some distributions may want to avoid naming conflicts among manuals.
  # If you want to change the names of installed section 7 manual pages,
  # the following alternative names are suggested.
  # The suffix ".7" will automatically be appended.
  # It is possible to set only one or a few of these variables,
  # there is no need to copy the whole block.

  MANM_MAN="mandoc_man"           # default is "man"

Yours,
  Ingo

-- 
Ingo Schwarze             <schwarze@usta.de>
http://www.openbsd.org/   <schwarze@openbsd.org>
http://mandoc.bsd.lv/     <schwarze@mandoc.bsd.lv>