[1/1] Add optional targets for documentation l10n
diff mbox series

Message ID 20190104165406.22358-2-jn.avila@free.fr
State New
Headers show
Series
  • i18n: add framework for localizing the manpages
Related show

Commit Message

Jean-Noël Avila Jan. 4, 2019, 4:54 p.m. UTC
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(-)

Comments

Junio C Hamano Jan. 4, 2019, 9:05 p.m. UTC | #1
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
Jean-Noël Avila Jan. 5, 2019, 8:35 a.m. UTC | #2
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?
Junio C Hamano Jan. 7, 2019, 7:29 p.m. UTC | #3
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.

Patch
diff mbox series

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