Info request on how documentation is built for the website - FAQ example

[Beatrice Torracca]

Hi all,

Since I work a lot on translations I would like to understand more how
the built system works to get the documentation from its sources in the
ddp repo to the webpages.

There are some things that I still can not understand. One very
stupid/simple example, using the Debian FAQ is this.
The sgml file is updated and correct (decision vs. decission).
The pot file is correct.
Both Italian and German translation are 100% completed in the po file.

But then you get this 3 pages:

English one with the mistake still present (last line of the question)
https://www.debian.org/doc/manuals/debian-faq/ch-ftparchives.en.html#s-codenames

German one with no sign at all of the sentence, and without some of the
codenames (no orgiginal version shown in their place)
https://www.debian.org/doc/manuals/debian-faq/ch-ftparchives.de.html#s-sourceforcodenames

Italian page with the sentence (with the mistake) and other codenames in
the original untranslated version.
https://www.debian.org/doc/manuals/debian-faq/ch-ftparchives.it.html#s-sourceforcodenames

The mistake was fixed in the repo the 15th of April.

In the past I had to try to understand part of this mechanism to try to
validate my translations or to move a translation from sgml to po, or
just for curiosity and to be able to be more involved in the process.

I imagine the top-level Makefile in the svn ddp repo gets called and
then the 7doc script in cron/parts of the debwww git repo should somehow
publish the doc online. But then what is going wrong here? Or am I
missing something obvious? (It might very well be because my
understanding of those scripts is very limited).

So I would be grateful if someone can explain me this, or point me to
some info, even if maybe it would be obvious for many of you.

Thanks,

beatrice

[victory]

On Sun, 5 Jun 2016 15:00:32 +0200

Post by Beatrice Torracca
In the past I had to try to understand part of this mechanism to try to
validate my translations or to move a translation from sgml to po, or
just for curiosity and to be able to be more involved in the process.

first, use your own system to test, do not try it on the server :)
no real hardware needed for that :)

Post by Beatrice Torracca
I imagine the top-level Makefile in the svn ddp repo gets called and
then the 7doc script in cron/parts of the debwww git repo should somehow
publish the doc online. But then what is going wrong here? Or am I
missing something obvious? (It might very well be because my
understanding of those scripts is very limited).

see SUBDIRS in the ddp's top level Makefile which you mentioned;
it does not contain any "debian-faq"
so the answer is:
yes, you overlooked what the Makefile does;
nothing on the server scripts was the factor
--

note: 7doc_manuals (not 7doc) handles svn versions

7doc handles files in ftpdir/pool/ pulled from ftp,
which means it cares "packaged" manuals

[Beatrice Torracca]

Post by victory
On Sun, 5 Jun 2016 15:00:32 +0200

Post by Beatrice Torracca
In the past I had to try to understand part of this mechanism to try to
validate my translations or to move a translation from sgml to po, or
just for curiosity and to be able to be more involved in the process.

first, use your own system to test, do not try it on the server :)
no real hardware needed for that :)

Yes, of course. :)

I did not mean that I wanted to test my translation on the server. I
never did that.

Still I need to know what "make" command to use on my system too if I
want to create the documentation locally and check that the translated
version compiles correctly.

Also if the translated version does not show on the website correctly it
is necessary to understand what is going wrong if I want to be able to help.

Post by victory

Post by Beatrice Torracca
I imagine the top-level Makefile in the svn ddp repo gets called and
then the 7doc script in cron/parts of the debwww git repo should somehow
publish the doc online. But then what is going wrong here? Or am I
missing something obvious? (It might very well be because my
understanding of those scripts is very limited).

see SUBDIRS in the ddp's top level Makefile which you mentioned;
it does not contain any "debian-faq"
yes, you overlooked what the Makefile does;
nothing on the server scripts was the factor

That is a starting point for me to understand, thanks.

So I guess the webpages for debian-faq are gathered from the debian-faq
packages.

Post by victory
note: 7doc_manuals (not 7doc) handles svn versions
7doc handles files in ftpdir/pool/ pulled from ftp,
which means it cares "packaged" manuals

OK, thanks again. debian-faq is indeed a packaged manual.

beatrice

[victory]

On Sun, 5 Jun 2016 19:13:40 +0200

Post by Beatrice Torracca
Still I need to know what "make" command to use on my system too if I
want to create the documentation locally and check that the translated
version compiles correctly.

it depands on how each of docs build them;
you need investigate each Makefile

you'll need to learn about Makefile in case you are not familiar with it;
do not be afraid even if not, I'm not so familiar with it :p

in any case the log is your best friend :)

but, usually just "make" works

[Holger Wansing]

Hi,

Post by victory
On Sun, 5 Jun 2016 19:13:40 +0200

Post by Beatrice Torracca
Still I need to know what "make" command to use on my system too if I
want to create the documentation locally and check that the translated
version compiles correctly.

it depands on how each of docs build them;
you need investigate each Makefile
you'll need to learn about Makefile in case you are not familiar with it;
do not be afraid even if not, I'm not so familiar with it :p

for debian-faq this is:

make clean
make po4a-translate
make html

optional:
make ps
make pdf


Holger