[rsyslog] Suggestion for Documentation Reconstructure
Rainer Gerhards
rgerhards at hq.adiscon.com
Thu Jul 17 18:33:38 CEST 2008
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
> >
>
>
>
More information about the rsyslog
mailing list