[PATCH 0/1] i18n: add framework for localizing the manpages

[PATCH 0/1] i18n: add framework for localizing the manpages

[Jean-Noël Avila]

Hi all,

This is a second attempt at providing localized manpages of git in a central way. The first attempt[1] was to include all the changes directly in the main repo. But as Junio made me realize, staying in the main repo would have many drawbacks such as forcing possible translators to follow the workflow of Git and preventing use of third party translation tools such as Weblate.

This solution is to make the manpage localization project standalone. I finally had time to hack po4a to enhance support for specificities of git manpages. This rather light patch is only an adaptation of the Makefile to be able to use the same building rules in the translation repo. The translation repo bases the workflow on a copy of the selected manpages asciidoc source files. You can find it at

https://github.com/jnavila/git-manpages-l10n

Translations can be filled using Weblate at https://hosted.weblate.org/projects/git-manpages/

[1] https://public-inbox.org/git/20170312200248.3610-1-jn.avila@free.fr/

Jean-Noel Avila (1):
  Add optional targets for documentation l10n

 Documentation/Makefile | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

-- 
2.20.1

[PATCH 1/1] Add optional targets for documentation l10n

[Jean-Noël Avila]

From: Jean-Noel Avila <jn.avila@free.fr>

The standard doc lists can be filtered to allow using the compilation
rules with translated manpages where all the pages of the original
version may not be present.

The install variable are reused in the secondary repo so that the
configured paths can be used for translated manpages too.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/Makefile | 25 +++++++++++++++++++------
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b5be2e2d3f..1f61a1fe86 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -35,13 +35,18 @@ MAN7_TXT += gittutorial-2.txt
 MAN7_TXT += gittutorial.txt
 MAN7_TXT += gitworkflows.txt
 
-MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
+TMP_MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
+MAN_FILTER ?= $(TMP_MAN_TXT)
+MAN_TXT = $(filter $(TMP_MAN_TXT), $(MAN_FILTER))
+undefine TMP_MAN_TXT
+
 MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
 MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
 
 OBSOLETE_HTML += everyday.html
 OBSOLETE_HTML += git-remote-helpers.html
-DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
+
+TMP_DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
 
 ARTICLES += howto-index
 ARTICLES += git-tools
@@ -81,11 +86,14 @@ TECH_DOCS += technical/trivial-merge
 SP_ARTICLES += $(TECH_DOCS)
 SP_ARTICLES += technical/api-index
 
-DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
+TMP_DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
+HTML_FILTER ?= $(TMP_DOC_HTML)
+DOC_HTML = $(filter $(HTML_FILTER),$(TMP_DOC_HTML))
+undefine TMP_DOC_HTML
 
-DOC_MAN1 = $(patsubst %.txt,%.1,$(MAN1_TXT))
-DOC_MAN5 = $(patsubst %.txt,%.5,$(MAN5_TXT))
-DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT))
+DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER), $(MAN1_TXT)))
+DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER), $(MAN5_TXT)))
+DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER), $(MAN7_TXT)))
 
 prefix ?= $(HOME)
 bindir ?= $(prefix)/bin
@@ -444,4 +452,9 @@ print-man1:
 lint-docs::
 	$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl
 
+ifeq ($(wildcard po/Makefile),po/Makefile)
+doc-l10n install-l10n::
+	$(MAKE) -C po $@
+endif
+
 .PHONY: FORCE
-- 
2.20.1

Re: [PATCH 1/1] Add optional targets for documentation l10n

[Junio C Hamano]

Jean-Noël Avila <jn.avila@free.fr> writes:

> From: Jean-Noel Avila <jn.avila@free.fr>
>
> The standard doc lists can be filtered to allow using the compilation
> rules with translated manpages where all the pages of the original
> version may not be present.
>
> The install variable are reused in the secondary repo so that the
> configured paths can be used for translated manpages too.
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>  Documentation/Makefile | 25 +++++++++++++++++++------
>  1 file changed, 19 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index b5be2e2d3f..1f61a1fe86 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -35,13 +35,18 @@ MAN7_TXT += gittutorial-2.txt
>  MAN7_TXT += gittutorial.txt
>  MAN7_TXT += gitworkflows.txt
>  
> -MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
> +TMP_MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
> +MAN_FILTER ?= $(TMP_MAN_TXT)
> +MAN_TXT = $(filter $(TMP_MAN_TXT), $(MAN_FILTER))
> +undefine TMP_MAN_TXT
> +

