How to build only Guix Manual

How to build only Guix Manual

[Rafael Fontenelle]

Hello,

I'm translating Guix Manual to Brazilian Portuguese, and I want to
build only the documentation (not the software) in order to test my
translation.

What I've got so far found:
1- doc/build.scm : line 9 : added "pt_BR" to the list of languages
2- doc/local.mk : line 21 : added guix.pt_BR.texi to info_TEXINFOS
3- doc/local.mk : line 34 : added guix/contributing.pt_BR.texi to
TRANSLATED_INFO
4- po/doc/local.mk: line 58: added "guix-manual.pt_BR.po" to DOC_PO_FILES

Is there a way for me to build only the Guix Manual (not the software)?

Thanks in advance.

Best regards,
Rafael Fontenelle

Re: How to build only Guix Manual

[Julien Lepiller]

Le Mon, 2 Sep 2019 16:41:22 -0300,
Rafael Fontenelle <rafaelff@gnome.org> a écrit :

> Hello,
> 
> I'm translating Guix Manual to Brazilian Portuguese, and I want to
> build only the documentation (not the software) in order to test my
> translation.
> 
> What I've got so far found:
> 1- doc/build.scm : line 9 : added "pt_BR" to the list of languages
> 2- doc/local.mk : line 21 : added guix.pt_BR.texi to info_TEXINFOS
> 3- doc/local.mk : line 34 : added guix/contributing.pt_BR.texi to
> TRANSLATED_INFO
> 4- po/doc/local.mk: line 58: added "guix-manual.pt_BR.po" to
> DOC_PO_FILES
> 
> Is there a way for me to build only the Guix Manual (not the
> software)?
> 
> Thanks in advance.
> 
> Best regards,
> Rafael Fontenelle
> 

Hi Rafael,

thanks for taking the time to translate the manual!

You can build the manual only by configuring the repository. If you are
running guix, you can simply run `guix environment guix` inside your
current git checkout. Otherwise, you will need to install the required
dependencies using your system package manager.

Then, you can run:

./bootstrap
./configure --localstatedir=/var

and to build only the manual:

make doc/guix.pt_BR.info

or

make doc/guix.pt_BR.html

Re: How to build only Guix Manual

[Rafael Fontenelle]

Julien,

Thanks, it is helping me a lot to fix errors in anchors and references
already. But the compilation is not successfully completing because
some os-config-* can not found -- indeed, I notice there is no
os-config-* in the build tree (no pt_BR neither English one).

