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 <[EMAIL PROTECTED]> Subject: correct language extension for pt_BR? Date: Tue, 1 Feb 2005 23:20:21 +0100 To: [email protected] ) 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 -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