I think your arguments to $(filter) is the other way around, but
other than that, I think I get what you are trying to do.  Let me
make sure I got it right.

The idea is to use $(filter PATTERN..., TEXT) that removes words in
TEXT that do not match any of the words in PATTERN, and for normal
build, MAN_FILTER is set identical to TMP_MAN_TXT (which is the
original MAN_TXT), so there is no filtering happen, but in a build
that does tweak MAN_FILTER, MAN_TXT can become a subset of the
original MAN_TXT.

Am I on the right track?

>  MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
>  MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))

And these act on already-filtered MAN_TXT

>  OBSOLETE_HTML += everyday.html
>  OBSOLETE_HTML += git-remote-helpers.html
> -DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
> +
> +TMP_DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
>  
>  ARTICLES += howto-index
>  ARTICLES += git-tools
> @@ -81,11 +86,14 @@ TECH_DOCS += technical/trivial-merge
>  SP_ARTICLES += $(TECH_DOCS)
>  SP_ARTICLES += technical/api-index
>  
> -DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
> +TMP_DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
> +HTML_FILTER ?= $(TMP_DOC_HTML)
> +DOC_HTML = $(filter $(HTML_FILTER),$(TMP_DOC_HTML))
> +undefine TMP_DOC_HTML

This one uses $(filter) in the right direction.

So is it expected that HTML help pages that correspond to manpages
are strict subset of manpages?  

I see HTML_FILTER may be useful to filter HTML pages that come from
$(ARTICLES), but I'd expect that all $(MAN_HTML) that came from the
already-filtered $(MAN_TXT) would not require any further filtering.
With the approach shown, the secondary project ends up needing to
list all the translated MAN_TXT twice (once for MAN_FILTER, and
again for HTML_FILTER), doesn't it?

I am wondering if it makes more sense to have HTML_FILTER filter _only_
parts of the DOC_HTML that does not come from MAN_TXT (i.e. those
$(ARTICLES) pages).

> -DOC_MAN1 = $(patsubst %.txt,%.1,$(MAN1_TXT))
> -DOC_MAN5 = $(patsubst %.txt,%.5,$(MAN5_TXT))
> -DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT))
> +DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER), $(MAN1_TXT)))
> +DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER), $(MAN5_TXT)))
> +DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER), $(MAN7_TXT)))

These are OK, too.

By the way, lose the SP after ',' in $(filter).  As we can see in
the context lines in the patch, args to $(make-functions) are
separated with comma without surrounding SP by convention.

What kind of PATTERN does the secondary project supply when invoking
this Makefile?  If it is list of filenames, I am wondering if it is
simpler to have it override MAN{1,5,7}_TXT variables, without adding
these "TMP_* + fliter + undef TMP_*" dance.

>  prefix ?= $(HOME)
>  bindir ?= $(prefix)/bin
> @@ -444,4 +452,9 @@ print-man1:
>  lint-docs::
>  	$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl
>  
> +ifeq ($(wildcard po/Makefile),po/Makefile)
> +doc-l10n install-l10n::
> +	$(MAKE) -C po $@
> +endif
> +
>  .PHONY: FORCE

Re: [PATCH 1/1] Add optional targets for documentation l10n

[Jean-Noël AVILA]

On Friday, 4 January 2019 22:05:10 CET Junio C Hamano wrote:
> Jean-Noël Avila <jn.avila@free.fr> writes:
> 
> > From: Jean-Noel Avila <jn.avila@free.fr>
> >
> > The standard doc lists can be filtered to allow using the compilation
> > rules with translated manpages where all the pages of the original
> > version may not be present.
> >
> > The install variable are reused in the secondary repo so that the
> > configured paths can be used for translated manpages too.
> >
> > Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> > ---
> >  Documentation/Makefile | 25 +++++++++++++++++++------
> >  1 file changed, 19 insertions(+), 6 deletions(-)
> >
> > diff --git a/Documentation/Makefile b/Documentation/Makefile
> > index b5be2e2d3f..1f61a1fe86 100644
> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
> > @@ -35,13 +35,18 @@ MAN7_TXT += gittutorial-2.txt
> >  MAN7_TXT += gittutorial.txt
> >  MAN7_TXT += gitworkflows.txt
> >  
> > -MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
> > +TMP_MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
> > +MAN_FILTER ?= $(TMP_MAN_TXT)
> > +MAN_TXT = $(filter $(TMP_MAN_TXT), $(MAN_FILTER))
> > +undefine TMP_MAN_TXT
> > +
> 
> I think your arguments to $(filter) is the other way around, but
> other than that, I think I get what you are trying to do.  Let me
> make sure I got it right.
> 
> The idea is to use $(filter PATTERN..., TEXT) that removes words in
> TEXT that do not match any of the words in PATTERN, and for normal
> build, MAN_FILTER is set identical to TMP_MAN_TXT (which is the
> original MAN_TXT), so there is no filtering happen, but in a build
> that does tweak MAN_FILTER, MAN_TXT can become a subset of the
> original MAN_TXT.
> 
> Am I on the right track?
>

Yes that's exactly the purpose of this trick. In fact, $(filter) in this 
configuration is equivalent to an intersection of lists, so the order does not 
change the end result.
 
> >  MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
> >  MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
> 
> And these act on already-filtered MAN_TXT
> 

Yes the filtered list fans out to the outputs.

> >  OBSOLETE_HTML += everyday.html
> >  OBSOLETE_HTML += git-remote-helpers.html
> > -DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
> > +
> > +TMP_DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
> >  
> >  ARTICLES += howto-index
> >  ARTICLES += git-tools
> > @@ -81,11 +86,14 @@ TECH_DOCS += technical/trivial-merge
> >  SP_ARTICLES += $(TECH_DOCS)
> >  SP_ARTICLES += technical/api-index
> >  
> > -DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
> > +TMP_DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
> > +HTML_FILTER ?= $(TMP_DOC_HTML)
> > +DOC_HTML = $(filter $(HTML_FILTER),$(TMP_DOC_HTML))
> > +undefine TMP_DOC_HTML
> 
> This one uses $(filter) in the right direction.
> 
> So is it expected that HTML help pages that correspond to manpages
> are strict subset of manpages?  
> 
> I see HTML_FILTER may be useful to filter HTML pages that come from
> $(ARTICLES), but I'd expect that all $(MAN_HTML) that came from the
> already-filtered $(MAN_TXT) would not require any further filtering.
> With the approach shown, the secondary project ends up needing to
> list all the translated MAN_TXT twice (once for MAN_FILTER, and
> again for HTML_FILTER), doesn't it?

The issue I had here is that DOC_HTML is a superset of of MAN_HTML (which 
needed to be translated anyway for MAN_XML) and I have no way to remove from 
the difference of them the files that are not already translated. So a second 
filter is needed, even if now, MAN_FILTER==HTML_FILTER.

As the translations expand hopefully, we will add the html documentation.

> 
> I am wondering if it makes more sense to have HTML_FILTER filter _only_
> parts of the DOC_HTML that does not come from MAN_TXT (i.e. those
> $(ARTICLES) pages).
> 

It can be done. That would separate manpage filter from doc filter. The 
secondary project can be simplified.

> > -DOC_MAN1 = $(patsubst %.txt,%.1,$(MAN1_TXT))
> > -DOC_MAN5 = $(patsubst %.txt,%.5,$(MAN5_TXT))
> > -DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT))
> > +DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER), $(MAN1_TXT)))
> > +DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER), $(MAN5_TXT)))
> > +DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER), $(MAN7_TXT)))
> 
> These are OK, too.
> 
> By the way, lose the SP after ',' in $(filter).  As we can see in
> the context lines in the patch, args to $(make-functions) are
> separated with comma without surrounding SP by convention.
> 
> What kind of PATTERN does the secondary project supply when invoking
> this Makefile?  If it is list of filenames, I am wondering if it is
> simpler to have it override MAN{1,5,7}_TXT variables, without adding
> these "TMP_* + fliter + undef TMP_*" dance.

Ah, I see. The filter from MAN{1,5,7}_TXT would ripple the same way as MAN_TXT, 
just one level upstream.  The filtering at this level would no longer be 
needed.

Unfortunately, the TMP_* dance would also be needed because these variables 
are built in several steps by append operations, and once filtered, the 
original variables are still useless. My Makefile-fu is low, so I may be 
missing something about redefining variables.

More generally, is this setup sustainable?

[PATCH v2] Add optional targets for documentation l10n

[Jean-Noël Avila]

From: Jean-Noel Avila <jn.avila@free.fr>

The standard doc lists can be filtered to allow using the compilation
rules with translated manpages where all the pages of the original
version may not be present.

The install variable are reused in the secondary repo so that the
configured paths can be used for translated manpages too.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---

The TMP_* dance was removed. The MAN{1,5,7} filtering was preserved, to keep the dispatching policy of manpages in a single place.


Documentation/Makefile | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b5be2e2d3f..c8450d6425 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -35,13 +35,18 @@ MAN7_TXT += gittutorial-2.txt
 MAN7_TXT += gittutorial.txt
 MAN7_TXT += gitworkflows.txt
 
+ifdef MAN_FILTER
+MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
+else
 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
+MAN_FILTER = $(MAN_TXT)
+endif
+
 MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
 MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
 
 OBSOLETE_HTML += everyday.html
 OBSOLETE_HTML += git-remote-helpers.html
-DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
 
 ARTICLES += howto-index
 ARTICLES += git-tools
@@ -81,11 +86,13 @@ TECH_DOCS += technical/trivial-merge
 SP_ARTICLES += $(TECH_DOCS)
 SP_ARTICLES += technical/api-index
 
-DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
+SP_ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
+HTML_FILTER ?= $(SP_ARTICLES_HTML) $(OBSOLETE_HTML)
+DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(SP_ARTICLES_HTML) $(OBSOLETE_HTML))
 
-DOC_MAN1 = $(patsubst %.txt,%.1,$(MAN1_TXT))
-DOC_MAN5 = $(patsubst %.txt,%.5,$(MAN5_TXT))
-DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT))
+DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER), $(MAN1_TXT)))
+DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER), $(MAN5_TXT)))
+DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER), $(MAN7_TXT)))
 
 prefix ?= $(HOME)
 bindir ?= $(prefix)/bin
@@ -444,4 +451,9 @@ print-man1:
 lint-docs::
 	$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl
 
+ifeq ($(wildcard po/Makefile),po/Makefile)
+doc-l10n install-l10n::
+	$(MAKE) -C po $@
+endif
+
 .PHONY: FORCE
-- 
2.20.1

Re: [PATCH v2] Add optional targets for documentation l10n

[Junio C Hamano]

Jean-Noël Avila <jn.avila@free.fr> writes:

> +ifdef MAN_FILTER
> +MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
> +else
>  MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
> +MAN_FILTER = $(MAN_TXT)
> +endif

OK.

>  OBSOLETE_HTML += everyday.html
>  OBSOLETE_HTML += git-remote-helpers.html
> -DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
>  
>  ARTICLES += howto-index
>  ARTICLES += git-tools
> @@ -81,11 +86,13 @@ TECH_DOCS += technical/trivial-merge
>  SP_ARTICLES += $(TECH_DOCS)
>  SP_ARTICLES += technical/api-index
>  
> -DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))

> +SP_ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))

I'd call that $(ARTICLES_HTML); SP_ARTICLES are those pages that
want to become regular articles but singled out because they need
special handling to format.

> +HTML_FILTER ?= $(SP_ARTICLES_HTML) $(OBSOLETE_HTML)
> +DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(SP_ARTICLES_HTML) $(OBSOLETE_HTML))

> -DOC_MAN1 = $(patsubst %.txt,%.1,$(MAN1_TXT))
> -DOC_MAN5 = $(patsubst %.txt,%.5,$(MAN5_TXT))
> -DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT))
> +DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER), $(MAN1_TXT)))
> +DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER), $(MAN5_TXT)))
> +DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER), $(MAN7_TXT)))