See output of `make doc/guix.pt_BR.html' (it seems safe to ignore po4a
"seems outdated" messages):

  PO4A doc/contributing.pt_BR.texi
Your input po file po/doc/guix-manual.pt_BR.po seems outdated (The
amount of entries differ between files: 7994 is not 228
). Please consider running po4a-updatepo to refresh it.
  POXREF doc/contributing.pt_BR.texi
mv "doc/contributing.pt_BR.texi.tmp" "doc/contributing.pt_BR.texi"
  PO4A doc/guix.pt_BR.texi
Your input po file po/doc/guix-manual.pt_BR.po seems outdated (The
amount of entries differ between files: 7994 is not 8055
). Please consider running po4a-updatepo to refresh it.
sed -i "s|guix\.info|$(basename "doc/guix.pt_BR.texi" | sed
's|texi$|info|')|" "doc/guix.pt_BR.texi.tmp"
  POXREF doc/guix.pt_BR.texi
mv "doc/guix.pt_BR.texi.tmp" "doc/guix.pt_BR.texi"
Updating ./doc/version-pt_BR.texi
  MAKEINFO doc/guix.pt_BR.html
doc/guix.pt_BR.texi:10287: @include: could not find
os-config-bare-bones-pt_BR.texi
doc/guix.pt_BR.texi:10422: @include: could not find os-config-desktop-pt_BR.texi
doc/guix.pt_BR.texi:10429: @include: could not find
os-config-lightweight-desktop-pt_BR.texi
make: *** [Makefile:4228: doc/guix.pt_BR.html] Error 1

Any suggestion?

Em seg, 2 de set de 2019 às 17:04, Julien Lepiller
<julien@lepiller.eu> escreveu:
>
> Le Mon, 2 Sep 2019 16:41:22 -0300,
> Rafael Fontenelle <rafaelff@gnome.org> a écrit :
>
> > Hello,
> >
> > I'm translating Guix Manual to Brazilian Portuguese, and I want to
> > build only the documentation (not the software) in order to test my
> > translation.
> >
> > What I've got so far found:
> > 1- doc/build.scm : line 9 : added "pt_BR" to the list of languages
> > 2- doc/local.mk : line 21 : added guix.pt_BR.texi to info_TEXINFOS
> > 3- doc/local.mk : line 34 : added guix/contributing.pt_BR.texi to
> > TRANSLATED_INFO
> > 4- po/doc/local.mk: line 58: added "guix-manual.pt_BR.po" to
> > DOC_PO_FILES
> >
> > Is there a way for me to build only the Guix Manual (not the
> > software)?
> >
> > Thanks in advance.
> >
> > Best regards,
> > Rafael Fontenelle
> >
>
> Hi Rafael,
>
> thanks for taking the time to translate the manual!
>
> You can build the manual only by configuring the repository. If you are
> running guix, you can simply run `guix environment guix` inside your
> current git checkout. Otherwise, you will need to install the required
> dependencies using your system package manager.
>
> Then, you can run:
>
> ./bootstrap
> ./configure --localstatedir=/var
>
> and to build only the manual:
>
> make doc/guix.pt_BR.info
>
> or
>
> make doc/guix.pt_BR.html

Re: How to build only Guix Manual

[Julien Lepiller]

Le 3 septembre 2019 02:37:25 GMT+02:00, Rafael Fontenelle <rafaelff@gnome.org> a écrit :
>Julien,
>
>Thanks, it is helping me a lot to fix errors in anchors and references
>already. But the compilation is not successfully completing because
>some os-config-* can not found -- indeed, I notice there is no
>os-config-* in the build tree (no pt_BR neither English one).
>
>See output of `make doc/guix.pt_BR.html' (it seems safe to ignore po4a
>"seems outdated" messages):
>
>  PO4A doc/contributing.pt_BR.texi
>Your input po file po/doc/guix-manual.pt_BR.po seems outdated (The
>amount of entries differ between files: 7994 is not 228
>). Please consider running po4a-updatepo to refresh it.
>  POXREF doc/contributing.pt_BR.texi
>mv "doc/contributing.pt_BR.texi.tmp" "doc/contributing.pt_BR.texi"
>  PO4A doc/guix.pt_BR.texi
>Your input po file po/doc/guix-manual.pt_BR.po seems outdated (The
>amount of entries differ between files: 7994 is not 8055
>). Please consider running po4a-updatepo to refresh it.
>sed -i "s|guix\.info|$(basename "doc/guix.pt_BR.texi" | sed
>'s|texi$|info|')|" "doc/guix.pt_BR.texi.tmp"
>  POXREF doc/guix.pt_BR.texi
>mv "doc/guix.pt_BR.texi.tmp" "doc/guix.pt_BR.texi"
>Updating ./doc/version-pt_BR.texi
>  MAKEINFO doc/guix.pt_BR.html
>doc/guix.pt_BR.texi:10287: @include: could not find
>os-config-bare-bones-pt_BR.texi
>doc/guix.pt_BR.texi:10422: @include: could not find
>os-config-desktop-pt_BR.texi
>doc/guix.pt_BR.texi:10429: @include: could not find
>os-config-lightweight-desktop-pt_BR.texi
>make: *** [Makefile:4228: doc/guix.pt_BR.html] Error 1
>
>Any suggestion?
>
>Em seg, 2 de set de 2019 às 17:04, Julien Lepiller
><julien@lepiller.eu> escreveu:
>>
>> Le Mon, 2 Sep 2019 16:41:22 -0300,
>> Rafael Fontenelle <rafaelff@gnome.org> a écrit :
>>
>> > Hello,
>> >
>> > I'm translating Guix Manual to Brazilian Portuguese, and I want to
>> > build only the documentation (not the software) in order to test my
>> > translation.
>> >
>> > What I've got so far found:
>> > 1- doc/build.scm : line 9 : added "pt_BR" to the list of languages
>> > 2- doc/local.mk : line 21 : added guix.pt_BR.texi to info_TEXINFOS
>> > 3- doc/local.mk : line 34 : added guix/contributing.pt_BR.texi to
>> > TRANSLATED_INFO
>> > 4- po/doc/local.mk: line 58: added "guix-manual.pt_BR.po" to
>> > DOC_PO_FILES
>> >
>> > Is there a way for me to build only the Guix Manual (not the
>> > software)?
>> >
>> > Thanks in advance.
>> >
>> > Best regards,
>> > Rafael Fontenelle
>> >
>>
>> Hi Rafael,
>>
>> thanks for taking the time to translate the manual!
>>
>> You can build the manual only by configuring the repository. If you
>are
>> running guix, you can simply run `guix environment guix` inside your
>> current git checkout. Otherwise, you will need to install the
>required
>> dependencies using your system package manager.
>>
>> Then, you can run:
>>
>> ./bootstrap
>> ./configure --localstatedir=/var
>>
>> and to build only the manual:
>>
>> make doc/guix.pt_BR.info
>>
>> or
>>
>> make doc/guix.pt_BR.html

