Skip to content

Commit 056178e

Browse files
blake-rileytarleb
blake-riley
authored and
tarleb
committed
Short-captions for Tables (#45)
Add table shortcaption filter.
1 parent 0978922 commit 056178e

File tree

5 files changed

+596
-0
lines changed

5 files changed

+596
-0
lines changed

‎table-short-captions/Makefile

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
LF = --lua-filter=table-short-captions.lua
2+
F = -F pandoc-crossref
3+
4+
readme:
5+
@pandoc -s $(LF) $(F) README.md -o README.pdf
6+
7+
sample:
8+
@pandoc -s $(LF) $(F) -t latex sample.md -o sample.tex
9+
@pandoc -s $(LF) $(F) -t latex sample.md -o sample.pdf
10+
11+
test: sample
12+
diff --strip-trailing-cr expected-sample.tex sample.tex
13+
14+
clean:
15+
rm -v *.aux *.dvi *.fdb_latexmk *.fls *.log *.lot *.ps *.pdf sample.tex | true

‎table-short-captions/README.md

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: "table-short-captions.lua"
3+
lot: true
4+
---
5+
6+
# Short captions in \LaTeX\ tables output
7+
8+
For LaTeX output, this filter enables use of the attribute `short-caption` for tables. The attribute value will appear in the List of Tables.
9+
10+
This filter also enables the class `.unlisted` for tables. This will prevent the table caption from appearing in the List of Tables.
11+
12+
# Usage
13+
14+
In Pandoc Markdown, you can add a caption to a table with
15+
16+
Table: This is the *italicised long caption* of my table, which has a very long caption.
17+
18+
If the document metadata includes `lot:true`, then the List of Tables will be inserted at the beginning of the document.
19+
20+
The [pandoc-crossref](http://lierdakil.github.io/pandoc-crossref/) filter extends this, and enables you to specify a custom label for the table.
21+
22+
Table: This is the *italicised long caption* of my table, which has a very long caption. {#tbl:full-of-juicy-data}
23+
24+
This filter, when run _before_ pandoc-crossref, allows you to add short captions to the table as a `short-caption` attribute. What is between the quotes will be parsed as Markdown.
25+
26+
**Important!:** You _must_ use empty square brackets before the attributes tag.
27+
28+
Table: This is the *italicised long caption* of my table, which has a very long caption. []{#tbl:full-of-juicy-data short-caption="Short caption for *juicy* data table."}
29+
30+
Alternatively, if you wish to create a table which is unlisted in the List of Tables, you can use the `.unlisted` class in the attributes tag.
31+
32+
Table: This is the *italicised long caption* of my table, which will not appear in the List of Tables. []{#tbl:full-of-juicy-data .unlisted}
33+
34+
This filter should prove useful for students writing dissertations, who often have to include a List of Tables in the front matter, but where table captions themselves can be quite lengthy.
35+
36+
pandoc --lua-filter=table-short-captions.lua --filter pandoc-crossref article.md -o article.tex
37+
38+
pandoc --lua-filter=table-short-captions.lua --filter pandoc-crossref article.md -o article.pdf
39+
40+
41+
# Limitations
42+
43+
- The filter will process the `short-caption` attribute value as pandoc markdown, regardless of the input format.
44+
- pandoc-crossref should be run after it.
45+
- I have only tested this from a Markdown source.

‎table-short-captions/expected-sample.tex

+290
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
\PassOptionsToPackage{unicode=true}{hyperref} % options for packages loaded elsewhere
2+
\PassOptionsToPackage{hyphens}{url}
3+
%
4+
\documentclass[
5+
]{article}
6+
\usepackage{lmodern}
7+
\usepackage{amssymb,amsmath}
8+
\usepackage{ifxetex,ifluatex}
9+
\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex
10+
\usepackage[T1]{fontenc}
11+
\usepackage[utf8]{inputenc}
12+
\usepackage{textcomp} % provides euro and other symbols
13+
\else % if luatex or xelatex
14+
\usepackage{unicode-math}
15+
\defaultfontfeatures{Scale=MatchLowercase}
16+
\defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
17+
\fi
18+
% use upquote if available, for straight quotes in verbatim environments
19+
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
20+
\IfFileExists{microtype.sty}{% use microtype if available
21+
\usepackage[]{microtype}
22+
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
23+
}{}
24+
\makeatletter
25+
\@ifundefined{KOMAClassName}{% if non-KOMA class
26+
\IfFileExists{parskip.sty}{%
27+
\usepackage{parskip}
28+
}{% else
29+
\setlength{\parindent}{0pt}
30+
\setlength{\parskip}{6pt plus 2pt minus 1pt}}
31+
}{% if KOMA class
32+
\KOMAoptions{parskip=half}}
33+
\makeatother
34+
\usepackage{xcolor}
35+
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
36+
\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}}
37+
\hypersetup{
38+
pdftitle={Tests for table-short-captions.lua},
39+
pdfborder={0 0 0},
40+
breaklinks=true}
41+
\urlstyle{same} % don't use monospace font for urls
42+
\usepackage{longtable,booktabs}
43+
% Allow footnotes in longtable head/foot
44+
\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}}
45+
\makesavenoteenv{longtable}
46+
\setlength{\emergencystretch}{3em} % prevent overfull lines
47+
\providecommand{\tightlist}{%
48+
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
49+
\setcounter{secnumdepth}{-2}
50+
% Redefines (sub)paragraphs to behave more like sections
51+
\ifx\paragraph\undefined\else
52+
\let\oldparagraph\paragraph
53+
\renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}}
54+
\fi
55+
\ifx\subparagraph\undefined\else
56+
\let\oldsubparagraph\subparagraph
57+
\renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}}
58+
\fi
59+
60+
% set default figure placement to htbp
61+
\makeatletter
62+
\def\fps@figure{htbp}
63+
\makeatother
64+
65+
% -- begin:latex-table-short-captions --
66+
\makeatletter\AtBeginDocument{%
67+
\def\LT@c@ption#1[#2]#3{% % Overwrite the workhorse macro used in formatting a longtable caption.
68+
\LT@makecaption#1\fnum@table{#3}%
69+
\ifdefined\pandoctableshortcapt % If pandoctableshortcapt is defined (even if blank), we should override default behaviour.
70+
\let\@tempa\pandoctableshortcapt% % (Use let, we don't want to expand pandoctableshortcapt!)
71+
\else % If not, fall back to default behaviour
72+
\def\@tempa{#2}% % (Use the argument in square brackets)
73+
\fi
74+
\ifx\@tempa\@empty\else % If @tempa is blank, no lot entry! Otherwise, @tempa becomes the lot title.
75+
{\let\\\space
76+
\addcontentsline{lot}{table}{\protect\numberline{\thetable}{\@tempa}}}%
77+
\fi}
78+
}\makeatother
79+
% -- end:latex-table-short-captions --
80+
\makeatletter
81+
\@ifpackageloaded{subfig}{}{\usepackage{subfig}}
82+
\@ifpackageloaded{caption}{}{\usepackage{caption}}
83+
\captionsetup[subfloat]{margin=0.5em}
84+
\AtBeginDocument{%
85+
\renewcommand*\figurename{Figure}
86+
\renewcommand*\tablename{Table}
87+
}
88+
\AtBeginDocument{%
89+
\renewcommand*\listfigurename{List of Figures}
90+
\renewcommand*\listtablename{List of Tables}
91+
}
92+
\@ifpackageloaded{float}{}{\usepackage{float}}
93+
\floatstyle{ruled}
94+
\@ifundefined{c@chapter}{\newfloat{codelisting}{h}{lop}}{\newfloat{codelisting}{h}{lop}[chapter]}
95+
\floatname{codelisting}{Listing}
96+
\newcommand*\listoflistings{\listof{codelisting}{List of Listings}}
97+
\makeatother
98+
99+
\title{Tests for table-short-captions.lua}
100+
\date{}
101+
102+
\begin{document}
103+
\maketitle
104+
105+
\listoftables
106+
These tests are written so that if \textbf{bold font} appears in the
107+
LOT, something is wrong.
108+
109+
The tests are split into two: expected uses, and non-standard
110+
uses/errors.\\
111+
The non-standard uses are presented in this document for troubleshooting
112+
purposes, and to ensure the filter doesn't crash in corner cases.
113+
114+
\hypertarget{standard-usage}{%
115+
\section{Standard usage}\label{standard-usage}}
116+
117+
\begin{longtable}[]{@{}ll@{}}
118+
\caption{This is the \emph{italicised long caption} of tbl1, which does
119+
not have a label.}\tabularnewline
120+
\toprule
121+
cola & colb\tabularnewline
122+
\midrule
123+
\endfirsthead
124+
\toprule
125+
cola & colb\tabularnewline
126+
\midrule
127+
\endhead
128+
a1 & b1\tabularnewline
129+
a2 & b2\tabularnewline
130+
\bottomrule
131+
\end{longtable}
132+
133+
\hypertarget{tbl:tbl-label2}{}
134+
\begin{longtable}[]{@{}ll@{}}
135+
\caption{\label{tbl:tbl-label2}This is the \emph{italicised long
136+
caption} of tbl2, in standard \texttt{pandoc-crossref}
137+
form.}\tabularnewline
138+
\toprule
139+
cola & colb\tabularnewline
140+
\midrule
141+
\endfirsthead
142+
\toprule
143+
cola & colb\tabularnewline
144+
\midrule
145+
\endhead
146+
a1 & b1\tabularnewline
147+
a2 & b2\tabularnewline
148+
\bottomrule
149+
\end{longtable}
150+
151+
\def\pandoctableshortcapt{} % .unlisted
152+
153+
\hypertarget{tbl:tbl-label3}{}
154+
\begin{longtable}[]{@{}ll@{}}
155+
\caption{\label{tbl:tbl-label3}This is the \emph{italicised long
156+
caption} of tbl3, which is \textbf{unlisted}.}\tabularnewline
157+
\toprule
158+
cola & colb\tabularnewline
159+
\midrule
160+
\endfirsthead
161+
\toprule
162+
cola & colb\tabularnewline
163+
\midrule
164+
\endhead
165+
a1 & b1\tabularnewline
166+
a2 & b2\tabularnewline
167+
\bottomrule
168+
\end{longtable}
169+
170+
\undef\pandoctableshortcapt
171+
172+
\def\pandoctableshortcapt{Table 4 \emph{short} capt.}
173+
174+
\hypertarget{tbl:tbl-label4}{}
175+
\begin{longtable}[]{@{}ll@{}}
176+
\caption{\label{tbl:tbl-label4}This is the \emph{italicised long
177+
caption} of tbl4, which has an \textbf{overriding} short-caption. This
178+
is the expected usage.}\tabularnewline
179+
\toprule
180+
cola & colb\tabularnewline
181+
\midrule
182+
\endfirsthead
183+
\toprule
184+
cola & colb\tabularnewline
185+
\midrule
186+
\endhead
187+
a1 & b1\tabularnewline
188+
a2 & b2\tabularnewline
189+
\bottomrule
190+
\end{longtable}
191+
192+
\undef\pandoctableshortcapt
193+
194+
\hypertarget{non-standard-usageerrors}{%
195+
\section{Non-standard usage/errors}\label{non-standard-usageerrors}}
196+
197+
\begin{longtable}[]{@{}ll@{}}
198+
\caption{This is the \emph{italicised long caption} of tbl5, which does
199+
not have a label, but does have empty braces at the end.
200+
\{\}}\tabularnewline
201+
\toprule
202+
cola & colb\tabularnewline
203+
\midrule
204+
\endfirsthead
205+
\toprule
206+
cola & colb\tabularnewline
207+
\midrule
208+
\endhead
209+
a1 & b1\tabularnewline
210+
a2 & b2\tabularnewline
211+
\bottomrule
212+
\end{longtable}
213+
214+
\begin{longtable}[]{@{}ll@{}}
215+
\caption{This is the \emph{italicised long caption} of tbl6, which does
216+
not have a label, but does have an empty span at the end.
217+
}\tabularnewline
218+
\toprule
219+
cola & colb\tabularnewline
220+
\midrule
221+
\endfirsthead
222+
\toprule
223+
cola & colb\tabularnewline
224+
\midrule
225+
\endhead
226+
a1 & b1\tabularnewline
227+
a2 & b2\tabularnewline
228+
\bottomrule
229+
\end{longtable}
230+
231+
\begin{longtable}[]{@{}ll@{}}
232+
\caption{This is the \emph{italicised long caption} of tbl7, which is
233+
improperly formatted, and will appear in the list of tables. This filter
234+
requires that \texttt{.unlisted} is placed in a span. \{\#tbl:tbl-label7
235+
.unlisted\}}\tabularnewline
236+
\toprule
237+
cola & colb\tabularnewline
238+
\midrule
239+
\endfirsthead
240+
\toprule
241+
cola & colb\tabularnewline
242+
\midrule
243+
\endhead
244+
a1 & b1\tabularnewline
245+
a2 & b2\tabularnewline
246+
\bottomrule
247+
\end{longtable}
248+
249+
\hypertarget{tbl:tbl-label8}{}
250+
\begin{longtable}[]{@{}ll@{}}
251+
\caption{\label{tbl:tbl-label8}This is the \emph{italicised long
252+
caption} of tbl8, which has an empty short-caption. An empty
253+
short-caption does nothing. The long caption will still be
254+
used.}\tabularnewline
255+
\toprule
256+
cola & colb\tabularnewline
257+
\midrule
258+
\endfirsthead
259+
\toprule
260+
cola & colb\tabularnewline
261+
\midrule
262+
\endhead
263+
a1 & b1\tabularnewline
264+
a2 & b2\tabularnewline
265+
\bottomrule
266+
\end{longtable}
267+
268+
\def\pandoctableshortcapt{} % .unlisted
269+
270+
\hypertarget{tbl:tbl-label9}{}
271+
\begin{longtable}[]{@{}ll@{}}
272+
\caption{\label{tbl:tbl-label9}This is the \emph{italicised long
273+
caption} of tbl9, which is \textbf{unlisted}, yet has a
274+
short-caption.}\tabularnewline
275+
\toprule
276+
cola & colb\tabularnewline
277+
\midrule
278+
\endfirsthead
279+
\toprule
280+
cola & colb\tabularnewline
281+
\midrule
282+
\endhead
283+
a1 & b1\tabularnewline
284+
a2 & b2\tabularnewline
285+
\bottomrule
286+
\end{longtable}
287+
288+
\undef\pandoctableshortcapt
289+
290+
\end{document}

0 commit comments

Comments
 (0)