Mailing List Archive

Hello,


On Thu, Aug 21, 2008 at 02:07:40AM +0900, Satoru SATOH wrote:
> Could you please take some time to review these and merge them?

Of course, my patches change many and don't think easy to merge nor am
not sure accetable enhancement in the first place.

Please let me know if you have any issues on them, I'll work to fix
them as far as I can.

- satoru

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).

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.

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.
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)?

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)?

Please advise.

Thanks,
Rainer


On Thu, 2008-08-21 at 02:07 +0900, Satoru SATOH wrote:
> Hello,
>
>
> I posted the first patch but it seems the patch was too big to post. I
> list them here at once.
>
> Could you please take some time to review these and merge them?
>
>
> I splitted origianl big patch into minimum units. However, to complete
> to man-i18n support, the following patches must be applied in this
> order.
>
> All of the patches below are available from
> http://www.gnome.gr.jp/~ss/t/rsyslog/.
>
>
> 1. 0001-man-i18n-move-man-files-from-tools-to-man-C.patch
>
> This patch just moves man files from tools/ to man/C/ (new dir to hold
> man related stuff) and update related Makefile.am files.
>
>
> 2. 0002-man-i18n-add-man-ja.patch
>
> This patch creates new dir, man/ja/ and Makefile.am in it.
>
> There are no man files in it and this should not have harmful effects
> for build process at all, I guess.
>
>
> 3. 0003-man-i18n-add-man-ja.patch
>
> This patch adds man files in man/ja and update Makefile.am in it to
> install these.
>
>
> 4. 0004-man-i18n-add-docbook-xml-sources-for-man-files.patch
>
> This patch adds docbook XML sources for man pages.
>
>
> 5. 0005-man-i18n-add-m4-macros-in-m4-and-make-aclocal-look.patch
>
> This patch adds m4 macros in m4/ and make aclocal look for this dir.
>
> These m4 files are not evaluated in actual and this should not have
> adverse effect at all, I guess.
>
>
> 6. 0006-man-i18n-add-build-process-of-man-pages-in-Makefile.patch
>
> This patch adds transformation process of man pages and po files in
> Makefile.am.
>
> Added part are in "if ENABLE_REGENERATE_MAN ... endif" and
> ENABLE_REGENERATE_MAN is not defined at this point, so this also should
> not have side effects.
>
>
> 7. 0007-man-i18n-add-enable-regenerate-man-option-for-con.patch
>
> This is the last one. This patch adds "--enable-regenerate-man"
> configure option to enable man build process.
>
> This option is disabled by default and should not affect normal build
> process, I think.
>
>
> 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

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 <xxxxyyyyy at example.com>\n"
"Language-Team: German <LL at li.org>\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

Hi,

just curious: Are you also working on getting the other documentation
in doc/ converted to docbook?
Something like [1] would be awesome for rsyslog and I think with
docbook, pdf would just be another output format, right?

While it is great to have documentation at all, the current one is a
bit inconsistent and hard to navigate.


Cheers,
Michael

[1] http://www.exim.org/exim-pdf-current/doc/spec.pdf
--
Why is it that all of the instruments seeking intelligent life in the
universe are pointed away from Earth?

Hi,

Yes, I'm converting other documentation in doc/ to DocBook xml.
# About 40 docs out of 90 has been converted.

But there are some issues to convert and restructure them,
I consult with Rainer-san out of the ML.

Best Rio.

On 2008/09/05, at 5:53, Michael Biebl wrote:

> Hi,
>
> just curious: Are you also working on getting the other documentation
> in doc/ converted to docbook?
> Something like [1] would be awesome for rsyslog and I think with
> docbook, pdf would just be another output format, right?
>
> While it is great to have documentation at all, the current one is a
> bit inconsistent and hard to navigate.
>
>
> Cheers,
> Michael
>
> [1] http://www.exim.org/exim-pdf-current/doc/spec.pdf
> --
> Why is it that all of the instruments seeking intelligent life in the
> universe are pointed away from Earth?
> _______________________________________________
> rsyslog mailing list
> http://lists.adiscon.net/mailman/listinfo/rsyslog

