diff options
Diffstat (limited to 'doc/latex/sphinx.sty')
| -rw-r--r-- | doc/latex/sphinx.sty | 232 |
1 files changed, 187 insertions, 45 deletions
diff --git a/doc/latex/sphinx.sty b/doc/latex/sphinx.sty index fc75bf3..de6664c 100644 --- a/doc/latex/sphinx.sty +++ b/doc/latex/sphinx.sty @@ -6,7 +6,7 @@ % \NeedsTeXFormat{LaTeX2e}[1995/12/01] -\ProvidesPackage{sphinx}[2018/07/18 v1.8 LaTeX package (Sphinx markup)] +\ProvidesPackage{sphinx}[2019/01/12 v1.8.4 LaTeX package (Sphinx markup)] % provides \ltx@ifundefined % (many packages load ltxcmds: graphicx does for pdftex and lualatex but @@ -82,11 +82,26 @@ % User interface to set-up whitespace before and after tables: \newcommand*\sphinxtablepre {0pt}% \newcommand*\sphinxtablepost{\medskipamount}% +% Space from caption baseline to top of table or frame of literal-block \newcommand*\sphinxbelowcaptionspace{.5\sphinxbaselineskip}% % as one can not use \baselineskip from inside longtable (it is zero there) % we need \sphinxbaselineskip, which defaults to \baselineskip \def\sphinxbaselineskip{\baselineskip}% -% These commands are inserted by the table templates +% The following is to ensure that, whether tabular(y) or longtable: +% - if a caption is on top of table: +% a) the space between its last baseline and the top rule of table is +% exactly \sphinxbelowcaptionspace +% b) the space from last baseline of previous text to first baseline of +% caption is exactly \parskip+\baselineskip+ height of a strut. +% c) the caption text will wrap at width \LTcapwidth (4in) +% - make sure this works also if "caption" package is loaded by user +% (with its width or margin option taking place of \LTcapwidth role) +% TODO: obtain same for caption of literal block: a) & c) DONE, b) TO BE DONE +% +% To modify space below such top caption, adjust \sphinxbelowcaptionspace +% To add or remove space above such top caption, adjust \sphinxtablepre: +% notice that \abovecaptionskip, \belowcaptionskip, \LTpre are **ignored** +% A. Table with longtable \def\sphinxatlongtablestart {\par \vskip\parskip @@ -95,48 +110,76 @@ \LTpre\z@skip\LTpost\z@skip % set to zero longtable's own skips \edef\sphinxbaselineskip{\dimexpr\the\dimexpr\baselineskip\relax\relax}% }% -\def\sphinxatlongtableend{\prevdepth\z@\vskip\sphinxtablepost\relax}% +% Compatibility with caption package +\def\sphinxthelongtablecaptionisattop{% + \spx@ifcaptionpackage{\noalign{\vskip-\belowcaptionskip}}{}% +}% +% Achieves exactly \sphinxbelowcaptionspace below longtable caption \def\sphinxlongtablecapskipadjust - {\dimexpr-\dp\strutbox-\sphinxbaselineskip+\sphinxbelowcaptionspace\relax}% -% Now for tables not using longtable -\def\sphinxattablestart - {\par - \vskip\dimexpr\sphinxtablepre\relax - }% + {\dimexpr-\dp\strutbox + -\spx@ifcaptionpackage{\abovecaptionskip}{\sphinxbaselineskip}% + +\sphinxbelowcaptionspace\relax}% +\def\sphinxatlongtableend{\prevdepth\z@\vskip\sphinxtablepost\relax}% +% B. Table with tabular or tabulary +\def\sphinxattablestart{\par\vskip\dimexpr\sphinxtablepre\relax}% \let\sphinxattableend\sphinxatlongtableend -% longtable's wraps captions to a maximal width of \LTcapwidth -% so we do the same for all tables +% This is used by tabular and tabulary templates \newcommand*\sphinxcapstartof[1]{% \vskip\parskip \vbox{}% force baselineskip for good positioning by capstart of hyperanchor + % hyperref puts the anchor 6pt above this baseline; in case of caption + % this baseline will be \ht\strutbox above first baseline of caption \def\@captype{#1}% \capstart -% move back vertically to compensate space inserted by next paragraph +% move back vertically, as tabular (or its caption) will compensate \vskip-\baselineskip\vskip-\parskip }% -% use \LTcapwidth (default is 4in) to wrap caption (if line width is bigger) -\newcommand\sphinxcaption[2][\LTcapwidth]{% +\def\sphinxthecaptionisattop{% locate it after \sphinxcapstartof + \spx@ifcaptionpackage + {\caption@setposition{t}% + \vskip\baselineskip\vskip\parskip % undo those from \sphinxcapstartof + \vskip-\belowcaptionskip % anticipate caption package skip + % caption package uses a \vbox, not a \vtop, so "single line" case + % gives different result from "multi-line" without this: + \nointerlineskip + }% + {}% +}% +\def\sphinxthecaptionisatbottom{% (not finalized; for template usage) + \spx@ifcaptionpackage{\caption@setposition{b}}{}% +}% +% The aim of \sphinxcaption is to apply to tabular(y) the maximal width +% of caption as done by longtable +\def\sphinxtablecapwidth{\LTcapwidth}% +\newcommand\sphinxcaption{\@dblarg\spx@caption}% +\long\def\spx@caption[#1]#2{% \noindent\hb@xt@\linewidth{\hss - \vtop{\@tempdima\dimexpr#1\relax + \vtop{\@tempdima\dimexpr\sphinxtablecapwidth\relax % don't exceed linewidth for the caption width \ifdim\@tempdima>\linewidth\hsize\linewidth\else\hsize\@tempdima\fi -% longtable ignores \abovecaptionskip/\belowcaptionskip, so add hooks here -% to uniformize control of caption distance to tables - \abovecaptionskip\sphinxabovecaptionskip - \belowcaptionskip\sphinxbelowcaptionskip - \caption[{#2}]% +% longtable ignores \abovecaptionskip/\belowcaptionskip, so do the same here + \abovecaptionskip\sphinxabovecaptionskip % \z@skip + \belowcaptionskip\sphinxbelowcaptionskip % \z@skip + \caption[{#1}]% {\strut\ignorespaces#2\ifhmode\unskip\@finalstrut\strutbox\fi}% }\hss}% \par\prevdepth\dp\strutbox }% -\def\spx@abovecaptionskip{\abovecaptionskip} -\newcommand*\sphinxabovecaptionskip{\z@skip} -\newcommand*\sphinxbelowcaptionskip{\z@skip} - -\newcommand\sphinxaftercaption -{% this default definition serves with a caption *above* a table, to make sure - % its last baseline is \sphinxbelowcaptionspace above table top - \nobreak +\def\sphinxabovecaptionskip{\z@skip}% Do not use! Flagged for removal +\def\sphinxbelowcaptionskip{\z@skip}% Do not use! Flagged for removal +% This wrapper of \abovecaptionskip is used in sphinxVerbatim for top +% caption, and with another value in sphinxVerbatimintable +% TODO: To unify space above caption of a code-block with the one above +% caption of a table/longtable, \abovecaptionskip must not be used +% This auxiliary will get renamed and receive a different meaning +% in future. +\def\spx@abovecaptionskip{\abovecaptionskip}% +% Achieve \sphinxbelowcaptionspace below a caption located above a tabular +% or a tabulary +\newcommand\sphinxaftertopcaption +{% + \spx@ifcaptionpackage + {\par\prevdepth\dp\strutbox\nobreak\vskip-\abovecaptionskip}{\nobreak}% \vskip\dimexpr\sphinxbelowcaptionspace\relax \vskip-\baselineskip\vskip-\parskip }% @@ -165,6 +208,9 @@ % For highlighted code. \RequirePackage{fancyvrb} \define@key{FV}{hllines}{\def\sphinx@verbatim@checkifhl##1{\in@{, ##1,}{#1}}} +% sphinxVerbatim must be usable by third party without requiring hllines set-up +\def\sphinxresetverbatimhllines{\def\sphinx@verbatim@checkifhl##1{\in@false}} +\sphinxresetverbatimhllines % For hyperlinked footnotes in tables; also for gathering footnotes from % topic and warning blocks. Also to allow code-blocks in footnotes. \RequirePackage{footnotehyper-sphinx} @@ -174,7 +220,13 @@ % For floating figures in the text. Better to load after float. \RequirePackage{wrapfig} % Separate paragraphs by space by default. -\RequirePackage{parskip} +\IfFileExists{parskip-2001-04-09.sty}% since September 2018 TeXLive update +% new parskip.sty, but let it rollback to old one. +% hopefully TeX installation not broken and LaTeX kernel not too old + {\RequirePackage{parskip}[=v1]} +% standard one from 1989. Admittedly \section of article/book gives possibly +% anomalous spacing, but we can't require September 2018 release for some time. + {\RequirePackage{parskip}} % For parsed-literal blocks. \RequirePackage{alltt} % Display "real" single quotes in literal blocks. @@ -499,15 +551,31 @@ \sloppy \hbadness = 5000 % don't print trivial gripes -\pagestyle{empty} % start this way - +% Use \pagestyle{normal} as the primary pagestyle for text. % Redefine the 'normal' header/footer style when using "fancyhdr" package: -% Note: this presupposes "twoside". If "oneside" class option, there will be warnings. -\ltx@ifundefined{fancyhf}{}{ - % Use \pagestyle{normal} as the primary pagestyle for text. - \fancypagestyle{normal}{ +\@ifpackageloaded{fancyhdr}{% + \ltx@ifundefined{c@chapter} + {% no \chapter, "howto" (non-Japanese) docclass + \fancypagestyle{plain}{ + \fancyhf{} + \fancyfoot[C]{{\py@HeaderFamily\thepage}} + \renewcommand{\headrulewidth}{0pt} + \renewcommand{\footrulewidth}{0pt} + } + % Same as 'plain', this way we can use it in template + % FIXME: shouldn't this have a running header with Name and Release like 'manual'? + \fancypagestyle{normal}{ + \fancyhf{} + \fancyfoot[C]{{\py@HeaderFamily\thepage}} + \renewcommand{\headrulewidth}{0pt} + \renewcommand{\footrulewidth}{0pt} + } + }% + {% classes with \chapter command + \fancypagestyle{normal}{ \fancyhf{} -% (for \py@HeaderFamily cf "TITLES") + % FIXME: this presupposes "twoside". + % If "oneside" class option, there are warnings in LaTeX log. \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}} \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}} @@ -517,17 +585,24 @@ % define chaptermark with \@chappos when \@chappos is available for Japanese \ltx@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}{ + % page of a chapter `clean.' + \fancypagestyle{plain}{ \fancyhf{} \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} \renewcommand{\headrulewidth}{0pt} \renewcommand{\footrulewidth}{0.4pt} + } + } + } + {% no fancyhdr: memoir class + % Provide default for 'normal' style simply as an alias of 'plain' style + % This way we can use \pagestyle{normal} in LaTeX template + \def\ps@normal{\ps@plain} + % Users of memoir class are invited to redefine 'normal' style in preamble } -} % geometry \ifx\kanjiskip\@undefined @@ -647,10 +722,38 @@ \setbox\spx@image@box\box\voidb@x % clear memory \includegraphics[#1,width=\linewidth]{#2}% \else + \setbox\spx@image@box\box\voidb@x % clear memory \includegraphics[#1]{#2}% \fi \fi } +% \sphinxsafeincludegraphics resizes images larger than the line width, +% or taller than about the text height (whether or not height/width options +% were used). This is requested to avoid a crash with \MakeFramed as used by +% sphinxShadowBox (topic/contents) and sphinxheavybox (admonitions), and also +% by sphinxVerbatim (but a priori no image inclusion there). +\newdimen\spx@image@maxheight +% default maximal setting will get reduced by sphinxShadowBox/sphinxheavybox +\AtBeginDocument{\spx@image@maxheight\textheight} +\newcommand*{\sphinxsafeincludegraphics}[2][]{% + \gdef\spx@includegraphics@options{#1}% + \setbox\spx@image@box\hbox{\includegraphics[#1,draft]{#2}}% + \in@false + \ifdim \wd\spx@image@box>\linewidth + \g@addto@macro\spx@includegraphics@options{,width=\linewidth}% + \in@true + \fi + % no rotation, no need to worry about depth + \ifdim \ht\spx@image@box>\spx@image@maxheight + \g@addto@macro\spx@includegraphics@options{,height=\spx@image@maxheight}% + \in@true + \fi + \ifin@ + \g@addto@macro\spx@includegraphics@options{,keepaspectratio}% + \fi + \setbox\spx@image@box\box\voidb@x % clear memory + \expandafter\includegraphics\expandafter[\spx@includegraphics@options]{#2}% +}% %% FIGURE IN TABLE @@ -660,8 +763,22 @@ \sphinxsetvskipsforfigintablecaption \begin{minipage}{#1}% }{\end{minipage}} -% store original \caption macro for use with figures in longtable and tabulary -\AtBeginDocument{\let\spx@originalcaption\caption} +% store the original \caption macro for usage with figures inside longtable +% and tabulary cells. Make sure we get the final \caption in presence of +% caption package, whether the latter was loaded before or after sphinx. +\AtBeginDocument{% + \let\spx@originalcaption\caption + \@ifpackageloaded{caption} + {\let\spx@ifcaptionpackage\@firstoftwo + \caption@AtBeginDocument*{\let\spx@originalcaption\caption}% +% in presence of caption package, drop our own \sphinxcaption whose aim was to +% ensure same width of caption to all kinds of tables (tabular(y), longtable), +% because caption package has its own width (or margin) option + \def\sphinxcaption{\caption}% + }% + {\let\spx@ifcaptionpackage\@secondoftwo}% +} +% tabulary expands twice contents, we need to prevent double counter stepping \newcommand*\sphinxfigcaption {\ifx\equation$%$% this is trick to identify tabulary first pass \firstchoice@false\else\firstchoice@true\fi @@ -1026,17 +1143,28 @@ \vskip\spx@abovecaptionskip \def\sphinxVerbatim@Before {\sphinxVerbatim@Title\nointerlineskip - \kern\dimexpr-\dp\strutbox+\sphinxbelowcaptionspace\relax}% + \kern\dimexpr-\dp\strutbox+\sphinxbelowcaptionspace + % if no frame (code-blocks inside table cells), remove + % the "verbatimsep" whitespace from the top (better visually) + \ifspx@opt@verbatimwithframe\else-\sphinxverbatimsep\fi + % caption package adds \abovecaptionskip vspace, remove it + \spx@ifcaptionpackage{-\abovecaptionskip}{}\relax}% \else \vskip\sphinxverbatimsmallskipamount \def\sphinxVerbatim@After - {\nointerlineskip\kern\dp\strutbox\sphinxVerbatim@Title}% + {\nointerlineskip\kern\dimexpr\dp\strutbox + \ifspx@opt@verbatimwithframe\else-\sphinxverbatimsep\fi + \spx@ifcaptionpackage{-\abovecaptionskip}{}\relax + \sphinxVerbatim@Title}% \fi \def\@captype{literalblock}% \capstart % \sphinxVerbatimTitle must reset color \setbox\sphinxVerbatim@TitleBox \hbox{\begin{minipage}{\linewidth}% + % caption package may detect wrongly if top or bottom, so we help it + \spx@ifcaptionpackage + {\caption@setposition{\spx@opt@literalblockcappos}}{}% \sphinxVerbatimTitle \end{minipage}}% \fi @@ -1245,6 +1373,12 @@ % could nest if LaTeX writer authorized it \newenvironment{sphinxShadowBox} {\def\FrameCommand {\spx@ShadowFBox }% + \advance\spx@image@maxheight + -\dimexpr2\sphinxshadowrule + +2\sphinxshadowsep + +\sphinxshadowsize + +\baselineskip\relax + \let\sphinxincludegraphics\sphinxsafeincludegraphics % configure framed.sty not to add extra vertical spacing \ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}% % the \trivlist will add the vertical spacing on top and bottom which is @@ -1327,6 +1461,11 @@ \newenvironment{sphinxheavybox}{\par \setlength{\FrameRule}{\spx@notice@border}% \setlength{\FrameSep}{\dimexpr.6\baselineskip-\FrameRule\relax} + \advance\spx@image@maxheight + -\dimexpr2\FrameRule + +2\FrameSep + +\baselineskip\relax % will happen again if nested, needed indeed! + \let\sphinxincludegraphics\sphinxsafeincludegraphics % configure framed.sty's parameters to obtain same vertical spacing % as for "light" boxes. We need for this to manually insert parskip glue and % revert a skip done by framed before the frame. @@ -1600,8 +1739,11 @@ % additional customizable styling \def\sphinxstyleindexentry #1{\texttt{#1}} -\def\sphinxstyleindexextra #1{ \emph{(#1)}} +\def\sphinxstyleindexextra #1{ (\emph{#1})} \def\sphinxstyleindexpageref #1{, \pageref{#1}} +\def\sphinxstyleindexpagemain#1{\textbf{#1}} +\protected\def\spxentry#1{#1}% will get \let to \sphinxstyleindexentry in index +\protected\def\spxextra#1{#1}% will get \let to \sphinxstyleindexextra in index \def\sphinxstyleindexlettergroup #1% {{\Large\sffamily#1}\nopagebreak\vspace{1mm}} \def\sphinxstyleindexlettergroupDefault #1% |