Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Is Sphinx better than LaTex in writing manuals/books? [closed]

Only a few people recommended to use Sphinx at the beginning of the year.

Sphinx has developed rather fast recently. I noted today that Sage has made a change from direct editing with LaTex to Sphinx. This is evident in William Stein's answer on 2nd April about Sage's tutorial

The tutorial is not a latex document anymore. It's an entirely different Sphinx document that can output pdf.

It suggests me that Sphinx may be at a level such that it is suitable for me.

Is Sphinx better than LaTex in writing manuals/books?

like image 404
Léo Léopold Hertz 준영 Avatar asked Apr 07 '09 13:04

Léo Léopold Hertz 준영


4 Answers

We wrote a book with sphinx but we had to tweak the tex file produced with a Python script.

Take a look at this thread, in the book building tool section

Here a some changes we made to the original LaTeX file:

  • documentclass = 'book'
  • added frontmatter, mainmatter and backmatter
  • added a new style to fncychap.sty
  • two columns index instead of one columns
  • some changes in the page header
  • everything is black & white
    • links
    • titles
    • images (using imagemagick to convert the images in greyscale)
  • tips and notes displayed in a nicer box with icon
  • better float placement on pages to optimize the space used

We also made minor changes to book.cls and sphinx.sty

With all these tweaks, we are very happy with the result.

like image 115
Oli Avatar answered Sep 22 '22 19:09

Oli


Well, there is at least one book printed using sphinx and rst2pdf

Some sample documents generated via sphinx and rst2pdf here:

http://freedrive.com/folder/236385

And here:

http://freedrive.com/folder/236380

Specially check the python library reference and the django book.

This is output from the development branch and has bugs (for example, the TOC is often on the wrong side of the page) which are being fixed.

like image 45
Roberto Alsina Avatar answered Sep 21 '22 19:09

Roberto Alsina


I prefer Sphinx to Latex for writing manuals for two reasons:

  1. You can build nice HTML, PDF, htmlhelp and qthelp versions of the manual with minimal effort.
  2. reST syntax is faster to write and I find easier to remember (it's more simple)

A book, however, might be a different story. If I wanted to write a book that has only a printed and a pdf version and contains equations and citations I would go with Latex, because I think it is much more mature than reST and I find it easy to customize.

Btw. I have much more experience in using Latex.

like image 31
Matti Pastell Avatar answered Sep 23 '22 19:09

Matti Pastell


It's better for creating reference documentation, not for writing books.

like image 34
vartec Avatar answered Sep 25 '22 19:09

vartec