########################################################################
Ryo Fujita <rfujita at redhat.com>
Senior Solution Architect, RHCE
Red Hat K.K.
TEL +81-3-5798-8500
FAX +81-3-5798-8599
Ebisu Neonato 8F
4-1-18 Ebisu, Shibuya-ku,
Tokyo Japan 1500013
########################################################################

Just one additional note:

> While it is great to have documentation at all, the current one is a
> bit inconsistent and hard to navigate.

Suggestions for improvement are welcome ;)

Rainer

Hi,

first of all, many thanks for your continued help. Please let me say
that I so far have very little experience with i18n/l10n under linux and
so may sometimes misunderstand something ;) Your detailled instructions
help much. The rest inline...

Rainer

On Fri, 2008-09-05 at 05:31 +0900, Satoru SATOH wrote:
> Hi,
> > 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.

I agree that this may be a problem. However, I don't think it is a very
serious one. I myself have contributed to some projects where I could
not build the documentation. This did not cause any trouble to me while
working at the program sources. Of course, if I would like to create a
full tarball, I need to have everything in place. But only few actually
needs this (am I right here?).

In contrast, the tarball must include the generated mans, as the average
user can not be expected to have the tools at hand (while we still
expect him to have everything at hand necessary to compile the program
sources).

So I would remove the files from git, but leave them within the
distribution source tarball.

> > 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.

Could you please elaborate a bit on this? Does that mean that the
generated man files (after doing a "make") can not be immediately be
used and need some kind of (manual?) post-processing?

>
> 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.

thanks for the detailed instructions, I'll first do a lab to get some experience first (plus read a bit more in various docs) and post questions when/if they come up.

Hi,


On Fri, 2008-09-05 at 05:31 +0900, Satoru SATOH wrote:
> [snip]

Thanks again for the good description. I think I now understand the
process, but I would like to make sure I really do.

First of all, there seems to be a minor nit with the current set of
files. Please have a look at what happens here:

--------------------------------
[root at rgf9dev rsyslog]# xml2po -v
0.12.2
[root at rgf9dev rsyslog]# make -C man/ja create-pot
make: Entering directory `/home/rger/proj/rsyslog/man/ja'
/usr/bin/xml2po -e -o rsyslogd.8.pot ../C/rsyslogd.8.xml
Traceback (most recent call last):
File "/usr/bin/xml2po", line 856, in <module>
doSerialize(doc)
File "/usr/bin/xml2po", line 589, in doSerialize
outtxt += doSerialize(child)
File "/usr/bin/xml2po", line 583, in doSerialize
(starttag, content, endtag, translation) = processElementTag(node,
repl, 1)
File "/usr/bin/xml2po", line 525, in processElementTag
translation = translation.replace('<placeholder-%d/>' % (i),
replacement)
UnicodeDecodeError: 'ascii' codec can't decode byte 0xe2 in position
4930: ordinal not in range(128)
make: *** [rsyslogd.8.pot] Error 1
make: Leaving directory `/home/rger/proj/rsyslog/man/ja'
----------------------------------

Do you have an idea how I can find out what exactly to fix (I think I
understand that there is in invalid character in rsyslogd.8.xml, but the
error message is not very helpful at pointing me at the actual trouble
source ;)).

From an upper level view, I now understand the workflow as follows:

When I update the documentation, I update the files in ./man/C. These
are kept in docbook format and these are the only sources for the
English language documentation.

After I have updated these files, every translator needs to run

$ make -C man/<lang> update-po

to update the PO files. The translators will work on the .po files only.
When they are (sufficiently ;)) finished, the man files need to be
regenerated. Let me elaborate a bit on this process, I'd like to get to
some details.