I don't understand why they are not generated when building individual info manuals. You can build these files with:

make doc/os-config-bare-bones.texi
ect

Note that we don't provide a way to translate these examples yet, so you'll have to use the English filename for now, or help us get them translated :)

Re: How to build only Guix Manual

[Ludovic Courtès]

Hi Rafael,

Julien Lepiller <julien@lepiller.eu> skribis:

> Then, you can run:
>
> ./bootstrap
> ./configure --localstatedir=/var
>
> and to build only the manual:
>
> make doc/guix.pt_BR.info

Alternately you can run:

  guix build -f doc/build.scm

Thanks for translating the manual, Rafael!

Ludo’.

Re: How to build only Guix Manual

[Rafael Fontenelle]

Em ter, 3 de set de 2019 às 05:16, Julien Lepiller
<julien@lepiller.eu> escreveu:
>
> I don't understand why they are not generated when building individual info manuals. You can build these files with:
>
> make doc/os-config-bare-bones.texi
> ect
>
> Note that we don't provide a way to translate these examples yet, so you'll have to use the English filename for now, or help us get them translated :)

Thanks Julien and Ludovic (in other email) for the replies.

Yep, adding the above command did the job and the build of HTML manual
worked just fine.

Doubt: is it safe to replace @pxref and @xref with @ref?  These two
macros prefix an untranslatable "see" and "See", respectively, before
the linked section. So I am considering using "veja @ref" and "Veja
@ref" (veja = "see" translation) instead.

Re: How to build only Guix Manual

[Julien Lepiller]

Le 3 septembre 2019 13:08:14 GMT+02:00, Rafael Fontenelle <rafaelff@gnome.org> a écrit :
>Em ter, 3 de set de 2019 às 05:16, Julien Lepiller
><julien@lepiller.eu> escreveu:
>>
>> I don't understand why they are not generated when building
>individual info manuals. You can build these files with:
>>
>> make doc/os-config-bare-bones.texi
>> ect
>>
>> Note that we don't provide a way to translate these examples yet, so
>you'll have to use the English filename for now, or help us get them
>translated :)
>
>Thanks Julien and Ludovic (in other email) for the replies.
>
>Yep, adding the above command did the job and the build of HTML manual
>worked just fine.
>
>Doubt: is it safe to replace @pxref and @xref with @ref?  These two
>macros prefix an untranslatable "see" and "See", respectively, before
>the linked section. So I am considering using "veja @ref" and "Veja
>@ref" (veja = "see" translation) instead.

Yes, other translators have done that. It sometimes issues a warning, but it's generally safe I think.

Re: How to build only Guix Manual

[Rafael Fontenelle]

