2011/11/30 Olivier Bonaventure <olivier.bonavent...@gmail.com>: > I'm currently using sphinx to write an open-source networking texbook > that explains the principles of computer networks and the TCP/IP > protocol suite. sphinx is really nice because it allows me to focus on > the content without having to think too much about the layout. The > objective is to distribute it as an epub ebook in the coming months. > > The current text is structured in five main chapters (see > http://inl.info.ucl.ac.be/cnp3 for HTML version > entire rst code is available at > https://scm.info.ucl.ac.be/trac/cnp3/browser/book ) > > Unfortunately, a chapter can be long and can contain lots of figures and > exercises. To allow the HTML pages to be easier to download, I'd like to > configure sphinx to generate one HTML page per subsection or > subsubsection instead of the current default of one page per section. > > I could not find a solution until now in the HTML output. Is there a > hidden solution somewhere ? It would be nice to be able to configure > sphinx to split the HTML files at section, subsection, subsubsection or > other boundaries.
I tried once to write my Dipoma thesis in Sphinx, because I thought the same as you do. But I switched back to LaTeX later, rewriting all the stuff again. The reasons are that Sphinx/Docutils is nice for HTML documentations of Programs, but the functionality just lacks some ingredients of LaTeX I really like and miss then: 1) Spanning paragraphs over equations. Paragraphs are in Docutils a nonstructured entity. In depends on the point of view if this is a design mistake or not. For the Sphinx purpose, it might be not, for the (e)paper document it probably is. I do not think we would like to discuss this here again, just to point it out. 2) Global References section. 3) Maths as PNGs (if not using JSMath, what is not an option for ebook readers) not properly aligned in inline text mostly. There migth be some more, but this reasons already drew me away from Sphinx-Docutils for "realworld" publications. I'm still happy to use it for my programming work etc. pp., where it is really ace. [For instance, I don't think it's easy to include ReST written docstrings from modules into a LaTeX document.] epub is, afaik, just a zip archive of XHTML files (or even HTML files, I really don't know) together with some meta information. At least things like this is what I found in my favourite ebook newspaper, Die Zeit. So if you have a decent HTML output it is probably easily possible to turn it into an ebook. But here, please refer to more knowledgable resources for the details; I never did this on my own; I just want to give the pointer. You might want to look into PlasTeX, an tranlator from LaTeX to HTML, which claims that it has proper CSS for aligning the graphics of PNG rendered math. It can also structure the document at a certain level into separate files, afair. Basically PlasTeX seems to be a parser for LaTeX, parsing to XML, and the translation XML => final document seems very flexible. Just give it a try. I will try this myself for my Diploma thesis, but never found the time to look into it so far. http://plastex.sourceforge.net/ I think we all here are just interested in getting our documentation work done, so it is admissible to give a pointer to another, "competing" program suite. [I don't think it can be called competiton after all, since the functionality differs significantly.] Happy writing, Friedrich -- You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to sphinx-dev@googlegroups.com. To unsubscribe from this group, send email to sphinx-dev+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en.
