Re: library packaging doc...
Hi Jens, (Hi to Frans too.)
On Sun, Feb 27, 2005 at 02:27:42PM +0100, Jens Seidel wrote:
> 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.
Hmmm... I have not thought through yet but now that we have automatic
XML converter which works without human involvement, we should think
this.
Do you propose to start ddp/manuals.xml/
That is certainly an idea but for junichi's document, it realluy do not
matter where they are. So for now let's not make too many things and
stay in ddp/manuals.sgml/ if junichi needs to start this soon.
Otherwise, let's discuss. Once we decide, we can move it anyway.
> 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 is an issue we need to solve before moving. One simple solution
exist if we decide XML file to be single file for each language.
checkin blank file as initial version for english XML
for each-non-english language
1. checkout english base SGML file in the corresponding version
2. convert english to XML
3. check in this into english XML source tree
4. convert this-non-english XML into XML
5. check in this into non-english XML source tree and insert english
XML version (If not known make it point to initial blank file.)
loop
checkout latest english base SGML file
convert english to XML
This can get complicated once this XML file is splitted into many files
(Can we do kind of file structure for XML?)
Anyway, this can be done with an extension of doc-check. But first, we
need to learn from d-i manual how to build it and how to manage multiple
languages. (I spoke with Frans Pop and he will send me some info soon
on d-i manual).
> 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.
For existing document, this makes sense. Hmmm... maybe we need
ddp/manuals.xml/
But how to organize structure inside is still open question.
> I do not know DocBook but I suggest something like
> ddp/manuals.xml or ddp/manuals.docbook, ...
I like ddp/manuals.xml
> 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, ...
I would say to use full locale like en_US.UTF-8
(For XML, we should use UTF-8 but adding this makes clearler)
But again we must follow d-i experience.
Osamu
Reply to: