-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.html
190 lines (190 loc) · 7.34 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>Introducing crossref-adapt</title>
<style>
html {
line-height: 1.5;
font-family: Georgia, serif;
font-size: 20px;
color: #1a1a1a;
background-color: #fdfdfd;
}
body {
margin: 0 auto;
max-width: 36em;
padding-left: 50px;
padding-right: 50px;
padding-top: 50px;
padding-bottom: 50px;
hyphens: auto;
word-wrap: break-word;
text-rendering: optimizeLegibility;
font-kerning: normal;
}
@media (max-width: 600px) {
body {
font-size: 0.9em;
padding: 1em;
}
}
@media print {
body {
background-color: transparent;
color: black;
font-size: 12pt;
}
p, h2, h3 {
orphans: 3;
widows: 3;
}
h2, h3, h4 {
page-break-after: avoid;
}
}
p {
margin: 1em 0;
}
a {
color: #1a1a1a;
}
a:visited {
color: #1a1a1a;
}
img {
max-width: 100%;
}
h1, h2, h3, h4, h5, h6 {
margin-top: 1.4em;
}
h5, h6 {
font-size: 1em;
font-style: italic;
}
h6 {
font-weight: normal;
}
ol, ul {
padding-left: 1.7em;
margin-top: 1em;
}
li > ol, li > ul {
margin-top: 0;
}
blockquote {
margin: 1em 0 1em 1.7em;
padding-left: 1em;
border-left: 2px solid #e6e6e6;
color: #606060;
}
code {
font-family: Menlo, Monaco, 'Lucida Console', Consolas, monospace;
font-size: 85%;
margin: 0;
}
pre {
margin: 1em 0;
overflow: auto;
}
pre code {
padding: 0;
overflow: visible;
}
.sourceCode {
background-color: transparent;
overflow: visible;
}
hr {
background-color: #1a1a1a;
border: none;
height: 1px;
margin: 1em 0;
}
table {
margin: 1em 0;
border-collapse: collapse;
width: 100%;
overflow-x: auto;
display: block;
font-variant-numeric: lining-nums tabular-nums;
}
table caption {
margin-bottom: 0.75em;
}
tbody {
margin-top: 0.5em;
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
}
th {
border-top: 1px solid #1a1a1a;
padding: 0.25em 0.5em 0.25em 0.5em;
}
td {
padding: 0.125em 0.5em 0.25em 0.5em;
}
header {
margin-bottom: 4em;
text-align: center;
}
#TOC li {
list-style: none;
}
#TOC a:not(:hover) {
text-decoration: none;
}
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
</style>
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<header id="title-block-header">
<h1 class="title">Introducing crossref-adapt</h1>
</header>
<h1 data-number="1" id="crossref-adapt"><span class="header-section-number">1</span> crossref-adapt</h1>
<p>A Pandoc-Lua Filter to change the internal IDs for cross-references as produced by <code>pandoc-crossref</code>.</p>
<p>Michael Cysouw <a href="mailto:cysouw@mac.com" class="email">cysouw@mac.com</a></p>
<h1 data-number="2" id="rationale"><span class="header-section-number">2</span> Rationale</h1>
<p><a href="https:pandoc.org">Pandoc</a> is a system for converting between different markup formats. The <a href="https://github.com/lierdakil/pandoc-crossref"><code>pandoc-crossref</code></a> filter (extensions to Pandoc are called ‘filter’ in Pandoc-parlance) allows for easy and flexible internal cross-reference to sections, figures, tables and equations. The current <code>crossref-adapt</code> filter adds a cosmetic change to the IDs of these cross-references.</p>
<p>The effect of <code>crossref-adapt</code> is that the internal IDs are harmonized with the IDs as they are type-set in the final text. In this way it is possible to use these IDs to transparently refer to each individual item. For example, in the <a href="https://cysouw.github.io/crossref-adapt/README.html">HTML-version</a> of this README this section is numbered as Section 2. By adding the <a href="https://en.wikipedia.org/wiki/URI_fragment">fragment-identifier</a> <code>#sec2</code> to the URL a direct link to this section is made (e.g. <a href="https://cysouw.github.io/crossref-adapt/README.html#sec2">cysouw.github.io/crossref-adapt/README.html#sec2</a>).</p>
<p>This functionality is intended for stable (scientific) publications on the open web. Instead of circuitous and cumbersome current practice of page numbering inside of PDFs, this allows for direct scientific cross-references to specific element of a scientific work, e.g. (Cysouw 2021: <a href="https://cysouw.github.io/diathesis/fulltext.html#sec2.5">#sec2.5</a>).</p>
<h1 data-number="3" id="cross-referencing"><span class="header-section-number">3</span> Cross-referencing</h1>
<p>Currently, the IDs as produced by this filter can be referred to as follows:</p>
<ul>
<li><strong><code>#sec2</code></strong> for numbered sections</li>
<li><strong><code>#tbl2</code></strong> for numbered tables</li>
<li><strong><code>#fig3</code></strong> for numbered figures</li>
<li><strong><code>#eq4</code></strong> for numbered equations</li>
</ul>
<p>The format is deliberately somewhat cryptic and short, but easy to type and parse. The hash is the URL-standard for fragments. The numbers are the actual numbers as produced in the final output. No punctuation is added inside these IDs to make automatic parsing easier.</p>
<p>The format is harmonized with the IDs for footnotes as produces natively by Pandoc, with linguistic examples as produced by the Pandoc-filter <code>pandoc-ling</code> and with paragraph numbers as added to Pandoc with the filter <code>count-para</code>:</p>
<ul>
<li><strong><code>#fn3</code></strong> for <a href="https://pandoc.org/MANUAL.html#footnotes">Pandoc footnotes</a></li>
<li><strong><code>#ex7</code></strong> for examples as produced by <a href="https://github.com/cysouw/pandoc-ling"><code>pandoc-ling</code></a></li>
<li><strong><code>#8</code></strong> for paragraph numbers as produced by <a href="https://github.com/cysouw/count-para"><code>count-para</code></a></li>
</ul>
<h1 data-number="4" id="usage"><span class="header-section-number">4</span> Usage</h1>
<p>As an example, this <code>readme</code> is converted into HTML with the following Pandoc command. It can be directly accessed at <a href="https://cysouw.github.io/crossref-adapt/readme.html">cysouw.github.io/crossref-adapt</a>.</p>
<pre><code>pandoc README.md \
--to html \
--output README.html \
--standalone \
--number-sections \
--filter pandoc-crossref \
--metadata linkReferences=true \
--metadata setLabelAttribute=true \
--lua-filter crossref-adapt.lua \
--metadata title="Introducing crossref-adapt"</code></pre>
</body>
</html>