[rsyslog] Suggestion for Documentation Reconstructure
Michael Biebl
mbiebl at gmail.com
Thu Jul 17 16:32:08 CEST 2008
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
>
--
Why is it that all of the instruments seeking intelligent life in the
universe are pointed away from Earth?
More information about the rsyslog
mailing list