bugGNU roff - Bugs: bug #58098, provide English translation of...

 
 

bug #58098: provide English translation of groff_mmse(7) man page

Submitter:  willie <willie>
Submitted:  Thu 02 Apr 2020 12:49:55 AM UTC
   
 
Category:  Macro mm Severity:  1 - Wish
Item Group:  Documentation Status:  Rejected
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Fri 31 Mar 2023 11:13:06 AM UTC, comment #12: 

I concur with Ingo that the quality of the English translation is not up to our standards, and with Bjarni that the prudence of shipping a translation for this page is questionable.

Let us review the purpose of the mse.tmac macro file, which is loaded with either of the "-mse" or "-mmse" command-line options to groff(1) or troff(1).

Quoting groff_mm(7) from the forthcoming groff 1.23.0 release:


  Localization
    groff mm is designed to be easily localized.  For languages other
    than English, strings that can appear in output are collected in the
    file /home/branden/groff/share/groff/1.23.0/tmac/xx.tmac, where xx
    is an ISO 639 two‐letter language identifier.  For Swedish, this is
    sv.tmac; “sv”, not “se”.

    This package can also be localized by site or territory; for
    example, /home/branden/groff/share/groff/1.23.0/tmac/mse.tmac
    illustrates how to adapt the output to a national standard using its
    ISO 3166 territory code.  Such a package can define a string that
    causes a macro file /home/branden/groff/share/groff/1.23.0/tmac/mm/
    territory_locale to be loaded at package initialization.  If this
    mechanism is not used, /home/branden/groff/share/groff/1.23.0/tmac/
    mm/locale is loaded instead.  No diagnostic is produced if these
    files do not exist.


(Please excuse the customized installation directory names.)

The whole point of the macro file is to address the localized needs of a language community, potentially within a territory where English is little used.

Most English speakers have no need of this man page; any that do must also have a sufficient command of Swedish to correctly produce formal documents in that language.

I am therefore closing this ticket as rejected, and dropping the patch annotation.  Even were my reasoning overturned and this ticket to be reopened, problems with the patch quality to date would remain, and the annotation should not be restored until an acceptable one is attached.

G. Branden Robinson <gbranden>
Group administrator
Sun 22 Nov 2020 08:27:00 PM UTC, comment #11: 

  There is no need for an English version.

  The manual is about a Swedish variant of the "mm" macro package,
 and therefore uses "contrib/mm/mse.tmac"
 It is for text in Swedish, so it is naturally in the same language.

  As the Debian distribution shows, its place is

 /usr/share/man/sv/man7/groff_mmse.7.gz

  Or read the hier(7), file-hierarchy(7),

 or

 https://refspecs.linuxfoundation.org/fhs.shtml

Bjarni Ingi Gislason <bjarniig>
Thu 16 Apr 2020 08:09:52 AM UTC, comment #10: 

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

G. Branden Robinson <gbranden>
Group administrator
Sat 11 Apr 2020 10:00:15 PM UTC, comment #9: 

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.

Ingo Schwarze <schwarze>
Group Member
Sat 11 Apr 2020 01:36:17 PM UTC, comment #8: 

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.

willie <willie>
Sat 11 Apr 2020 03:57:46 AM UTC, 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.

G. Branden Robinson <gbranden>
Group administrator
Sun 05 Apr 2020 02:42:42 AM UTC, comment #6: 

comment #5:

> J William Piggott translated the groff_mmse(7) manual from Swedish to English and posted the translation here:
>
> 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

willie <willie>
Sat 04 Apr 2020 01:52:04 PM UTC, comment #5: 

J William Piggott translated the groff_mmse(7) manual from Swedish to English and posted the translation here:

https://lists.gnu.org/archive/html/bug-groff/2020-04/msg00008.html

Now, do we want to include that translation?

Advantage: In the unlikely case that somebody uses -mmse who is unable to understand Swedish (or, a bit more likely, has to deal with a file using it that was prepared by somebody else), having the manual available in English may help a bit.

Downside: Minor ongoing effort to maintain the translation itself and the build system parts related to it.

Neither the advantage nor the downside feels large, but i think the advantage may slightly outweigh the downside.

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?

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.

Ingo Schwarze <schwarze>
Group Member
Fri 03 Apr 2020 10:09:27 PM UTC, comment #4: 

J William Piggott asked:

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

Ingo Schwarze <schwarze>
Group Member
Fri 03 Apr 2020 12:57:05 AM UTC, comment #3: 

  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.

Bjarni Ingi Gislason <bjarniig>
Thu 02 Apr 2020 03:44:49 PM UTC, comment #2: 

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

willie <willie>
Thu 02 Apr 2020 02:57:16 AM UTC, 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.

Ingo Schwarze <schwarze>
Group Member
Thu 02 Apr 2020 12:49:55 AM UTC, original submission:  

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

willie <willie>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #48756:  groff_mmse.7-en.man added by willie (4KiB - application/x-troff-man - v2 English translation of groff_mmse.7.man)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by bjarniig (Posted a comment)
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by willie (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 16 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-03-31 gbranden StatusNeed Info Rejected
        Assigned toschwarze gbranden
        Open/ClosedOpen Closed
        Summary[PATCH] English translation of the groff_mmse(7) manual provide English translation of groff_mmse(7) man page
    2020-04-16 gbranden StatusConfirmed Need Info
    2020-04-11 gbranden Assigned toNone schwarze
    2020-04-05 willie Attached File- Added groff_mmse.7-en.man, #48756
    2020-04-04 schwarze StatusInvalid Confirmed
        Open/ClosedClosed Open
        Summary[PATCH] build system man page failure [PATCH] English translation of the groff_mmse(7) manual
    2020-04-02 schwarze CategoryCore Macro mm
        Severity3 - Normal 1 - Wish
        Item GroupBuild/Installation Documentation
        StatusNone Invalid
        Open/ClosedOpen Closed
    2020-04-02 willie Attached File- Added 0001-contrib-mm-mm.am-had-hooks-for-Swedish-man-page.patch, #48733

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code