We are exploring the features of Sphinx in order to rebuild our legacy manuals. We already ported most of the former manual to Sphinx. Now I'm exploring the possibilities to adapt our company styles.
Especially, we would like to change the appearance of the headers and footers in the PDF manual. Including a company logo and changing the appearance of even and odd pages.
Hence, I included the following preamble in my conf.py with a custom pagestyle using the package fancyhdr.
latex_elements = {
'preamble' : '''\
\\pagestyle{fancy}
\\fancyhf{}
\\fancyhead[LE,RO]{My Header}'''
}
Unfortunately, the headers only changes before begin{document}, afterwards the Sphinx Style File sphinx.sty overwrites somehow my settings.
The following snippet from sphinx.sty might cause the issue:
% Redefine the 'normal' header/footer style when using "fancyhdr" package:
\spx#ifundefined{fancyhf}{}{
% Use \pagestyle{normal} as the primary pagestyle for text.
\fancypagestyle{normal}{
\fancyhf{}
\fancyfoot[LE,RO]{{\py#HeaderFamily\thepage}}
\fancyfoot[LO]{{\py#HeaderFamily\nouppercase{\rightmark}}}
\fancyfoot[RE]{{\py#HeaderFamily\nouppercase{\leftmark}}}
\fancyhead[LE,RO]{{\py#HeaderFamily \#title, \py#release}}
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0.4pt}
% define chaptermark with \#chappos when \#chappos is available for Japanese
\spx#ifundefined{#chappos}{}
{\def\chaptermark##1{\markboth{\#chapapp\space\thechapter\space\#chappos\space ##1}{}}}
}
% Update the plain style so we get the page number & footer line,
% but not a chapter or section title. This is to keep the first
% page of a chapter and the blank page between chapters `clean.'
\fancypagestyle{plain}{
\fancyhf{}
\fancyfoot[LE,RO]{{\py#HeaderFamily\thepage}}
\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0.4pt}
}
}
What might be a possible workaround?
The table of contents code (in sphinxmanual.cls) ends up with
\ifdefined\fancyhf\pagestyle{normal}\fi
The comment in sphinx.sty says:
% Use \pagestyle{normal} as the primary pagestyle for text.
Thus the simplest should be for your conf.py setting to overwrite the \fancypagestyle{normal}, just re-issue it to your liking.
You will need to wrap the whole latex in \makeatletter...\makeatother if you use \py#HeaderFamily. And use Python raw strings to avoid having to double all backslashes.
in details, here I copy the original definition to conf.py so that it can be customized from there
latex_elements = {
'preamble': """
\makeatletter
\fancypagestyle{normal}{
\fancyhf{}
\fancyfoot[LE,RO]{{\py#HeaderFamily\thepage}}
\fancyfoot[LO]{{\py#HeaderFamily\nouppercase{\rightmark}}}
\fancyfoot[RE]{{\py#HeaderFamily\nouppercase{\leftmark}}}
\fancyhead[LE,RO]{{\py#HeaderFamily \#title, \py#release}}
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0.4pt}
% define chaptermark with \#chappos when \#chappos is available for Japanese
\spx#ifundefined{#chappos}{}
{\def\chaptermark##1{\markboth{\#chapapp\space\thechapter\space\#chappos\space ##1}{}}}
}
\makeatother
""",
}
Related
I'm a Technical Writer trying to output a Python-Sphinx website into a .pdf via LaTeX. The manual has a safety regulations and environmental compliance section with about 40+ languages in it. These languages all appear as-is in the base file - and .rst files have the same unicode support as .txt, so if Bulgarian renders appropriately in Cyrillic in the base file I'm assuming it's encoded correctly.
I already know to use either LuaLaTeX or XeLaTeX to render unicode properly, and I've already found that TeX files compiled from Sphinx/.rst render better under LuaLaTeX. Even so, under LuaLaTeX, the Greek and Cyrillic don't render at all (nor do accented letters, but for some reason Germanic eth/ð does render).
Everything I've seen on multi-language support involves one of several packages that require you to bracket each section with something like \begin{Russian}, but for all 40+ languages. With the base file being in a different format and the .tex file being generated automatically, every time I update the manual it would save over all the work I've done.
The best solution for me would be to put all the multi-language support in the header, and just say "hey dumb dumb... just render the unicode text as-is". As it is, the auto-generated frontspiece and ToC is unsatisfactory, so I'm keeping the header saved in a separate document and I'm pasting the better header in. Front-loading multi-language support by defining everything in the header is definitely the most ideal solution.
Any help would be good.
The following is the header provided by Python-Sphinx, with minor adjustments:
%% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\ifdefined\pdfpxdimen
\let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=.75bp\relax
\ifdefined\pdfimageresolution
\pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax
\fi
%% let collapsible pdf bookmarks panel have high depth per default
\PassOptionsToPackage{bookmarksdepth=5}{hyperref}
\PassOptionsToPackage{warn}{textcomp}
\usepackage[utf8]{inputenc}
\ifdefined\DeclareUnicodeCharacter
% support both utf8 and utf8x syntaxes
\ifdefined\DeclareUnicodeCharacterAsOptional
\def\sphinxDUC#1{\DeclareUnicodeCharacter{"#1}}
\else
\let\sphinxDUC\DeclareUnicodeCharacter
\fi
\sphinxDUC{00A0}{\nobreakspace}
\sphinxDUC{2500}{\sphinxunichar{2500}}
\sphinxDUC{2502}{\sphinxunichar{2502}}
\sphinxDUC{2514}{\sphinxunichar{2514}}
\sphinxDUC{251C}{\sphinxunichar{251C}}
\sphinxDUC{2572}{\textbackslash}
\fi
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb,amstext}
\usepackage{babel}
\usepackage{tgtermes}
\usepackage{tgheros}
\renewcommand{\ttdefault}{txtt}
\usepackage[Bjarne]{fncychap}
\usepackage{sphinx}
\fvset{fontsize=auto}
\usepackage{geometry}
% Include hyperref last.
\usepackage{hyperref}
% Fix anchor placement for figures with captions.
\usepackage{hypcap}% it must be loaded after hyperref.
% Set up styles of URL: it should be placed after hyperref.
\urlstyle{same}
\usepackage{sphinxmessages}
\title{...}
\date{\today}
\release{...}
\author{...}
\makeindex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
The document is almost entirely in English except for one dang section near but not at the end:
- Това е българско
- Αυτό είναι ελληνικό
- Tohle je česky
- Bu türkçe
- Þetta er íslenskt
\end{document}
Caveat: This won't give correct hyphenation and other special language settings (e.g. French spacing for punctuation marks), but it will show the text. If you want these other features as well, you will have to deal with babel or polyglossia.
The unicode capabilities of xe- and lualatex only fully unfold if you also use a font which does have a good coverage of symbols.
For example with the Noto Serif font:
% !TeX TS-program = lualatex
%% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\ifdefined\pdfpxdimen
\let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=.75bp\relax
\ifdefined\pdfimageresolution
\pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax
\fi
%% let collapsible pdf bookmarks panel have high depth per default
\PassOptionsToPackage{bookmarksdepth=5}{hyperref}
\PassOptionsToPackage{warn}{textcomp}
\usepackage[utf8]{inputenc}
\ifdefined\DeclareUnicodeCharacter
% support both utf8 and utf8x syntaxes
\ifdefined\DeclareUnicodeCharacterAsOptional
\def\sphinxDUC#1{\DeclareUnicodeCharacter{"#1}}
\else
\let\sphinxDUC\DeclareUnicodeCharacter
\fi
\sphinxDUC{00A0}{\nobreakspace}
\sphinxDUC{2500}{\sphinxunichar{2500}}
\sphinxDUC{2502}{\sphinxunichar{2502}}
\sphinxDUC{2514}{\sphinxunichar{2514}}
\sphinxDUC{251C}{\sphinxunichar{251C}}
\sphinxDUC{2572}{\textbackslash}
\fi
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb,amstext}
\usepackage{babel}
\usepackage{tgtermes}
\usepackage{tgheros}
\renewcommand{\ttdefault}{txtt}
\usepackage[Bjarne]{fncychap}
\usepackage{sphinx}
\fvset{fontsize=auto}
\usepackage{geometry}
% Include hyperref last.
\usepackage{hyperref}
% Fix anchor placement for figures with captions.
\usepackage{hypcap}% it must be loaded after hyperref.
% Set up styles of URL: it should be placed after hyperref.
\urlstyle{same}
\usepackage{sphinxmessages}
\title{...}
\date{\today}
\release{...}
\author{...}
\makeindex
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{fontspec}
\setmainfont{Noto Serif}
\begin{document}
The document is almost entirely in English except for one dang section near but not at the end:
- Това е българско
- Αυτό είναι ελληνικό
- Tohle je česky
- Bu türkçe
- Þetta er íslenskt
\end{document}
(to see which fonts on your computer support the characters you want to use, you can use the command line tool albatross, see e.g. https://stackoverflow.com/a/69721465/2777074)
I have a section defined like this:
\section*{\huge Summary}
\label{chap:summary}
And then I use a \ref to it
\nameref{chap:summary}
But the reference also takes the \huge format. How can I remove it?
You should refrain from adding font selections as part of your section title. Instead, rely on packages to manage your formatting. Below I've used secsty to adjust the section font; other options also exist:
\documentclass{article}
\usepackage{sectsty,nameref}
\sectionfont{\huge}
\begin{document}
\section*{Summary}\label{chap:summary}
See section \nameref{chap:summary}.
\end{document}
Can anyone recommend me a good template to include C source code with line numbering
in Latex? For example, taking the classical Hello world program, I would like to make it look as follows:
(1) /* Hello World program */
(2)
(3) #include<stdio.h>
(4)
(5) main()
(6) {
(7) printf("Hello World");
(8) }
Typicall, I always used the verbatim environment, but I am wondering if there is a better and nicer way to do that.
Thanks so much
Richard
As others have said, the listings package will probably do what you want using something like the following:
\lstset{
language=C, % choose the language of the code
numbers=left, % where to put the line-numbers
stepnumber=1, % the step between two line-numbers.
numbersep=5pt, % how far the line-numbers are from the code
backgroundcolor=\color{white}, % choose the background color. You must add \usepackage{color}
showspaces=false, % show spaces adding particular underscores
showstringspaces=false, % underline spaces within strings
showtabs=false, % show tabs within strings adding particular underscores
tabsize=2, % sets default tabsize to 2 spaces
captionpos=b, % sets the caption-position to bottom
breaklines=true, % sets automatic line breaking
breakatwhitespace=true, % sets if automatic breaks should only happen at whitespace
title=\lstname, % show the filename of files included with \lstinputlisting;
}
\lstinputlisting{HelloWorld.c}
A more powerful alternative would be to use the minted package, although this will do much more than what you're currently asking, as it uses/requires pygments to be installed on your system so that it can fully tokenize the code you give it.
You might want to have a look at the listings package. It is very flexible and easy to use.
Take a look at Code listings in LaTeX. You'll find a couple of alternatives there. Some options are:
listings
minted
lgrind
Use lgrind package for latex. It converts your code into a .tex file
CWEB had a nice C formatter.
I've been looking at Philip Bunge's post on how to create a "Tango" style with LaTeX listings, and trying to adapt this to make the default text style white and the background black (this is for slides, not an article!). This is what I added:
\definecolor{Black}{gray}{0.0}
\definecolor{White}{gray}{0.9}
...
\lstset{
basicstyle=\color{White},
backgroundcolor=\color{Black},
...
}
This assumes that basicstyle sets the default style of all text. The listings documentation says this:
basicstyle is selected at the beginning of each listing. You could use \footnotesize,
\small, \itshape, \ttfamily, or something like that. The last token of must not read any following characters.
The output of this still shows "default" text as black. It is possible to set more style directives that cover most tokens in a given programming language, but even doing this some tokens (such as brackets and other punctuation) will be missed. What did I do wrong?
The following code worked for me, but I converted the .dvi file to a .pdf in order to have the text appear as white, so it might have been your viewer? I'm using xdvi and xpdf.
\documentclass[a4paper, 11pt]{article}
\usepackage{listings}
\usepackage{color}
\definecolor{theWhite}{gray}{0.9}
\definecolor{theBlack}{gray}{0.0}
\lstset { basicstyle=\color{theWhite}, backgroundcolor=\color{theBlack} }
\begin{document}
\begin{lstlisting}
((lambda (x) `((lambda (x) ,x) ',x)) '`((lambda (x) ,x) ',x))
\end{lstlisting}
\end{document}
I hope that helps!
I have a LaTeX document like this:
\documentclass{article}
\begin{document}
\section{1}
\section{2}
\section{3}
\section{4}
\section{5}
\section{6}
\section{7}
\section{8}
\section{9}
\section{10}
\section{11}
\section{12}
\section{13}
\section{14}
\section{15}
\section{16}
\section{17}
\section{18}
\section{19}
\section{20}
\section{21}
\section{22}
\section{23}
\section{24}
\section{25}
\section{26}
\section{27}
\section{28}
\section{29}
\section{30}
\end{document}
Lots of section headings, but no text in
It produces something like this:
As you can see it keeps all the section headings on one page, and won't break it into 2 pages. Everything above 26 has disappeared off the end of the page.
Is there anyway to get LaTeX to split these sections across multiple pages? I can't easily change the actual content of body, since it's autogenerated. I can change the preamble though. Is there anyway to do this by changing the preamble?
Adding \mbox{} after a section heading would allow the page break. You could introduce it globally in the preamble by:
\makeatletter
\g#addto#macro\#afterheading{\mbox{}}
\makeatother
or
\makeatletter
\expandafter\def\expandafter\#afterheading\expandafter{\#afterheading\mbox{}}
\makeatother
like in this expandafter example.
You should be able to do something like this with the sectsty package