[rsyslog] Suggestion for Documentation Reconstructure

[Rainer Gerhards]

Hi Rio-san,

I need to leave soon, but a quick feedback: the proposal looks *very*
interesting. I need to digest it a bit. I have no experience with
DocBook, so I probably need to check that out, first. That may take a
short while (should you happen to know a good "getting started guide",
I'd grateful if you send me a link ;)). From first thought, I would
prefer to generate the html et al outputs from a single source (where
only that source is in git).

Feedback from other list members is also appreciated.

Rainer
> -----Original Message-----
> From: rsyslog-bounces at lists.adiscon.com [mailto:rsyslog-
> bounces at lists.adiscon.com] On Behalf Of Ryo Fujita
> Sent: Thursday, July 10, 2008 8:51 AM
> To: rsyslog-users
> Subject: [rsyslog] Suggestion for Documentation Reconstructure
> 
> Hi List,
> 
> I consulted with my colleagues about the smartest way to reconstruct
> the documents of rsyslog.
> 
> 1.Work Flow matter
> The attached image is just an idea for rational flowchart to make
> translation easier.
> #If this ML forbids me to attach any files, you can see it on my site.
> http://rio.tc/2008/07/10-144007.php
> 
> I'm worried that this flow will give the contributers much trouble.
> 
> - HTML(from Wiki) to DocBook conversion
>    'tidy' will help us a little, but exporter of media Wiki is poor to
> export 'well-formed HTML'.
>    We need to edit and check them manually.
>    Of course, I willingly do this. But it may take a number of days.
> 
> - Writers need to edit DocBook XML after the reconstruction.
>    As you know, HTML format is not good for a source of multi-output.
>    DocBook XML is a perfect one except for edit :)
> 
> - Automake related matter
>    There can be two streams to generate man and html from DocBook XML.
>    One : When you edit DocBook, you commit DocBook, HTML and man files
> to git tree.
>               Of course this method requires us to prepare an
> environment where you can use xsltproc/docbook2man.
>    Two : By adding some sequences into Makefile, HTML and man files
> can be generated automatically.
>               All persons who want to build rsyslog from tar ball need
> to prepare the environment.
>               And we need to put some check routines for dependencies
> into Makefile.
> 
> 2.git tree reconstruct only with 'doc' directory
> 
> `-- doc
>      |-- Makefile.am
>      |-- conf
>      |   |-- en
>      |   |   `-- rsyslog-example.conf
>      |   |-- OTHER_LANGUAGES(iso code)
>      |   `-- jp
>      |       `-- rsyslog-example.conf # annotations are translated.
>      |-- html
>      |   |-- en
>      |   |   |-- bugs.html
>      |   |   |-- OTHER_HTMLS
>      |   |   `-- version_naming.html
>      |   |-- OTHER_LANGUAGES(iso code)
>      |   `-- jp
>      |       |-- bugs.html
>      |       |-- OTHER_HTMLS
>      |       `-- version_naming.html
>      |-- images
>      |   |-- gssapi.png
>      |   |-- OTHER_IMAGES
>      |   `-- tls_cert_ca.jpg
>      |-- man
>      |   |-- en
>      |   |   |-- man5
>      |   |   |   `-- rsyslog.conf.5
>      |   |   `-- man8
>      |   |       `-- rsyslogd.8
>      |   |-- OTHER_LANGUAGES(iso code)
>      |   `-- jp
>      |       |-- man5
>      |       |   `-- rsyslog.conf.5
>      |       `-- man8
>      |           `-- rsyslogd.8
>      `-- src
>          |-- dias
>          |   |-- classes.dia
>          |   |-- OTHER_DIA_FILES
>          |   `-- tls_cert_ca.dia
>          `-- docbook
>              |-- en
>              |   |-- bugs.xml
>              |   |-- rsyslog.conf.5.xml
>              |   |-- rsyslogd.8.xml
>              |   |-- OTHER_XMLS
>              |   `-- version_naming.xml
>              `-- ja
>                  |-- bugs.html
>                  |-- rsyslog.conf.5.xml
>                  |-- rsyslogd.8.xml
>                  |-- OTHER_XMLS
>                  `-- version_naming.html
> 
> # rsyslog.conf.5 and rsyslogd.8 files will be removed from ./tools/
> directory.
> 
> Your suggestions will be highly appreciated!!
> 
> Best Rio.
> 
>
#######################################################################
> #
> 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
>
#######################################################################
> #