As far as I understand, this results in the .po files being converted
back to docbook. Then, docbook is used to generate the ultimate
destination, e.g. the man files. The same process is used to generate
the English files, except that the docbook tools are run directly,
because there were no interim .po files.

Is this description correct? I am asking because I think it would make
sense to generate different formats (man, html, pdf at least) from the
same set of source files. So I understand that .po is just an interim
step which makes translation easier, but there will be a translated
version which in turn can be processed into any format that docbook
tools support.

I'd greatly appreciate your feedback. If you know how to do it, I would
also greatly appreciate if you could provide me a patch (or
instructions) on how to generate pdf from the "man files".

Thanks,
Rainer


> > 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 <xxxxyyyyy at example.com>\n"
> "Language-Team: German <LL at li.org>\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

Hi,

On Fri, Sep 05, 2008 at 04:01:41PM +0200, Rainer Gerhards wrote:
> First of all, there seems to be a minor nit with the current set of
> files. Please have a look at what happens here:
>
> --------------------------------
> [root at rgf9dev rsyslog]# xml2po -v
> 0.12.2
> [root at rgf9dev rsyslog]# make -C man/ja create-pot
> make: Entering directory `/home/rger/proj/rsyslog/man/ja'
> /usr/bin/xml2po -e -o rsyslogd.8.pot ../C/rsyslogd.8.xml
(snip)
> UnicodeDecodeError: 'ascii' codec can't decode byte 0xe2 in position
> 4930: ordinal not in range(128)
> make: *** [rsyslogd.8.pot] Error 1
> make: Leaving directory `/home/rger/proj/rsyslog/man/ja'
> ----------------------------------
> Do you have an idea how I can find out what exactly to fix (I think I
> understand that there is in invalid character in rsyslogd.8.xml, but the
> error message is not very helpful at pointing me at the actual trouble
> source ;)).

This is an well-known annoying issue of python. 'ascii' is the default
internal encoding so that this happens.

There are many ways to "fix" this but to upgrade the latest
gnome-doc-utils (0.13.1; this problem is solved already), looks the
best.

> >From an upper level view, I now understand the workflow as follows:
>
> When I update the documentation, I update the files in ./man/C. These
> are kept in docbook format and these are the only sources for the
> English language documentation.
>
> After I have updated these files, every translator needs to run
>
> $ make -C man/<lang> update-po
>
> to update the PO files. The translators will work on the .po files only.

correct if [s]he or other made the required files (PO) already.

> When they are (sufficiently ;)) finished, the man files need to be
> regenerated. Let me elaborate a bit on this process, I'd like to get to
> some details.
>
> As far as I understand, this results in the .po files being converted
> back to docbook. Then, docbook is used to generate the ultimate
> destination, e.g. the man files. The same process is used to generate
> the English files, except that the docbook tools are run directly,
> because there were no interim .po files.

exactly. DocBook XML files just play an intermediate format role

a. to generate man pages (result)
b. to generate POT (and PO indirectly) to facilitate translation

> Is this description correct? I am asking because I think it would make
> sense to generate different formats (man, html, pdf at least) from the
> same set of source files. So I understand that .po is just an interim
> step which makes translation easier, but there will be a translated
> version which in turn can be processed into any format that docbook
> tools support.

absolutely correct.

> I'd greatly appreciate your feedback. If you know how to do it, I would
> also greatly appreciate if you could provide me a patch (or
> instructions) on how to generate pdf from the "man files".
(snip)

OK, I'll try to make it. wait for a while, please.

Unfortunatelly, xml to pdf transformation process is much complicate
than html/man/other text based formats and it brings another
dependencies - fonts and XSL-FO processor :-P

- satoru

