[rsyslog] Suggestion for Documentation Reconstructure

[Ryo Fujita]

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