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

[Stephane Wirtel]

Hi all,

The rst is a simple format as like as markdown. You can write your text in Japanese via UTF8.

Sphinx can generate a PDF, HTML, ePub and man pages format.

For the PDF, sphinx uses latex as a backend and latex can generate a document in Japanese.

Sphinx can manage  i18n it can extract the text and provides a directory for the others languages.

About the anchors, there is no problem with sphinx and restructured text.

I converted the original HTML file to the restructured text  format with pandoc.

After, I had to change the tables and the anchors because pandoc didn't correctly translate the tables and the anchors.

Please, I would like you to read two websites. 
sphinx-doc.org
And http://flask.pocoo.org/

The flask project uses the sphinx doc generator and
generates a PDF and HTML docs. There is a style
for the generated documentation.

For the translation in Japanese, I think you can check
this link.

http://sphinx-users.jp/doc10/


Best regards,

Stephane 


On 15 août 2013, at 02:39 AM, Tatsuo Ishii <ishii at postgresql.org> wrote:

>> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.pgpool.net/pipermail/pgpool-general/attachments/20130815/20f170fd/attachment.htm>