Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 303919 - Prefer -i18n option of doman to filename language suffix
Summary: Prefer -i18n option of doman to filename language suffix
Status: RESOLVED FIXED
Alias: None
Product: Gentoo Hosted Projects
Classification: Unclassified
Component: PMS/EAPI (show other bugs)
Hardware: All Linux
: High normal (vote)
Assignee: PMS/EAPI
URL:
Whiteboard: in-eapi-4
Keywords:
Depends on:
Blocks: future-eapi
  Show dependency tree
 
Reported: 2010-02-07 20:20 UTC by Daniel Pielmeier
Modified: 2010-12-30 19:53 UTC (History)
1 user (show)

See Also:
Package list:
Runtime testing required: ---


Attachments
doman.patch (doman.patch,459 bytes, patch)
2010-03-05 19:53 UTC, Ulrich Müller
Details | Diff
doman.patch (doman.patch,550 bytes, patch)
2010-03-06 07:55 UTC, Ulrich Müller
Details | Diff
Patch for PMS (pms.patch,2.18 KB, patch)
2010-03-06 07:58 UTC, Ulrich Müller
Details | Diff
Patch for PMS (0001-Document-the-i18n-option-of-doman.patch,3.24 KB, patch)
2010-03-06 11:07 UTC, Ulrich Müller
Details | Diff
Patch for PMS (0001-Document-the-i18n-option-of-doman.patch,3.42 KB, patch)
2010-03-13 11:18 UTC, Ulrich Müller
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Daniel Pielmeier gentoo-dev 2010-02-07 20:20:53 UTC
Bug #222439 introduced the handling of localized manpages. While this is handy, the automatic detection of the language detection leads to bugs where the extension is not meant to be a locale.