On Fri, Sep 05, 2008 at 10:42:03AM +0200, Rainer Gerhards wrote:
> > 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.
>
> I agree that this may be a problem. However, I don't think it is a very
> serious one. I myself have contributed to some projects where I could
> not build the documentation. This did not cause any trouble to me while
> working at the program sources. Of course, if I would like to create a
> full tarball, I need to have everything in place. But only few actually
> needs this (am I right here?).

right. Who needs required tools and files are

a. developers do git-pull *and* modify man sources
b. translators contribute initial translation or update it
c. others just want ;-) to switch on '--enable-regenerate-man' option

> In contrast, the tarball must include the generated mans, as the average
> user can not be expected to have the tools at hand (while we still
> expect him to have everything at hand necessary to compile the program
> sources).
(snip)

This should be accomplished already, I think.

I made all related stuff (xml, po, man) in EXTRA_DIST so that these will
be in the archive generated by 'make dist'.

> > Actually, man files generated from docbook xml files are slightly
> > different from original man files ATM. These need some refactoring.
>
> Could you please elaborate a bit on this? Does that mean that the
> generated man files (after doing a "make") can not be immediately be
> used and need some kind of (manual?) post-processing?

No. There should be no any problems to convert xml files to man pages
but the result *looks* may different.

Transition from man (roff) to DocBook XML is similar to the transition
from old HTML to XHTML + CSS. The authors/editors/writers have to
concentrate attention at the *logical* structure of the text instead of
its appearance.

It's typical that many HTML tags to control appearance found in old HTML
sources and it makes impossible to keep complete same look in new XHTML
+ CSS sources.

- satoru

Hi,

thanks again for your insight. I'll now remove the (generated) man files
from git, but will leave them inside the tarball. I think that is a
workable solution.

Rainer

> -----Original Message-----
> From: rsyslog-bounces at lists.adiscon.com [mailto:rsyslog-
> bounces at lists.adiscon.com] On Behalf Of Satoru SATOH
> Sent: Friday, September 05, 2008 6:00 PM
> To: rsyslog-users
> Subject: Re: [rsyslog] [PATCH] man-i18n patches summary
>
> On Fri, Sep 05, 2008 at 10:42:03AM +0200, Rainer Gerhards wrote:
> > > 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.
> >
> > I agree that this may be a problem. However, I don't think it is a
> very
> > serious one. I myself have contributed to some projects where I
could
> > not build the documentation. This did not cause any trouble to me
> while
> > working at the program sources. Of course, if I would like to create
> a
> > full tarball, I need to have everything in place. But only few
> actually
> > needs this (am I right here?).
>
> right. Who needs required tools and files are
>
> a. developers do git-pull *and* modify man sources
> b. translators contribute initial translation or update it
> c. others just want ;-) to switch on '--enable-regenerate-man' option
>
> > In contrast, the tarball must include the generated mans, as the
> average
> > user can not be expected to have the tools at hand (while we still
> > expect him to have everything at hand necessary to compile the
> program
> > sources).
> (snip)
>
> This should be accomplished already, I think.
>
> I made all related stuff (xml, po, man) in EXTRA_DIST so that these
> will
> be in the archive generated by 'make dist'.
>
> > > Actually, man files generated from docbook xml files are slightly
> > > different from original man files ATM. These need some
refactoring.
> >
> > Could you please elaborate a bit on this? Does that mean that the
> > generated man files (after doing a "make") can not be immediately be
> > used and need some kind of (manual?) post-processing?
>
> No. There should be no any problems to convert xml files to man pages
> but the result *looks* may different.
>
> Transition from man (roff) to DocBook XML is similar to the transition
> from old HTML to XHTML + CSS. The authors/editors/writers have to
> concentrate attention at the *logical* structure of the text instead
of
> its appearance.
>
> It's typical that many HTML tags to control appearance found in old
> HTML
> sources and it makes impossible to keep complete same look in new
XHTML
> + CSS sources.
>
> - satoru
> _______________________________________________
> rsyslog mailing list
> http://lists.adiscon.net/mailman/listinfo/rsyslog