Em ter, 3 de set de 2019 às 08:33, Julien Lepiller
<julien@lepiller.eu> escreveu:
>
> Le 3 septembre 2019 13:08:14 GMT+02:00, Rafael Fontenelle <rafaelff@gnome.org> a écrit :
> >Em ter, 3 de set de 2019 às 05:16, Julien Lepiller
> ><julien@lepiller.eu> escreveu:
> >>
> >> I don't understand why they are not generated when building
> >individual info manuals. You can build these files with:
> >>
> >> make doc/os-config-bare-bones.texi
> >> ect
> >>
> >> Note that we don't provide a way to translate these examples yet, so
> >you'll have to use the English filename for now, or help us get them
> >translated :)
> >
> >Thanks Julien and Ludovic (in other email) for the replies.
> >
> >Yep, adding the above command did the job and the build of HTML manual
> >worked just fine.
> >
> >Doubt: is it safe to replace @pxref and @xref with @ref?  These two
> >macros prefix an untranslatable "see" and "See", respectively, before
> >the linked section. So I am considering using "veja @ref" and "Veja
> >@ref" (veja = "see" translation) instead.
>
> Yes, other translators have done that. It sometimes issues a warning, but it's generally safe I think.

Great, thanks.

So, just for the record, I'll sum up below all I did in order to help
anyone willing to start testing translations:
1- doc/build.scm : line 9 : added "pt_BR" to the list of languages
2- doc/local.mk : line 21 : added guix.pt_BR.texi to info_TEXINFOS
3- doc/local.mk : line 34 : added guix/contributing.pt_BR.texi to
TRANSLATED_INFO
4- po/doc/local.mk: line 58: added "guix-manual.pt_BR.po" to DOC_PO_FILES
5- put my guix-manual translation in po/doc/guix-manual.pt_BR.po
6- ran:

make doc/os-config-bare-bones.texi
make doc/os-config-desktop.texi
make doc/os-config-lightweight-desktop.texi
make doc/guix.pt_BR.html

And (after some fixes in the translation) the documentation was
available at "doc/guix.pt_BR.html/"

Translating texinfo commands in Guix manual (was: Re: How to build only Guix Manual)

[Rafael Fontenelle]

For whom it may interest.

Em ter, 3 de set de 2019 às 08:33, Julien Lepiller
<julien@lepiller.eu> escreveu:
>
> Le 3 septembre 2019 13:08:14 GMT+02:00, Rafael Fontenelle <rafaelff@gnome.org> a écrit :
> >Em ter, 3 de set de 2019 às 05:16, Julien Lepiller
> ><julien@lepiller.eu> escreveu:
> >
> >Doubt: is it safe to replace @pxref and @xref with @ref?  These two
> >macros prefix an untranslatable "see" and "See", respectively, before
> >the linked section. So I am considering using "veja @ref" and "Veja
> >@ref" (veja = "see" translation) instead.
>
> Yes, other translators have done that. It sometimes issues a warning, but it's generally safe I think.

I learned how to translate the see/See <link> from @pxref and @xref.
First, texinfo_document has to be translated to the target language
[1]. Second, make sure to include "@documentlanguage
<target_language_code>" when translating the following string:

#. type: Plain text
#: doc/guix.texi:7
msgid "@documentencoding UTF-8"
msgstr ""

For example, for Brazilian Portuguese, I have translated to:

#. type: Plain text
#: doc/guix.texi:7
msgid "@documentencoding UTF-8"
msgstr ""
"@documentencoding UTF-8\n"
"@documentlanguage pt_BR"

Now, using @pxref, @xref and any other related texinfo command are
translated to the target language in the resulting Guix manual.

[1] https://translationproject.org/domain/texinfo_document.html

Re: Translating texinfo commands in Guix manual (was: Re: How to build only Guix Manual)

[pelzflorian (Florian Pelz)]

Thank you for your localization efforts!

On Thu, Oct 17, 2019 at 03:18:58AM -0300, Rafael Fontenelle wrote:
> For example, for Brazilian Portuguese, I have translated to:
> 
> #. type: Plain text
> #: doc/guix.texi:7
> msgid "@documentencoding UTF-8"
> msgstr ""
> "@documentencoding UTF-8\n"
> "@documentlanguage pt_BR"
> 

