[bug #58098] [PATCH] build system man page failure

[willie]

URL:
<https://savannah.gnu.org/bugs/?58098>

Summary: [PATCH] build system man page failure
Project: GNU troff
Submitted by: willie
Submitted on: Thu 02 Apr 2020 12:49:55 AM UTC
Category: Core
Severity: 3 - Normal
Item Group: Build/Installation
Status: None
Privacy: Public
Assigned to: None
Open/Closed: Open
Discussion Lock: Any
Planned Release: None

_______________________________________________________

Details:

The man page system requires strict naming conventions and file
tree structure to enable discovery and encoding conversion.

This commit adds (un)install hooks to the build system so that
the Swedish man page will accessible and usable by moving it:
From: $(mandir)/man7/groff_mmse.7
To: $(mandir)/sv/man7/groff_mm.7

Resolves bug:
https://savannah.gnu.org/bugs/index.php?57802

Please consider the attached git patch.

Thank you
Willie




_______________________________________________________

File Attachments:


-------------------------------------------------------
Date: Thu 02 Apr 2020 12:49:55 AM UTC Name:
0001-contrib-mm-mm.am-had-hooks-for-Swedish-man-page.patch Size: 1KiB By:
willie

<http://savannah.gnu.org/bugs/download.php?file_id=48733>

_______________________________________________________

Reply to this item at:

<https://savannah.gnu.org/bugs/?58098>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

[Ingo Schwarze]

Update of bug #58098 (project groff):

Category: Core => Macro - mm
Severity: 3 - Normal => 1 - Wish
Item Group: Build/Installation => Documentation
Status: None => Invalid
Open/Closed: Open => Closed

_______________________________________________________

Follow-up Comment #1:

It is true that many implementations of man(1) require specific naming
conventions for manual page files, but these naming conventions vary among
man(1) implemenations and among operating systems and for some man(1)
implementations, some of these conventions can also be configured on the
individual machine. So an upstream build system cannot fully solve the
question where to install manual pages; if whatever the upstream build system
does won't work well on some operating system, it is the job of the downstream
packaging system to adjust where such files are installed on that system.

That said, on *some* systems (not necessarily on all, some will for example
also include character encodings in the path, or vendor or package
directories, or ...), the path "$(mandir)/sv/man7/groff_mm.7" means "a swedish
translation of the manual page "$(mandir)/man7/groff_mm.7".

But that is not what groff_mmse.7 is. It is not at all a translation of the
manual page groff_mm.7. It does not even document the macro set "mm"
(implemented in contrib/mm/m.tmac). Instead, it documents the *different*
macro set "mmse" (implemented in contrib/mm/mse.tmac).

There is no English documentation for the the "mmse" macro set. So it is
correct that the Swedish documentation gets shown to any user who says "man
groff_mmse", no matter the locale. Also, there is no Swedish translation of
the documentation of the "mm" macro set. So it is correct that the English
documentation of "mm" gets shown to readers even if they have selected a
Swedish locale.

So this ticket is invalid and the patch is wrong. Consequently, i reject the
patch and close the ticket.

_______________________________________________________

Reply to this item at:

<https://savannah.gnu.org/bugs/?58098>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

[willie]

Follow-up Comment #2, bug #58098 (project groff):

Thank you Ingo, for taking the time to write such a through explanation. It is
much appreciated. Sorry for the noise.

_______________________________________________________

Reply to this item at:

<https://savannah.gnu.org/bugs/?58098>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

[Bjarni Ingi Gislason]

Follow-up Comment #3, bug #58098 (project groff):

The report (request, concern) is not invalid, but valid!

The fact is, that the file "groff_mmse.7" is installed in the wrong
directory.

A "wrong" cure does not make an issue invalid nor makes it disappear.

The mistake in the patch is to change the name from "groff_mmse" to
"groff_mm".

In my system the installed software (Debian) puts it in
"/usr/share/man/sv/man7".

The "man" programme does thus not find it.

On a "CentOS release 6.10 (Final)" system it is placed in the
directory, that "groff" dictates, although a directory
"/usr/share/man/sv/" exists (man7/ is missing there).

So "groff" is wrong in this case!

GROFF is a GNU project!

Why should a foreign language man page pop up?

The report is thus about a bug (defect), not a "wish" nor invalid.


_______________________________________________________

Reply to this item at:

<https://savannah.gnu.org/bugs/?58098>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

[Ingo Schwarze]

If there were an English version of the page, then the
arguments regarding the FHS[1] could be perused, IMO.

Correct, if you have an English original and a translation, then the English
original goes into the root and the translation goes somewhere else, but there
is no need to discuss that as we don't have any translations here.

Does GNU have a man(1) implementation?

Not that i'm aware of. The list of man(1) implementations i'm aware of is at
https://mandoc.bsd.lv/links.html; not listing Oracle Solaris man(1) because it
isn't free software. Most Linux distros use man-db, some use man-1.6, a few
use mandoc. man-db and NetBSD man are highly configurable and can be
configured according to the FHS or in totally different ways. What is
actually done may depend on the distro and on the individual sysadmin. mandoc
configuration is deliberately massively simpler. In what matters here, it
follows the FHS except that it deliberately does not support character set
specifiers but only supports UTF-8.

Regarding unusual configurations, commercial Oracle Solaris is usually a
rewarding beast to look at. On one system i have access to, this is the
default MANPATH:

/usr/man:/usr/dt/man:/usr/openwin/man:/opt/RICHPse/man:/opt/csw/man:/usr/sfw/man

/usr/man is a symlink to /usr/share/man and has over 200 subdirectories, but
none of those are locale-releated. It is really hard to make any general
statements.

I would be interested to see a list of who does and who does not.

Sorry, i haven't done full research on that, and i'm not aware of any site
comparing different systems in that respect.

Fortunately, none of this is relevant in the present context because groff
does not contain any translated manual pages in the first place, so installing
all in the root is just fine.

_______________________________________________________

Reply to this item at:

<https://savannah.gnu.org/bugs/?58098>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

[J William Piggott]

Post by Bjarni Ingi Gislason
The report (request, concern) is not invalid, but valid!
The fact is, that the file "groff_mmse.7" is installed in the wrong
directory.

I think there are two levels of discussion: should groff follow the
FHS[1] standard; and where should a man page with only one encoding go.

I mistakenly thought that groff_mmse.7 was intended to be the Swedish
version of groff_mm.7, but that is not the case.

I agree with Ingo that since it is the only documentation available, it
should be in the man root and shown to everyone. If the user is desperate
for the information they could use a translator.

If there were an English version of the page, then the arguments
regarding the FHS[1] could be perused, IMO.

Ingo says that some system do not follow the FHS[1] man page hierarchy.
I would be interested to see a list of who does and who does not.
Perhaps groff should favor the majority, and then fall back to Ingo's
argument that the minority systems need their packagers make the
adjustments.

Or maybe the argument should be that groff should follow GNU? Does GNU
have a man(1) implementation? Is it unoffically the savannah hosted
man-db[2]?

[1] 4.11.6. /usr/share/man : Manual pages:
https://refspecs.linuxfoundation.org/FHS_3.0/fhs-3.0.txt

[2] "NLS manual pages"
http://git.savannah.nongnu.org/cgit/man-db.git/tree/manual/files.me#n212

Post by Bjarni Ingi Gislason
A "wrong" cure does not make an issue invalid nor makes it disappear.
The mistake in the patch is to change the name from "groff_mmse" to
"groff_mm".
In my system the installed software (Debian) puts it in
"/usr/share/man/sv/man7".
The "man" programme does thus not find it.
On a "CentOS release 6.10 (Final)" system it is placed in the
directory, that "groff" dictates, although a directory
"/usr/share/man/sv/" exists (man7/ is missing there).
So "groff" is wrong in this case!
GROFF is a GNU project!
Why should a foreign language man page pop up?

Because it is the only documentation available for everyone.

Post by Bjarni Ingi Gislason
The report is thus about a bug (defect), not a "wish" nor invalid.
_______________________________________________________
<https://savannah.gnu.org/bugs/?58098>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

[willie]

Follow-up Comment #6, bug #58098 (project groff):

[comment #5 comment #5:]

J William Piggott translated the groff_mmse(7) manual from Swedish to
https://lists.gnu.org/archive/html/bug-groff/2020-04/msg00008.html

... >8

William, a translation is a derived work and the translator owns Copyright.

Do you put your work (i.e. the translation) under the GPL? If so, do you
agree that we add a line

.\" Skrivet av Jörgen Hägg, Lund, Sverige
.\" Translated to English by J William Piggott
into the file?

The original is licensed under Latex2e[1], which is incompatible with GPL. So
providing no changes are made that violate the original license, yes I agree.

I have attached v2 to this bug ticket that includes the requested line,
changes the dates, and the file encoding comment in the footer to UTF-8. It
may not be a bad idea to convert the original to UTF-8 as well?

If so, i'd be willing to integrate this, provided that another developer

confirms that we want it. The two files would be installed as
$(mandir)/man7/groff_mmse.7 and $(mandir)/sv/man7/groff_mmse.7. That might
not be perfect on all systems, but close enough, i think, and systems using
slightly different naming schemes can tweak the naming in their packaging
system.

LGTM. Thank you for your time and effort, Ingo.

[1] https://fedoraproject.org/wiki/Licensing/Latex2e


_______________________________________________________

Reply to this item at:

<https://savannah.gnu.org/bugs/?58098>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

[willie]

Additional Item Attachment, bug #58098 (project groff):

File name: groff_mmse.7-en.man Size:4 KB
<https://savannah.gnu.org/file/groff_mmse.7-en.man?file_id=48756>



_______________________________________________________

Reply to this item at:

<https://savannah.gnu.org/bugs/?58098>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

[G. Branden Robinson]

Update of bug #58098 (project groff):

Assigned to: None => schwarze

_______________________________________________________

Follow-up Comment #7:

Assigning to Ingo until and unless he doesn't want it, just so I don't keep
clicking on it as a possible to-do item for myself.

_______________________________________________________

Reply to this item at:

<https://savannah.gnu.org/bugs/?58098>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

[willie]

Follow-up Comment #8, bug #58098 (project groff):

[comment #5 comment #5:]

i'd be willing to integrate this, provided that another
developer confirms that we want it.

Branden, could you (or anyone) please second this so that Ingo can
move forward and close this ticket? Thank you.

_______________________________________________________

Reply to this item at:

<https://savannah.gnu.org/bugs/?58098>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

[Ingo Schwarze]

Follow-up Comment #9, bug #58098 (project groff):

So, after doing some work on the build system integration, i went ahead and
actually read the translated text.

Sorry, but the quality of the translation is insufficient for inclusion. The
translated text is full of grammatical errors, blatantly mistranslated words,
and unclear and confusing wordings. I have started fixing it, but right now
i'm losing patience and i'm also wasting significant amounts of time because
almost every phrase contains at least one serious error that requires
correction. Not sure when i will return to this...

It's OK with me if people leave this ticket assigned to me, maybe i'll return
to it at some point when i happen to be very bored.

If some other developer wants to take over, tell me, and i'll share what i
have so far, but it's unfinished to such a degree that i'm unwilling to
publish it, not even as an attachment in a bugtracking ticket.


_______________________________________________________

Reply to this item at:

<https://savannah.gnu.org/bugs/?58098>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

[G. Branden Robinson]

Update of bug #58098 (project groff):

Status: Confirmed => Need Info

_______________________________________________________

Follow-up Comment #10:

Apparently we need a better translation, so marking "Need Info".

_______________________________________________________

Reply to this item at:

<https://savannah.gnu.org/bugs/?58098>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/