Hi,
On Thu, Sep 04, 2008 at 11:52:40AM +0200, Rainer Gerhards wrote:
> Hi,
>
> I was now able to apply the patch series - many thanks. It is currently
> in the docbook branch, which is also available on my public git server
> (so that others can follow).
Thanks!
> I am digging into what the patches actually do and, not surprisingly, I
> finally need to learn a bit more about docbook to fully understand it
> (looks like this gets my prime activity for the time being ;)).
>
> One thing I already noticed. The man pages are generated via the
> --enable-regenerate-man switch, but they are also in git. So when I
> regenerate them, this results in a large volume of git changes.
Right.
> In my POV, the man pages are now output files and as such no longer
> something that belongs into git. I understand that this has the
> implication that when I remove them from git, everyone who pulls the git
> archive needs to have the proper tools in place to generate the doc.
Exactly. Addtional requirements are the followings.
- xslt processor, xsltproc
- xml validator, xmllint
- properly configured xml catalog or internet access
- docbook xml dtd (local or remote)
- docbook xsl stylesheet for docbook-to-man transformation (local or
remote)
- xml2po in gnome-doc-utils (optional; must for translators)
I thought that not all of developers have such system and so that this
should be avoided. This is why I disabled man-regeneration process by
default.
> However, is this really a problem? AFAIK other projects have similar
> demands. So I would prefer to remove the man pages themselves from git
> (but of course not from autotools config files, so that they be still
> present in a release tarball).
>
> Does this sound reasonable? Any objections (from anyone)?
One thing i have to mention.
Actually, man files generated from docbook xml files are slightly
different from original man files ATM. These need some refactoring.
If it's not a matter, it would be ok.
> I also have not yet fully understood the translation workflow. If
> the ./ja subdirectory is copied, doesn't it (soon) contain the Japanese
> version? If so, shouldn't any other subdirectory be copied (e.g. an ./en
> be created with the English source doc, which I maintain)?
It is a little much complicated than that. Here are example steps for
german (de) man pages.
[initial translation]
1. create mandir and makefile.am in it
$ mkdir man/de && \
sed 's/LANG = ja/LANG = de/' man/ja/Makefile.am > \
man/de/Makefile.am
2. add man/de/ to SUBDIRS in man/Makefile.am
$ sed -i 's/^\(SUBDIRS.*\)/\1 de/' man/Makefile.am
3. add man/de/Makefile.am to AC_CONFIG_FILES in configure.ac
4. generate man/de/Makefile.am
$ autoreconf -vfi && ./configure --prefix=$(pwd)/i \
--enable-regenerate-man
5. generate POT (PO template; language independent) and rename it
$ make -C man/de create-pot
$ mv man/de/rsyslog.conf.5.pot man/de/rsyslog.conf.5.po
$ mv man/de/rsyslogd.8.pot man/de/rsyslogd.8.po
6. edit necessary header fields in PO files
$ vim man/de/rsyslog.conf.5.po
$ cat man/de/rsyslog.conf.5.po
msgid ""
msgstr ""
"Project-Id-Version: rsyslog HEAD\n"
"POT-Creation-Date: 2008-09-05 04:41+0900\n"
"PO-Revision-Date: 2008-09-05 05:01+0900\n"
"Last-Translator: XXXXX YYYYY <[EMAIL PROTECTED]>\n"
"Language-Team: German <[EMAIL PROTECTED]>\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
(snip)
7. translate PO files
8. generate man files
$ ./configure --prefix=$(pwd)/i --enable-regenerate-man && make
[update translations]
1. update PO to follow changes in original docbook xml files
$ make -C man/de update-po
Please refer to man/ja/Makefile.am also.
BTW, "C" (man/C) means C (English) locale. This is the traditional dir
name to keep original English message catalogs, I think.
- satoru
(snip)
> > How to build:
> >
> > To enable the man build process, configure have to be regenerated:
> >
> > $ (autoreconf -vfi && \
> > ./configure --enable-regenerate-man [...other options] && \
> > make && make install
> >
> >
> > Translator's workflow:
> >
> > a. initial translation:
> >
> > 0. arrange lang dir, that is, cp man/ja to man/YOUR_LANG/ and edit
> > Makefile.am; s/ja/YOUR_LANG/.
> > 1. create POT: make -C man/YOUR_LANG/ create-pot
> > 2. copy POT to PO and translate it
> > 3. run make
> >
> > b. maintanance:
> >
> > 1. update PO: make -C man/YOUR_LANG update-po
> > 2. update translations
> > 3. just run make
> >
> >
> > Requirements for man regeneration / translation:
> >
> > xmllint, xsltproc, xml2po in gnome-doc-utils, DocBook DTD and DocBook
> > xslt stylesheet for man pages are required.
> >
> > If xmlcatalog (e.g. /etc/xml/catalog) is configured appropriately,
> > both xmllint and xsltproc will use local DTD and stylsheet files
> > instead of these from remote site
> > (http://www.oasis-open.org/docbook/...).
> >
> >
> > - satoru
_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
