[pgpool-general: 2035] Re: PDF format of the documentation

[Tatsuo Ishii]

> On 08/13, Tatsuo Ishii wrote:
>> > A markdown format or restructured text should be better for the documentation. Do you write the HTML file without a generator ? 
>> 
>> Right. Developers just don't have time to rewrite docs by using
>> markdown format or restructured text.
> I converted the pgpool-en.html file in restructured text with pandoc and
> adjust some parts of the rst document. After I just created a sphinx
> doc and here is the result. This is a prototype of the documentation.
> 
> Please, give me your feedback 

I have briefly looked into this.

- It seems most of anchors are gone. For example:

  p27 "Please refer to replicate_select as well. See also a flow
  chart."  In html file there are anchros for "replcate_select" and
  "flow chart".

- Diagrams are gone. For example, 

  "20.2 Server composition
  Figure below describes how pgpool-II and watchdog process is configured."

  There's no figure in the pdf file.

BTW, Stephane kindly uploaded the rst file at: https://raw.github.com/matrixise/pgpool-doc/master/index.rst

Here are some excerpt from the file. I am not familiar with rst but it
seems writing rst gives less pain than writing raw html.

-------------------------------------------------------------
####################
Welcome to pgpool II
####################

.. toctree::
   :maxdepth: 2

What is pgpool-II?
==================

pgpool-II is a middle ware that sits between PostgreSQL servers and a
PostgreSQL database client. It provides the following features:

* Connection Pooling
* Replication
* Load Balance
* Limiting Exceeding Connections
* Parallel Query
-------------------------------------------------------------

What I am not sure is, the tool chain is available to Japanese and
Chinese as well. If not, there's 0 hope to use rst.

I think migrating from html to rst could be one of the candidates in
the long term in my opinion. I'd love to hear from Chinese document
maintainer Bambo Huang.
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
Japanese: http://www.sraoss.co.jp