For example vdradmind.pl.1 which is a man page for a perl script and not the polish localisation.
Comment 1 SpanKY gentoo-dev 2010-02-08 02:26:13 UTC
i'm of the opinion that programs you run like `foo` in $PATH shouldnt have arbitrary suffixes like '.pl' or '.sh' or '.py'.  people executing `foo` dont give two sh*ts about the implementation details.
Comment 2 Daniel Pielmeier gentoo-dev 2010-02-08 08:24:26 UTC
(In reply to comment #1)
> i'm of the opinion that programs you run like `foo` in $PATH shouldnt have
> arbitrary suffixes like '.pl' or '.sh' or '.py'.  people executing `foo` dont
> give two sh*ts about the implementation details.
> 

Agreed! In my case I already solved this by using newbin for the perl script and newman for the man page.

If I remember right there are cases where the manpage is split up into parts like man.part1.1, man.part2.1 etc...

I filed this bug because I have seen two cases where the automatic locale detection causes problems withing two days.
Comment 3 SpanKY gentoo-dev 2010-02-08 08:27:20 UTC
can you provide some other examples ?  i'm not terribly sympathetic to .pl programs and such ...
Comment 4 Ulrich Müller gentoo-dev 2010-02-08 10:11:13 UTC
(In reply to comment #3)
> can you provide some other examples ?

ld.so.8

> i'm not terribly sympathetic to .pl programs and such ...

Right. But doman could still provide an escape mechanism, even if there are only few legitimate cases.
Comment 5 Jeroen Roovers gentoo-dev 2010-02-20 16:16:13 UTC
(In reply to comment #3)
> can you provide some other examples ?  i'm not terribly sympathetic to .pl
> programs and such ...

net-analyzer/dhcp_probe uses `doman doc/dhcp_probe.cf.5'. The man page ends up being installed as </usr/share/man/cf/man5/dhcp_probe.5.bz2>.
Comment 6 SpanKY gentoo-dev 2010-03-05 18:06:35 UTC
good enough for me ... thanks guys
Comment 7 Ulrich Müller gentoo-dev 2010-03-05 18:49:00 UTC
So, what option letter should be used for this?
   -k (for "keep")
   -N (for --literal according to GNU coding style)

Any better suggestions?
Comment 8 SpanKY gentoo-dev 2010-03-05 19:09:14 UTC
does `doman -i18n=` work today ?
Comment 9 Ulrich Müller gentoo-dev 2010-03-05 19:17:51 UTC
(In reply to comment #8)
> does `doman -i18n=` work today ?

It's ignored if the filename contains a language suffix.
Comment 10 SpanKY gentoo-dev 2010-03-05 19:19:07 UTC
any reason for not fixing that behavior rather than adding new flags ?
Comment 11 Ulrich Müller gentoo-dev 2010-03-05 19:53:49 UTC
Created attachment 222201 [details, diff]
doman.patch

(In reply to comment #10)
> any reason for not fixing that behavior rather than adding new flags ?

Good idea. We only have to make the -i18n option take priority, as in attached patch.
Comment 12 Zac Medico gentoo-dev 2010-03-06 00:35:31 UTC
(In reply to comment #11)
If we want to avoid having doman behave differently depending on the portage version, we'll have to make that behavior change conditional on a new EAPI.
Comment 13 Ulrich Müller gentoo-dev 2010-03-06 07:55:56 UTC
Created attachment 222241 [details, diff]
doman.patch

(In reply to comment #12)
> If we want to avoid having doman behave differently depending on the portage
> version, we'll have to make that behavior change conditional on a new EAPI.

Right, new patch for EAPI 4 (or later) is attached.

So far PMS doesn't mention the option at all, in spite of all package managers supporting it. Patch will follow.
Comment 14 Ulrich Müller gentoo-dev 2010-03-06 07:58:14 UTC
Created attachment 222243 [details, diff]
Patch for PMS

First attempt of a wording for PMS. This would be for EAPI 4.
Comment 15 Christian Faulhammer (RETIRED) gentoo-dev 2010-03-06 08:27:54 UTC
(In reply to comment #14)
> Created an attachment (id=222243) [details]
> Patch for PMS
> 
> First attempt of a wording for PMS. This would be for EAPI 4.

 Short review:

* Is it really "the empty string" or "an empty string"?
* write "e.\,g."
* Better use "\t{-i18n=\textit{lang}}"
Comment 16 Ulrich Müller gentoo-dev 2010-03-06 08:45:45 UTC
(In reply to comment #15)
> * Is it really "the empty string" or "an empty string"?

Since the empty string is unique I think "the" is correct here.

> * write "e.\,g."

"e.\,g.\" even, and the other dozen occurences of it should be fixed too.

> * Better use "\t{-i18n=\textit{lang}}"

You're right again, but I suggest that we postpone these typographical matters. (I haven't even looked at the LaTeX output yet. ;-)

Comment 17 Ciaran McCreesh 2010-03-06 08:49:58 UTC
We've used "in EAPIs specified by" rather than "in EAPIs as decided by" everywhere else I think. The latter sounds rather weird to me.
Comment 18 Ulrich Müller gentoo-dev 2010-03-06 11:07:03 UTC
Created attachment 222257 [details, diff]
Patch for PMS

Updated patch, addressing the points of comment #15 and comment #17.

I've also changed the wording slightly to avoid overfull lines in LaTeX output (due to the long directory names that cannot be split).
Comment 19 David Leverton 2010-03-06 18:47:21 UTC
(In reply to comment #18)
> Created an attachment (id=222257) [details]
> Patch for PMS

"Supports doman languages?" is a bit vague given that the -i18n option is supported in all EAPIs (I know it's worded like that already, and you didn't write it, but still...).  Maybe something like "Supports doman language detection by filename?"
Comment 20 Ulrich Müller gentoo-dev 2010-03-06 19:53:14 UTC
(In reply to comment #19)
> "Supports doman languages?" is a bit vague given that the -i18n option is
> supported in all EAPIs (I know it's worded like that already, and you didn't
> write it, but still...).  Maybe something like "Supports doman language
> detection by filename?"

Fine with me. I think I'll wait for a few days to collect any other suggestions, before preparing a new patch.

Another question, should "newman" accept an -i18n option too (and propagate it to doman)? Currently it doesn't, but we could add this for EAPI 4.
Comment 21 Ulrich Müller gentoo-dev 2010-03-11 18:58:15 UTC
(In reply to comment #19)
> Maybe something like "Supports doman language detection by filename?"

It turns out that this makes the table too wide. How about "Language detection by filename"?
Comment 22 David Leverton 2010-03-11 19:33:44 UTC
(In reply to comment #21)
> It turns out that this makes the table too wide. How about "Language detection
> by filename"?
> 

Sure.

Just noticed that the caption says "EAPIs supporting doman languages", which should probably be changed for the same reason, although I can't think of what to change it to.
Comment 23 Ulrich Müller gentoo-dev 2010-03-11 20:30:15 UTC
(In reply to comment #22)
> Just noticed that the caption says "EAPIs supporting doman languages", which
> should probably be changed for the same reason, although I can't think of
> what to change it to.

"\t{doman} language support for EAPIs"?
(The i18n option is about language support too.)
Comment 24 David Leverton 2010-03-11 21:00:32 UTC
(In reply to comment #23)
> "\t{doman} language support for EAPIs"?
> (The i18n option is about language support too.)
> 

Maybe something about "options" or "extras", since the base -i18n is available in all of them, but something like that, yeah.
Comment 25 Ulrich Müller gentoo-dev 2010-03-13 11:18:13 UTC
Created attachment 223393 [details, diff]
Patch for PMS

New patch, taking all comments into account.
Comment 26 Ulrich Müller gentoo-dev 2010-04-20 07:39:36 UTC
This was approved for EAPI 4 in yesterday's council meeting.
Portage implementation is tracked in bug 316311.
Comment 27 Ulrich Müller gentoo-dev 2010-12-30 19:53:14 UTC
EAPI 4 has been approved by the council.