[rsyslog] Suggestion for Documentation Reconstructure

[Ryo Fujita]

Hi Rainer-san,

DocBook.org is here.
http://www.docbook.org/

And IBM has a good guide for beginners.
http://www.ibm.com/developerworks/xml/library/xml-matters3.html

Recently, Red Hat uses DocBook format to generate web pages ,PDFs and  
so on.
For example,
https://www.redhat.com/docs/manuals/enterprise/
A document having both html and PDF is generated from DocBook.

gnome-doc-utils and kdesdk-utils include very convenient tools to  
handle DocBook and related formats.

Best Rio.

On 2008/07/10, at 16:03, Rainer Gerhards wrote:

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