Re: [Firebird-docs] Experimenting with asciidoc / asciidoctor

[Mark R. <ma...@la...>]

On 16-6-2018 00:05, Norman Dunbar wrote:
> Yes indeed, it does look smart. Unfortunately, the pdf of isql suffers 
> from formatting errors, in justification, Appendix A - second line, 
> first paragraph for example.

I have used the default asciidoctor-pdf theme for generating the PDF, 
and that theme applies align: justify for paragraphs. You just notice it 
specifically for this paragraph, because of the long URL.

> I trie asciidoc and asciidoctor some time back, but I didn't get on with 
> it/them. >
> I used Sphinx-doc for a project a while back, that was much better, but 
> requires Python etc. With github and sphinx you can get an automatic 
> build on commit/push and the pdf, html and epub (I think) can be 
> uploaded automagically to readthedocs.io.

For the jaybird-manual I have setup an automatic build and publish to 
GitHub Pages yesterday (see my other mail for links).

> I use ReStructuredText at work to create version controllable sources 
> for pdf and Word (hack, spit) documents. Currently I convert with Pandoc 
> - which I suspect will read docbook and write asciidoc, if necessary - 
> although it's better to convert to LaTeX, do some editing and then 
> generate the pdf. That gives a much better output.
> 
> I'm rather fond of these plain text sources that can generate almost 
> anything!

Yes, me too.

-- 
Mark Rotteveel