You may want to add frenchspacing:

#. type: Plain text
#: doc/guix.texi:7
msgid "@documentencoding UTF-8"
msgstr ""
"@documentencoding UTF-8\n"
"@documentlanguage pt_BR\n"
"@frenchspacing on"

I do not know if french spacing is common in Portuguese.


> Now, using @pxref, @xref and any other related texinfo command are
> translated to the target language in the resulting Guix manual.
> 
> [1] https://translationproject.org/domain/texinfo_document.html
> 

I always use “see @ref{…}” because @xref and @pxref are only
translated in HTML output for me, but not when running “info guix.de”.
The info command looks more right and HTML looks the same.

Regards,
Florian

Re: Translating texinfo commands in Guix manual (was: Re: How to build only Guix Manual)

[Rafael Fontenelle]

Hi Florian

Em qui, 17 de out de 2019 às 04:39, pelzflorian (Florian Pelz)
<pelzflorian@pelzflorian.de> escreveu:
>
> You may want to add frenchspacing:
>
> #. type: Plain text
> #: doc/guix.texi:7
> msgid "@documentencoding UTF-8"
> msgstr ""
> "@documentencoding UTF-8\n"
> "@documentlanguage pt_BR\n"
> "@frenchspacing on"
>
> I do not know if french spacing is common in Portuguese.
>

It seems the French Spacing consists in a space between last word in a
sentence and ending punctuation, and only one space between sentences.
If I've got it right, then it doesn't apply to Portuguese. We normally
use no space between last word and ending punctuation, and also only
one space between sentences.

Thanks for the suggestion, though.

> I always use “see @ref{…}” because @xref and @pxref are only
> translated in HTML output for me, but not when running “info guix.de”.
> The info command looks more right and HTML looks the same.

Testing the info output, it shows " *note <link>:: " (where <link> is
the target link. Is this the same you see in not using “see @ref{…}” ?

Regards,
Rafael Fontenelle

Re: Translating texinfo commands in Guix manual (was: Re: How to build only Guix Manual)

[pelzflorian (Florian Pelz)]

On Thu, Oct 17, 2019 at 05:17:43AM -0300, Rafael Fontenelle wrote:
> It seems the French Spacing consists in a space between last word in a
> sentence and ending punctuation, and only one space between sentences.
> If I've got it right, then it doesn't apply to Portuguese. We normally
> use no space between last word and ending punctuation, and also only
> one space between sentences.
> 

I believe the Texinfo command @frenchspacing only affects whether
there is a single or double space after a sentence.  What you describe
sounds like you would want to use French spacing (although it is
apparently without effect in HTML output).

See the Texinfo manual (“info texinfo”), section
12.3.4 '@frenchspacing' VAL: Control Sentence Spacing.

I believe whether you put a space before … or quotes is *not* affected by
Texinfo’s @frenchspacing command, despite the real meaning of French spacing:
#: gnu/installer/newt/network.scm:125
msgid "Waiting for Internet access establishment..."
msgstr "Auf Herstellung des Internetzugangs wird gewartet …"


> Thanks for the suggestion, though.
> 
> > I always use “see @ref{…}” because @xref and @pxref are only
> > translated in HTML output for me, but not when running “info guix.de”.
> > The info command looks more right and HTML looks the same.
> 
> Testing the info output, it shows " *note <link>:: " (where <link> is
> the target link. Is this the same you see in not using “see @ref{…}” ?
> 
> Regards,
> Rafael Fontenelle

This is hard to explain.  Both are wrong.  The proper solution might
be to fix Texinfo and use @pxref and @xref where appropriate, or
alternatively to get rid of useless @pxref and @xref.  For now though,
I see:

With @pxref, in HTML, “veja <link>” (translated), in `info' “*note <link>“.

With “see @ref”, in HTML, “veja <link>”, in `info' “veja *note <link>”.

Therefore I think “veja @ref” is less wrong.  I guess we should ask on
the Texinfo mailing list upstream.

Regards,
Florian