Makes sense; s/, /,/, though.

[PATCH v3] Add optional targets for documentation l10n

[Jean-Noël Avila]

From: Jean-Noel Avila <jn.avila@free.fr>

The standard doc lists can be filtered to allow using the compilation
rules with translated manpages where all the pages of the original
version may not be present.

The install variable are reused in the secondary repo so that the
configured paths can be used for translated manpages too.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/Makefile | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b5be2e2d3f..2bd2fb11f4 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -35,13 +35,18 @@ MAN7_TXT += gittutorial-2.txt
 MAN7_TXT += gittutorial.txt
 MAN7_TXT += gitworkflows.txt
 
+ifdef MAN_FILTER
+MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
+else
 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
+MAN_FILTER = $(MAN_TXT)
+endif
+
 MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
 MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
 
 OBSOLETE_HTML += everyday.html
 OBSOLETE_HTML += git-remote-helpers.html
-DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
 
 ARTICLES += howto-index
 ARTICLES += git-tools
@@ -81,11 +86,13 @@ TECH_DOCS += technical/trivial-merge
 SP_ARTICLES += $(TECH_DOCS)
 SP_ARTICLES += technical/api-index
 
-DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
+ARTICLES_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
+HTML_FILTER ?= $(ARTICLES_HTML) $(OBSOLETE_HTML)
+DOC_HTML = $(MAN_HTML) $(filter $(HTML_FILTER),$(ARTICLES_HTML) $(OBSOLETE_HTML))
 
-DOC_MAN1 = $(patsubst %.txt,%.1,$(MAN1_TXT))
-DOC_MAN5 = $(patsubst %.txt,%.5,$(MAN5_TXT))
-DOC_MAN7 = $(patsubst %.txt,%.7,$(MAN7_TXT))
+DOC_MAN1 = $(patsubst %.txt,%.1,$(filter $(MAN_FILTER),$(MAN1_TXT)))
+DOC_MAN5 = $(patsubst %.txt,%.5,$(filter $(MAN_FILTER),$(MAN5_TXT)))
+DOC_MAN7 = $(patsubst %.txt,%.7,$(filter $(MAN_FILTER),$(MAN7_TXT)))
 
 prefix ?= $(HOME)
 bindir ?= $(prefix)/bin
@@ -444,4 +451,9 @@ print-man1:
 lint-docs::
 	$(QUIET_LINT)$(PERL_PATH) lint-gitlink.perl
 
+ifeq ($(wildcard po/Makefile),po/Makefile)
+doc-l10n install-l10n::
+	$(MAKE) -C po $@
+endif
+
 .PHONY: FORCE
-- 
2.20.1

Re: [PATCH 1/1] Add optional targets for documentation l10n

[Junio C Hamano]

Jean-Noël AVILA <jn.avila@free.fr> writes:

>> The idea is to use $(filter PATTERN..., TEXT) that removes words in
>> TEXT that do not match any of the words in PATTERN, and for normal
>> build, MAN_FILTER is set identical to TMP_MAN_TXT (which is the
>> original MAN_TXT), so there is no filtering happen, but in a build
>> that does tweak MAN_FILTER, MAN_TXT can become a subset of the
>> original MAN_TXT.
>> 
>> Am I on the right track?
>>
>
> Yes that's exactly the purpose of this trick. In fact, $(filter) in this 
> configuration is equivalent to an intersection of lists, so the order does not 
> change the end result.

That is only true if MAN_FILTER is literally a list of "I want
exactly these things", without any pattern.  Once a future caller
wants to say "We now have translations for pages from [a-m]*", it
becomes apparent again that the order is wrong.

And if the caller is supposed to have a literal list of pages, not a
pattern, then it may be sufficient to update our Makefile so that
the caller can override the literal list of pages we (incrementally)
compute with its own list without any filtering.

> Ah, I see. The filter from MAN{1,5,7}_TXT would ripple the same way as MAN_TXT, 
> just one level upstream.  The filtering at this level would no longer be 
> needed.

Yup.  I see you sent v2; let me read it.

Thanks.