When using the 'manual' latex documentclass, the resulting pdf
documents have blank pages added after contents and at the end of
every chapter. Is there any way to remove those? As an alternative, is
it possible to use the 'howto' class, but have each chapter begin on a
new page?
- Max
If you use the LaTeX classoption "oneside" that should be possible for manual.
Use
latex_elements = {
'classoptions': 'oneside',
}
in conf.py.
cheers,
Georg
Didn't work. The Sphinx documentation states that classoptions is one
of the options that are set automatically, so maybe some other
component resets its value?
- Max
No, it only adds to it if you have set a language that has Babel support.
However, I gave you the wrong option; it should by 'openany' instead of 'oneside'.
Georg
Actually, it looks like the value should be ',openany'. Without that
comma, I get this at the top of the index.tex file:
\documentclass[letterpaper,10ptopenany]{manual}
Once the comma is added, empty pages between chapters are removed :).
There are still blank pages around contents, but I guess that makes
sense when printing this out. Thanks for your help!
- Max
I'm not sure that should behave differently around the ToC or after
chapters; "openany" should do the trick. It doesn't surprise me that
it doesn't either, as when I implemented the stuff to open only on odd
pages, that part clearly demonstrated insufficient LaTeX-fu on my
part.
There are a couple of different bits that determine what the "right"
behavior should be:
1. Number of sides of the paper your printer will be printing on, if
you're actually printing.
If you're only printing on one side of the paper, any blank pages are
simply waste.
2. Whether you want what I've been told is the European style, where
chapters open on any page, or the American, where chapters open on
odd-numbered pages. My understanding is that the blank pages in the
front matter are still appropriate in this case.
I'm guessing sphinx is inheriting this behavior from the original
manual style I put together for the old Python documentation.
-Fred
--
Fred L. Drake, Jr. <fdrake at gmail.com>
"Chaos is the score upon which reality is written." --Henry Miller
I tried both options together, oneside doesn't seem to have any
effect. With openany, there are two blank pages just before and after
the table of contents.
- Max
I said my lack for LaTeX-fu would come into play on this. :-(
If anyone knows how to make it pass those settings along only if it
gets them, that would be great.
> I said my lack for LaTeX-fu would come into play on this. :-(
> If anyone knows how to make it pass those settings along only if it
> gets them, that would be great.
I could find out and maybe even fix the manual.cls latex documentclass.
However, I would rather find out who is in charge of this file.
Alternatively, there should be an option to select a documentclass for LaTeX
output.
Günter
It's in charge of whoever writes patches :)
> Alternatively, there should be an option to select a documentclass for LaTeX
> output.
I agree.
Georg
>> I could find out and maybe even fix the manual.cls latex documentclass.
>> However, I would rather find out who is in charge of this file.
> It's in charge of whoever writes patches :)
* Where to send patches?
* Is manual.cls a part of Sphinx or or Python?
(I find it in both,
/usr/lib/python2.5/doc/texinputs/manual.cls
/usr/lib/python2.5/site-packages/sphinx/texinputs/manual.cls
)
* Who could decide to change the name to be more specific
(python-manual.cls, say).
>> Alternatively, there should be an option to select a documentclass for
>> LaTeX output.
> I agree.
Fine. So I am looking forward to see a "documentclass" config setting
similar to what we have in Docutils' rst2latex:
--documentclass=DOCUMENTCLASS
Specify documentclass. Default is "article".
This could be supplemented with a "stylesheet" setting:
--stylesheet=<file[,file2, ...]> Specify comma separated list of
LaTeX packages/stylesheets.
A style is referenced with \usepackage if
extension is ".sty" or omitted and with \input else.
Günter
Here, or to me directly.
> * Is manual.cls a part of Sphinx or or Python?
>
> (I find it in both,
>
> /usr/lib/python2.5/doc/texinputs/manual.cls
> /usr/lib/python2.5/site-packages/sphinx/texinputs/manual.cls
>
> )
The original was used in 2.5's LaTeX-source documentation, and I adapted it
(quite a lot over time) for Sphinx. I guess that the first you find there
is the original 2.5 doc one (which Debian ships).
> * Who could decide to change the name to be more specific
> (python-manual.cls, say).
I'd say changing it to "sphinx-manual.cls" is not a problem.
>>> Alternatively, there should be an option to select a documentclass for
>>> LaTeX output.
>
>> I agree.
>
> Fine. So I am looking forward to see a "documentclass" config setting
> similar to what we have in Docutils' rst2latex:
>
> --documentclass=DOCUMENTCLASS
> Specify documentclass. Default is "article".
It should be latex_elements['docclass'].
> This could be supplemented with a "stylesheet" setting:
>
> --stylesheet=<file[,file2, ...]> Specify comma separated list of
> LaTeX packages/stylesheets.
> A style is referenced with \usepackage if
> extension is ".sty" or omitted and with \input else.
However, this is already subsumed by latex_elements['preamble'].
Georg
>>>> I could find out and maybe even fix the manual.cls latex documentclass.
>>>> However, I would rather find out who is in charge of this file.
>>> It's in charge of whoever writes patches :)
>> * Where to send patches?
> Here, or to me directly.
I'll see what I can do.
----
>>>> Alternatively, there should be an option to select a documentclass for
>>>> LaTeX output.
>>> I agree.
>> Fine. So I am looking forward to see a "documentclass" config setting
>> similar to what we have in Docutils' rst2latex:
>> --documentclass=DOCUMENTCLASS
>> Specify documentclass. Default is "article".
> It should be latex_elements['docclass'].
Why docclass instead of the established name documentclass (used in LaTeX
and Docutils)?
>> This could be supplemented with a "stylesheet" setting:
>> --stylesheet=<file[,file2, ...]> Specify comma separated list of
>> LaTeX packages/stylesheets.
>> A style is referenced with \usepackage if
>> extension is ".sty" or omitted and with \input else.
> However, this is already subsumed by latex_elements['preamble'].
But 'preamble' expects raw LaTeX code (if I remember right).
So, are Sphinx and Docutils inevitabely drifting apart?
Günter
Thanks!
>>>>> Alternatively, there should be an option to select a documentclass for
>>>>> LaTeX output.
>
>>>> I agree.
>
>>> Fine. So I am looking forward to see a "documentclass" config setting
>>> similar to what we have in Docutils' rst2latex:
>
>>> --documentclass=DOCUMENTCLASS
>>> Specify documentclass. Default is "article".
>
>> It should be latex_elements['docclass'].
>
> Why docclass instead of the established name documentclass (used in LaTeX
> and Docutils)?
It's already there :)
>>> This could be supplemented with a "stylesheet" setting:
>
>>> --stylesheet=<file[,file2, ...]> Specify comma separated list of
>>> LaTeX packages/stylesheets.
>>> A style is referenced with \usepackage if
>>> extension is ".sty" or omitted and with \input else.
>
>> However, this is already subsumed by latex_elements['preamble'].
>
> But 'preamble' expects raw LaTeX code (if I remember right).
Yes.
> So, are Sphinx and Docutils inevitabely drifting apart?
It won't "drift apart" more with this change; Sphinx has always had a
different approach to configuration, using conf.py instead of options to
sphinx-build, and this should not be an exception.
cheers,
Georg
>>>>>> Also, it loads the 'report' standard LaTeX documentclass with the
>>>>>> "openright" option hard-coded
>> ...
>>>>> If anyone knows how to make it pass those settings along only if it
>>>>> gets them, that would be great.
...
While possible (with some LaTeX magic), the most easy and maintable
method will be to provide "openright" and "twoside" as default settings
configurable via config.py [#]_ and call the "report" documentclass
without options.
_[#] either modify the 'classoptions' so that the "special named" class
options are appended to a customizable prefix or provide separate
keys to the latex_elements.
See patch below.
>> * Is manual.cls a part of Sphinx or or Python?
...
> The original was used in 2.5's LaTeX-source documentation, and I adapted it
> (quite a lot over time) for Sphinx. I guess that the first you find there
> is the original 2.5 doc one (which Debian ships).
>> * Who could decide to change the name to be more specific
>> (python-manual.cls, say).
> I'd say changing it to "sphinx-manual.cls" is not a problem.
Please do so, as in the LaTeX world, it is common to rename any modified
versions (in many cases it is even mandated by the License). This prevents
nasty surprises with things not working as expected.
thanks,
Günter
Suggestion for sphinx-manual.cls::
--- /usr/share/sphinx/texinputs/manual.cls 2009-03-24 21:51:15.000000000 +0100
+++ /Test/sphinx-manual.cls 2009-05-06 14:26:46.000000000 +0200
@@ -1,14 +1,14 @@
%
-% manual.cls for Sphinx
+% Default document class for Sphinx (http://sphinx.pocoo.org/)
%
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesClass{manual}[2008/10/18 Document class (Sphinx manual)]
+\ProvidesClass{sphinx-manual}[2009/05/06 Document class (Sphinx manual)]
% Pass all given class options to the parent class.
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{report}}
\ProcessOptions\relax
-\LoadClass[twoside,openright]{report}
+\LoadClass{report}
% Set some sane defaults for section numbering depth and TOC depth. You can
% reset these counters in your preamble.
>>>>>>> Also, it loads the 'report' standard LaTeX documentclass with the
>>>>>>> "openright" option hard-coded
> While possible (with some LaTeX magic), the most easy and maintable
> method will be to provide "openright" and "twoside" as default settings
> configurable via config.py [#]_ and call the "report" documentclass
> without options.
With help of the comp.text.tex list, I got a working version of the required
"LaTeX magic"::
%
% Default document class for Sphinx (http://sphinx.pocoo.org/)
% extending the 'report' standard class.
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
\ProvidesClass{sphinx-manual}[2008/10/18 Document class (Sphinx manual)]
% 'oneside' option overriding the 'twoside' default
\newif\if@oneside
\DeclareOption{oneside}{\@onesidetrue}
% Pass remaining document options to the parent class.
\DeclareOption*{\PassOptionsToClass{\CurrentOption}{report}}
\ProcessOptions\relax
% Defaults
% two-side document
\if@oneside
% nothing to do (this is the default in report class)
\else
\PassOptionsToClass{twoside}{report}
\fi
% chapters starting at odd pages (overridden by 'openany' document option)
\PassOptionsToClass{openright}{report}
\LoadClass{report}
<... rest of manual.cls ....>
Günter
Cool! I'll test and include this soon.
Georg