[rsyslog] Suggestion for Documentation Reconstructure
Ryo Fujita
rfujita at redhat.com
Fri Jul 18 04:19:53 CEST 2008
Hi,
As I found an excellent template in the SRPM of docbook2X package,
I'm rewriting the two man pages, rsyslogd.8 and rsyslog.conf.5.
First of all, let me finish the work related to man pages.
I hope Rainer-san and other contributors devote yourself to make
rsyslog better :)
Best Rio.
On 2008/07/18, at 1:33, Rainer Gerhards wrote:
> I still haven't found the time to have an in-depth look at docbook,
> but
> I strongly tend to agree to Michael's conclusion. It looks like a
> problem solver for some ugly problems I am facing.
>
> I will probably re-evaluate the release goal for 3.21.x. It may happen
> that I push back the script engine evolution to after summer to do
> some
> cleanup, performance improvement, doc work and maybe a rewrite of the
> file output handler. I find it a bit hard to think what is more
> important, but I think we can stay with the non-scriptable config for
> two more month. Maybe I can add custom functions as a smaller
> improvement sometime while doing the other things.
>
> In any case, I am happy to have Rio-san over here and as such
> someone to
> ask for solutions to the doc problem. Thanks a lot!
>
> Rainer
>
> On Thu, 2008-07-17 at 16:32 +0200, Michael Biebl wrote:
>> Hi,
>>
>> I just wanted to say, that I like the idea of using docbook/xml to
>> generate the (html) documentation (and possibly the man pages).
>> Imo this would make the documentation more consistent (consistent
>> font
>> sizes, headers, footers etc.), more usable (You'd get something
>> like a
>> TOC and possibly better cross-linking) and perhaps easier keeping
>> up-to-date.
>>
>> Cheers,
>> Michael
>>
>>
>> 2008/7/10 Ryo Fujita <rfujita at redhat.com>:
>>> 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
>>> ########################################################################
>>>
>>> _______________________________________________
>>> rsyslog mailing list
>>> http://lists.adiscon.net/mailman/listinfo/rsyslog
>>>
>>
>>
>>
>
> _______________________________________________
> 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
########################################################################
More information about the rsyslog
mailing list