Skip to content

Commit

Permalink
feat: Citations basic support
Browse files Browse the repository at this point in the history
  • Loading branch information
Omikhleia authored and Didier Willis committed Dec 14, 2024
1 parent 2b977f9 commit d68ab20
Show file tree
Hide file tree
Showing 13 changed files with 245 additions and 48 deletions.
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,7 @@ This is but an overview. For more details, please refer to the provided example
- Raw inline HTML convenience subset in Markdown
- Advanced use of symbols in Djot (variable substitution ,and templating)
- Advanced configuration (e.g. Markdown variants, headings shifting, etc.)
- Bibliography citations (when appropriate support is enabled)

## Use with the resilient collection

Expand Down
9 changes: 9 additions & 0 deletions examples/extra-styles.dj
Original file line number Diff line number Diff line change
Expand Up @@ -57,3 +57,12 @@ class:registerCommand("Initial", function (_, content)
SILE.call("dropcap", { lines = lines, family = family, color = color, join = true }, { letter })
end)
```

```=sile
% Chicken and egg problem: resilient.sile will suppot loading bibliographies
% in master document, but relies on markdown.sile as dependency for references
% in content files.
% So this is a workaround to load the bibliography here, be able to release a
% new version of markdown.sile and move forward with the development.
\loadbibliography[file=examples/markdown-djot.bib]
```
23 changes: 23 additions & 0 deletions examples/markdown-djot.bib
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
@book{sile,
title = {The SILE Book},
author = {Cozens, Simon and Maclennan, Caleb and Nicole, Olivier and Willis, Didier},
year = {2014–202X},
}

@book{sile:willis2021,
title = {The re·sil·ient collection of classes & packages for SILE: User Guide},
author = {Willis, Didier},
year = {2021–},
}

@book{sile:willis2022,
title = {Markdown and Djot to PDF with SILE: Ultimate Guide & Showcase Document},
author = {Willis, Didier},
year = {2022–},
}

@book{sile:willis2024,
title = {SILE and the Hydra of Maths. Showcase & Critical Assessment 2024},
author = {Willis, Didier},
year = {2024},
}
33 changes: 26 additions & 7 deletions examples/sile-and-djot.dj
Original file line number Diff line number Diff line change
Expand Up @@ -501,7 +501,7 @@ $$`\pi=\sum_{k=0}^\infty\frac{1}{16^k}(\frac{4}{8k+1} − \frac{2}{8k+4} − \fr

Attributes are passed through to SILE.
In display math mode, you can number equations using the default counter (`numbered=true`), a named counter (`counter=name`), or a custom value (`number=...`).
$$`e^{i\phi} = \mi{cos} \phi + i \mi{sin} \phi`{numbered=true}
$$`e^{i\phi} = \cos \phi + i \sin \phi`{numbered=true}

### Footnote calls

Expand All @@ -517,6 +517,26 @@ A footnote call[^djot-some-fn] is marked...

[^djot-some-fn]: An example footnote.

### Bibliographic citations

Djot does not officially support citations at the moment.
This implementation, however, recognizes a simplified subset of the Pandoc citation syntax.

{custom-style=CodeBlock}
:::
```
I wrote a whole book on mathematics with SILE [@sile:willis2024].
... in a "master document" [@sile:willis2021, part 1].
... _The SILE Book_ for more information [@sile, chapter 5].
```
:::

I wrote whole book on mathematics with SILE [@sile:willis2024].

How to load bibliographies and configure citation styles is beyond the scope of this manual.
If you are using the resilient collection, the most natural way to do this in a "master document"
[@sile:willis2021, part 1].
Note that support for biblibraphies in SILE is an experimental feature, so you may also want to check _The SILE Book_ for more information [@sile, chapter 5].

{#djot-symbols}
### Symbols
Expand Down Expand Up @@ -809,8 +829,8 @@ Any further blocks included in the item are assumed to be the definition.

Block attributes are passed to the underlying definition environment.
When not using a supporting class or package, the converter uses its own fallback method, with hard-coded styling (e.g. the term is typeset in boldface).
When using the *resilient* classes, the converter uses the *resilient.defn* environment, and the `variant` option may thus be used to switch to an alternate style.[^djot-defn-variant]
For the purpose of illustration, let's say you have a "Custom" variant with an _ad hoc_ style.
When using the *resilient* classes, the *resilient.defn* environment is loaded, and the `variant` option may thus be used to switch to an alternate style.[^djot-defn-variant]
As an example, let's say you have a "Custom" variant with an _ad hoc_ style.

{custom-style=CodeBlock}
:::
Expand Down Expand Up @@ -996,7 +1016,7 @@ The `render` attribute can be set to `false` to prevent this behavior, and enfor
For instance, the image below is produced with `{.dot width="3.5cm" layout=twopi}`.

:::
{width="3.5cm" layout=twopi}
{width="3cm" layout=twopi}
```dot
graph {
node [fillcolor="lightskyblue:darkcyan" style=filled gradientangle=270]
Expand All @@ -1009,7 +1029,7 @@ The `render` attribute can be set to `false` to prevent this behavior, and enfor
:::
^ An example of a rendered DOT graph.

The original DOT description used in the code block is shown hereafter.
The original DOT description is shown hereafter.

{custom-style=CodeBlock}
:::
Expand Down Expand Up @@ -1239,7 +1259,7 @@ Language changes within the text are supported, on either blocks or inline
elements.
It relies on the `lang` key-value attribute, where the value is a BCP47 language code.
It is not much visible below, obviously, but the language setting affects the hyphenation and other properties.
In the case of French, for instance, you can see the special thin space before the exclamation point, the use of appropriate quotation marks, and the internal spacing around quoted text:
In the case of French, for instance, you can see the thin space before the exclamation point, the use of appropriate quotation marks, and the internal spacing around quoted text:

{lang=fr}
> Cette citation est en français!
Expand Down Expand Up @@ -1331,7 +1351,6 @@ Since it's possible to have unused footnote definitions, let's craft one as show

When encountering a symbol, this converter looks for such a footnote and expands its content.
It works with inline elements as shown above, but also with full blocks, provided the symbol is the only element in a paragraph of its own.

Of course, these pseudo-footnotes[^djot-pseudo-footnotes] can in turn contain symbols, which get replaced too.


Expand Down
114 changes: 82 additions & 32 deletions examples/sile-and-markdown-manual-styles.yml
Original file line number Diff line number Diff line change
@@ -1,25 +1,4 @@

defn-term-Custom:
inherit: "defn-base"
origin: "resilient.defn"
style:
font:
features: "+smcp"
paragraph:
after:
vbreak: false
before:
skip: "smallskip"

defn-desc-Custom:
inherit: "defn-desc"
style:
paragraph:
after:
skip: "smallskip"
before:
vbreak: false

CodeBlock:
origin: "resilient.book"
style:
Expand All @@ -44,22 +23,12 @@ CoverCredit:
CustomDroppedInitial:
origin: "resilient.book"
style:
color: "#66a0b3"
font:
family: "Zallman Caps"
color: "#66a0b3"
special:
lines: 3

FramedPara:
origin: "resilient.book"
style:
paragraph:
after:
skip: "medskip"
align: "fancy-framed"
before:
skip: "medskip"

Difference:
style:
font:
Expand All @@ -71,6 +40,16 @@ Difference:
before:
skip: "smallskip"

FramedPara:
origin: "resilient.book"
style:
paragraph:
after:
skip: "medskip"
align: "fancy-framed"
before:
skip: "medskip"

blockquote:
origin: "resilient.book"
style:
Expand Down Expand Up @@ -104,6 +83,46 @@ bookmatter-copyright:
paragraph:
align: "noparindent"

bookmatter-cover-author:
inherit: "bookmatter-coverpage"
origin: "resilient.bookmatters"
style:
font:
size: "16pt"
properties:
case: "upper"

bookmatter-cover-publisher:
inherit: "bookmatter-coverpage"
origin: "resilient.bookmatters"
style:

bookmatter-cover-subtitle:
inherit: "bookmatter-coverpage"
origin: "resilient.bookmatters"
style:
font:
size: "16pt"
paragraph:
after:
skip: "5%fh"

bookmatter-cover-title:
inherit: "bookmatter-coverpage"
origin: "resilient.bookmatters"
style:
font:
size: "20pt"
paragraph:
after:
skip: "5%fh"
before:
skip: "30%fh"

bookmatter-coverpage:
origin: "resilient.bookmatters"
style:

bookmatter-halftitle:
origin: "resilient.bookmatters"
style:
Expand Down Expand Up @@ -179,6 +198,15 @@ defn-desc:
before:
vbreak: false

defn-desc-Custom:
inherit: "defn-desc"
style:
paragraph:
after:
skip: "smallskip"
before:
vbreak: false

defn-term:
inherit: "defn-base"
origin: "resilient.defn"
Expand All @@ -191,6 +219,18 @@ defn-term:
before:
skip: "smallskip"

defn-term-Custom:
inherit: "defn-base"
origin: "resilient.defn"
style:
font:
features: "+smcp"
paragraph:
after:
vbreak: false
before:
skip: "smallskip"

dropcap:
origin: "resilient.book"
style:
Expand Down Expand Up @@ -239,6 +279,16 @@ epigraph-text:
paragraph:
align: "justify"

eqno:
origin: "resilient.book"
style:
numbering:
after:
text: ")"
before:
text: "("
display: "arabic"

fancytoc-base:
style:

Expand Down
22 changes: 21 additions & 1 deletion examples/sile-and-markdown.md
Original file line number Diff line number Diff line change
Expand Up @@ -507,6 +507,25 @@ They are introduced with directly with the caret `^`, immediately followed by th

:::

### Bibliographic citations

This implementation recognizes a simplified subset of the Pandoc citation syntax, aligned with what we also support in Djot.

::: {custom-style=CodeBlock}
```
I wrote a whole book on mathematics with SILE [@sile:willis2024].
... in a "master document" [@sile:willis2021, part 1].
... _The SILE Book_ for more information [@sile, chapter 5].
```
:::

I wrote whole book on mathematics with SILE [@sile:willis2024].

How to load bibliographies and configure citation styles is beyond the scope of this manual.
If you are using the resilient collection, the most natural way to do this in a "master document"
[@sile:willis2021, part 1].
Note that support for biblibraphies in SILE is an experimental feature, so you may also want to check _The SILE Book_ for more information [@sile, chapter 5].

### Symbols

::: {custom-style=Difference}
Expand Down Expand Up @@ -1054,7 +1073,8 @@ This converter recognizes a few specific attributes on divs:
### Horizontal dividers

In standard Markdown, a line containing a row of three or more asterisks, dashes, or underscores (optionally separated by spaces) are supposed to produce a horizontal rule.
This converter however slightly deviates from that simple specification^[And also from Pandoc, therefore. Quite obviously, the `\autodoc:package{pandocast}`{=sile} package will also only show horizontal rules.],
This converter however slightly deviates from that simple specification^[And also from Pandoc.
Our `\autodoc:package{pandocast}`{=sile} package will only show horizontal rules.],
for the mere reason that such a horizontal rule is seldom typographically sound in many contexts.

Three asterisks produce a centered asterism.
Expand Down
5 changes: 5 additions & 0 deletions inputters/djot.lua
Original file line number Diff line number Diff line change
Expand Up @@ -759,6 +759,11 @@ function Renderer:math (node)
return createCommand("markdown:internal:math", options, { node.s }, node_pos(node))
end

function Renderer:naive_citations (node)
local pos = node_pos(node)
return utils.naiveCitations(node.s, pos)
end

-- SILE INPUTTER LOGIC

local base = require("inputters.base")
Expand Down
13 changes: 13 additions & 0 deletions inputters/markdown.lua
Original file line number Diff line number Diff line change
Expand Up @@ -267,6 +267,10 @@ local function SileAstWriter (writerOps, renderOps)
return createCommand("markdown:internal:math" , { mode = mode }, { text })
end

writer.naive_citations = function (rawcites)
return utils.naiveCitations(rawcites)
end

-- Final AST conversion logic.
-- The lunamark "AST" is made of "ropes":
-- "A rope is an array whose elements may be ropes, strings, numbers,
Expand Down Expand Up @@ -366,11 +370,15 @@ parsers.lineof = function (c)

local function customSyntax (writer, options)
return function (syntax)
-- Re-create the horizontal rule syntax to use our modified lineof
-- with a capture.
syntax.HorizontalRule = (parsers.lineof(parsers.asterisk)
+ parsers.lineof(parsers.dash)
+ parsers.lineof(parsers.underscore)
) / writer.hrule

-- Extend the smart typography syntax to recognize primes and double primes
-- after digits.
if options.smart_primes then
syntax.Smart = lpeg.P("\"") * lpeg.B(parsers.digit*1) / function ()
return "" -- double primes
Expand All @@ -380,6 +388,10 @@ local function customSyntax (writer, options)
end
+ syntax.Smart
end
-- Override the citation syntax to use our own raw citations writer
syntax.Citations = lpeg.P("[")
* lpeg.C(lpeg.P("@") *(lpeg.P(1) - lpeg.P("]"))^1)
* lpeg.P("]") / writer.naive_citations
return syntax
end
end
Expand Down Expand Up @@ -430,6 +442,7 @@ function inputter:parse (doc)
line_blocks = true,
escaped_line_breaks = true,
tex_math_dollars = true,
citations = true,
}
for k, v in pairs(self.options) do
-- Allow overriding known options
Expand Down
Loading

0 comments on commit d68ab20

Please sign in to comment.