Re: library packaging doc...
Hi,
On Sat, Feb 26, 2005 at 05:00:11PM +0900, Junichi Uekawa wrote:
> I would like to request some input on actual actions that I will
> need to do in order to maintain libpkg-guide as part of
> DDP.
I cannot say whether this document is accepted but no one complained yet
so go on.
> I'm not quite yet sure about the Makefile structure,
> and directory structure.
That's indeed a good question and there were many discussions during the
last years. Let's hope we will be able to find a good solution.
> 1. Directory
> is
> ddp/manuals.sgml/libpkg-guide
> okay? The directory is called sgml, but the libpkg-guide source is in
> DocBook-XML format.
We plan to move from SGML to DocBook XML for DDP documents. It is very
likely that this will result in a new file/directory structure. The
change will be performed using a script. Nevertheless I expect a lot of
manual changes for the transition.
The current CVS is especially important for translators who need a
history for synchronisation. After the transition it is much more
difficult to synchronize an old SGML file against a new XML file. Fancy
scripts such as doc-check which is used by a few documents will no
longer work (or better: create too large patches to be useful). This
requires manual intervention so I suggest to move to a new directory
structure for XML documents. It will not make syncs easier but it
doesn't harm and we will have a proper directory structure.
So we will also see what documents are still in SGML and need fixes.
I do not know DocBook but I suggest something like
ddp/manuals.xml or ddp/manuals.docbook, ...
I also strongly suggest to use a unique file and directory structure for
all documents. This includes:
Translations should always reside in an own subdirectory $lang. This is
true for English files as well (no longer no ".en" suffix for these files,
this simplifies Makefiles).
Now the funny question: What's the form of $lang: pt_BR or pt-br, de or
de_DE, ...
Both forms have pro's and con's (see the debian-doc, debian-www
archives, e.g.
From: Frank Lichtenheld <djpig@debian.org>
Subject: correct language extension for pt_BR?
Date: Tue, 1 Feb 2005 23:20:21 +0100
To: debian-www@lists.debian.org
)
Currently I prefer: pt-br. One reason for this is that debian packages
of DDP documents have sometimes a -$lang suffix and capitals and _ are
invalid there.
Do you know what form is required to specify the document language to
docbook tools?
I also suggest to create a single file for each chapter so that it's not
necessary to split a large file later into smaller parts as happened
with securing-howto 8 months ago. Translators (e.g. the German one, see
current debian-l10n-german postings) have now problems to synchronize ...
By the way: It happened in the past that useful scripts/Makefile
approaches where copied and modified for each document (doc-check,
doc-copy, getdocdate, or do you remember that I added
../quick-reference/bin to many PATH's in Makefile's?). Using a
consistent scheme we can reuse all these files.
Maybe these can be located in ddp/manuals.xml/tools/ and each user is
asked to check out this directory as well (no longer need to create
symlinks as it hapended currently on www-master to support Asian PDF
files of release-notes)?
> 2. Makefile
>
> What is the requirements for the makefile?
As far as I know you need only a publish: target which should evaluate
the PUBLISHDIR := /org/www.debian.org/www/doc/manuals variable. This is
required to install the documents on the web server.
I also suggest you add a clean: target.
Jens
Reply to: