Re: D-I Manual on official Debian website [long]
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On Monday 13 December 2004 13:10, Frank Lichtenheld wrote:
> On Sun, Dec 12, 2004 at 08:02:24PM +0100, Frans Pop wrote:
> 1) AFAIK the install-manual can't be build with the tools available
> in woody, only on sarge (and sid, of course). So the most important
> question is: Can we arrange for the manual to be build on klecker
> or do we need to build it somewhere else and then rsync it to klecker?
> (klecker = www-master). Some time after the release the problem will
> vanish of course.
I think it would be impractical to backport all packages needed to build
all variants of the manual, so I guess until klecker is upgraded,
building elsewhere and rsync is the best option.
> 2) The current installmanual for woody uses the layout
> <arch>/<filename>.<lang>.<ext>, the sarge installmanual uses
> <lang>.<arch>/<filename>.<ext>. I think we would prefer the old layout
> (which would require some changes in build.sh, AFAICS).
As we also link to the final location on the website from the manual, it
would be nice to know what the URL structure will be.
AFAICT, the structure for Woody seems to be:
1. www.d.o/releases/stable/
2. www.d.o/releases/stable/releasenotes/
3. www.d.o/releases/stable/installmanual/
4. www.d.o/releases/stable/<arch>/
5. www.d.o/releases/stable/<arch>/install/
1. General information page on the release
2. Index page for the release notes
3. Index page for the manual
4. I would guess all the actual files are in this directory; it seems
that, for Woody, _all_ html files have a .<lang>.html extention
5. I would guess this is a specially created directory containing the
symlinks supporting content negotiation
For the Sarge manual, the central script is "buildone.sh". There are
currently 2 wrapper scripts that call this script to do bulk builds (for
multiple language/architecture/format combinations) and that determine
the final directory structure:
- - build.sh used to build the "official" version of the manual which are
then included in the debian-installer-manual debs.
- - a complex script I run at home that builds the "unofficial" version
published on alioth.
The buildone.sh script creates all files for _one_ architecture/language
but allows multiple formats.
There are two major differences to the Woody builds:
- - The index file is named "index.html" and not "install.<lang>.html".
- - None of the html files have <lang> in their extension.
The pdf and txt versions _do_ include <lang> in their extention.
I would suggest to create a new wrapper buildscript "webbuild.sh" for the
website that builds the wanted languages and formats and makes sure it
all ends up in the proper directory structure and creates symlinks for
content negotiation (and possibly the index pages).
I would also suggest the following directory structure under
www.d.o/releases/<sarge|testing|stable>/.
1. ./
2. ./releasenotes/ (or whatever has already been decided)
3. ./installmanual/
4. ./installmanual/<arch>.<lang>/
5. ./installmanual/<arch>/
The fuction of 1, 2 and 3 is unchanged from Woody.
4. Contains the html files for a specific architecture/language
combination.
5. Contains the symlinks for content negotiation and the pdf and text
versions of the manual.
IMHO this proposal would make the links from the table (at 3) showing all
possible versions somewhat simpler than the current situation for Woody
as no filenames would have to be included.
Other issues to be decided:
- - Which languages to include on the website?
For the CD's (and the d-i-manual packages) we've limited the languages
to be included to those that were completely translated: en, es, pt_br,
fr, cs and ja.
At the moment de and ru are also very advanced and some other languages
are partially translated. Which should be included at release time?
Should extra languages that complete later be added at that time?
- - Probably the manual for the website should be built from the sarge
branch of the SVN repository.
Note however that currently the build system in that branch does not
allow building pdf or txt files.
How can we work around this?
- - There will probably be major changes to the manual (restructuring) after
Sarge is released that are relevant. Do we want to rebuild the manual
after release for the website?
- - Should rebuilds (if we want them) be triggered automatically or started
manually?
What are the implications of this for translations of the website?
My preference would be manually because that would make it possible to
check the status of translations first and allow to keep the build
scripts simpler.
- - Should the index page at 3 be generated automatically or maintained
manually.
Cheers,
Frans Pop
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (GNU/Linux)
iD8DBQFBwI7Qgm/Kwh6ICoQRAtw6AJ968hDiVQ7JT+JIfQoVFk3xtS73bACgy5NV
Z/D6JzbRpUN6I0Mu/VGJYFg=
=aayR
-----END PGP SIGNATURE-----
Reply to: