From d225c73b5cf86bb9674565a7f80e614fd30fff22 Mon Sep 17 00:00:00 2001 From: Omikhleia Date: Sat, 18 Jan 2025 20:39:23 +0100 Subject: [PATCH] docs(manual): Migrate Markdown chapters to Djot We've already a lot of Djot chapters. It parses faster and has more capabilities, so generalize it. --- examples/manual-front.sil | 5 ++- examples/manual-masterdoc/bibliographies.dj | 2 +- examples/manual-masterdoc/masterdoc.dj | 2 +- .../advanced/{dropcap.md => dropcap.dj} | 2 +- .../advanced/{eqno.md => eqno.dj} | 0 .../advanced/{folio.md => folio.dj} | 2 +- .../advanced/{footnotes.md => footnotes.dj} | 0 .../advanced/{intro.md => intro.dj} | 0 .../advanced/{liststyles.md => liststyles.dj} | 2 +- .../advanced/{other.md => other.dj} | 6 ++-- .../advanced/{toclevels.md => toclevels.dj} | 4 +-- .../basics/{character.md => character.dj} | 13 ++++--- .../basics/{concepts.md => concepts.dj} | 3 +- .../basics/{definitions.md => definitions.dj} | 0 .../basics/{lists.md => lists.dj} | 0 .../basics/{paragraph.md => paragraph.dj} | 17 ++++++---- .../basics/{sectioning.md => sectioning.dj} | 16 ++++----- .../manual-styling/basics/{toc.md => toc.dj} | 0 examples/sile-resilient-manual.silm | 34 +++++++++---------- 19 files changed, 58 insertions(+), 50 deletions(-) rename examples/manual-styling/advanced/{dropcap.md => dropcap.dj} (93%) rename examples/manual-styling/advanced/{eqno.md => eqno.dj} (100%) rename examples/manual-styling/advanced/{folio.md => folio.dj} (94%) rename examples/manual-styling/advanced/{footnotes.md => footnotes.dj} (100%) rename examples/manual-styling/advanced/{intro.md => intro.dj} (100%) rename examples/manual-styling/advanced/{liststyles.md => liststyles.dj} (94%) rename examples/manual-styling/advanced/{other.md => other.dj} (53%) rename examples/manual-styling/advanced/{toclevels.md => toclevels.dj} (94%) rename examples/manual-styling/basics/{character.md => character.dj} (96%) rename examples/manual-styling/basics/{concepts.md => concepts.dj} (98%) rename examples/manual-styling/basics/{definitions.md => definitions.dj} (100%) rename examples/manual-styling/basics/{lists.md => lists.dj} (100%) rename examples/manual-styling/basics/{paragraph.md => paragraph.dj} (92%) rename examples/manual-styling/basics/{sectioning.md => sectioning.dj} (89%) rename examples/manual-styling/basics/{toc.md => toc.dj} (100%) diff --git a/examples/manual-front.sil b/examples/manual-front.sil index 637d5f3..0a73e27 100644 --- a/examples/manual-front.sil +++ b/examples/manual-front.sil @@ -7,7 +7,10 @@ \set[parameter=document.parindent, value=0]{% \roughbox[enlarge=true, singlestroke=true, preserve=true, padding=2%fw, bordercolor=#59b24c, fillcolor=230, shadowcolor=#96A8C7, shadow=false]{% -\parbox[width=96%lw]{\set[parameter=document.parindent, value=0]\font[size=9pt]\color[color=100]{\process}\par}% +% Beware, wrap color around the parbox so it stays in horizontal mode +% In the parbox it could lead to a blank line (we'd need to fix this...) +% Colors aren't settings so they propagate to the parbox, whatever settings logic it has. +\color[color=100]{\parbox[width=96%lw]{\set[parameter=document.parindent, value=0]\font[size=9pt]{\process}\par}}% }}% \medskip} diff --git a/examples/manual-masterdoc/bibliographies.dj b/examples/manual-masterdoc/bibliographies.dj index f126a0b..871d6fa 100644 --- a/examples/manual-masterdoc/bibliographies.dj +++ b/examples/manual-masterdoc/bibliographies.dj @@ -36,7 +36,7 @@ Refer to _The SILE Book_ for more information on how to do this. ## Printing the bibliography -The **resilient.book** class registers a Djot symbol, `_BIBLIOGRAPHY_`, which you can use in a standalone paragraph to print the bibliography.[^bibliography-symbol] +The *resilient.book* class registers a Djot symbol, `_BIBLIOGRAPHY_`, which you can use in a standalone paragraph to print the bibliography.[^bibliography-symbol] Attributes are passed through to the underlying implementation. For example, to print all the bibliography including uncited references, you can use: diff --git a/examples/manual-masterdoc/masterdoc.dj b/examples/manual-masterdoc/masterdoc.dj index 8115296..c69e982 100644 --- a/examples/manual-masterdoc/masterdoc.dj +++ b/examples/manual-masterdoc/masterdoc.dj @@ -155,7 +155,7 @@ chapters: ``` We earlier mentioned the `parts` keywords. -With document classes supporting parts, such as **resilient.book**, it allows using them, starting at that level.[^masterdoc-astute] +With document classes supporting parts, such as *resilient.book*, it allows using them, starting at that level.[^masterdoc-astute] [^masterdoc-nesting]: In particular, you may include a master document in another. In that case, though, only the declared extra packages and the content files are used. diff --git a/examples/manual-styling/advanced/dropcap.md b/examples/manual-styling/advanced/dropcap.dj similarity index 93% rename from examples/manual-styling/advanced/dropcap.md rename to examples/manual-styling/advanced/dropcap.dj index 28856fb..ce303e9 100644 --- a/examples/manual-styling/advanced/dropcap.md +++ b/examples/manual-styling/advanced/dropcap.dj @@ -1,7 +1,7 @@ ## Styling initial capitals Initial capitals (also known as drop caps) are a typographic feature where the first letter of a paragraph is enlarged and styled differently from the rest of the text. -The **resilient.book** class defines two commands for this purpose: `initial-joined` and `initial-unjoined`. +The *resilient.book* class defines two commands for this purpose: `initial-joined` and `initial-unjoined`. The former should be used when the initial capital is part of the first word of the paragraph, and the latter when it is a separate character. In Markdown or Djot, you may use one or the other directly as a style (although they are rather pseudo-styles, strictly speaking). diff --git a/examples/manual-styling/advanced/eqno.md b/examples/manual-styling/advanced/eqno.dj similarity index 100% rename from examples/manual-styling/advanced/eqno.md rename to examples/manual-styling/advanced/eqno.dj diff --git a/examples/manual-styling/advanced/folio.md b/examples/manual-styling/advanced/folio.dj similarity index 94% rename from examples/manual-styling/advanced/folio.md rename to examples/manual-styling/advanced/folio.dj index 1f45152..f34041e 100644 --- a/examples/manual-styling/advanced/folio.md +++ b/examples/manual-styling/advanced/folio.dj @@ -1,6 +1,6 @@ ## Styling page numbers -In two-side documents, such as the **resilient.book** class, dedicated paragraph styles +In two-side documents, such as the *resilient.book* class, dedicated paragraph styles are used for odd and even pages. The _default_ definitions just take care the alignment, and defer other styling decisions to a common parent style. diff --git a/examples/manual-styling/advanced/footnotes.md b/examples/manual-styling/advanced/footnotes.dj similarity index 100% rename from examples/manual-styling/advanced/footnotes.md rename to examples/manual-styling/advanced/footnotes.dj diff --git a/examples/manual-styling/advanced/intro.md b/examples/manual-styling/advanced/intro.dj similarity index 100% rename from examples/manual-styling/advanced/intro.md rename to examples/manual-styling/advanced/intro.dj diff --git a/examples/manual-styling/advanced/liststyles.md b/examples/manual-styling/advanced/liststyles.dj similarity index 94% rename from examples/manual-styling/advanced/liststyles.md rename to examples/manual-styling/advanced/liststyles.dj index bdb615c..7b88a78 100644 --- a/examples/manual-styling/advanced/liststyles.md +++ b/examples/manual-styling/advanced/liststyles.dj @@ -1,6 +1,6 @@ ## Styling lists -The **resilient.lists** package, as noted in its documentation, uses +The *resilient.lists* package, as noted in its documentation, uses different sets of styles for the `itemize` and the `enumerate` environments. diff --git a/examples/manual-styling/advanced/other.md b/examples/manual-styling/advanced/other.dj similarity index 53% rename from examples/manual-styling/advanced/other.md rename to examples/manual-styling/advanced/other.dj index 49fd540..2113653 100644 --- a/examples/manual-styling/advanced/other.md +++ b/examples/manual-styling/advanced/other.dj @@ -6,9 +6,9 @@ You should therefore read their documentation to learn about them, and look at a Readers experienced with SILE’s standard packages also have to be aware that the latter sometimes define hooks, initially intended for users to possibly re-implement in order to override some internal formatting logic. Obviously, in the context of a resilient-compatible class, some of these are already overriden to rely on the styling paradigm presented here. -For instance, the (standard) **url** package provides a `urlstyle` hook command. While you could override it---that is, redefine that command---, please note that this is what the resilient classes already do, so as to delegate the decision to a style conveniently called `urlstyle` too.[^other-sile-hooks] +For instance, the (standard) *url* package provides a `urlstyle` hook command. While you could override it---that is, redefine that command---, please note that this is what the resilient classes already do, so as to delegate the decision to a style conveniently called `urlstyle` too.[^other-sile-hooks] -[^other-sile-hooks]: The same principle actually applies to page numbers, relying on the standard **folio** package. The latter provides a `foliostyle` hook, which the resilient styling system overrides with its own clever logic. -Likewise, the `math:numberstyle` hook from the **math** package is also redefined, to rely on the `eqno` style for display math equation numbers (and actually, if it exist and is non-emppty, to the `eqno-⟨counter⟩` style specific to the counter in question, by default `equation`), as described in the previous section. +[^other-sile-hooks]: The same principle actually applies to page numbers, relying on the standard *folio* package. The latter provides a `foliostyle` hook, which the resilient styling system overrides with its own clever logic. +Likewise, the `math:numberstyle` hook from the *math* package is also redefined, to rely on the `eqno` style for display math equation numbers (and actually, if it exist and is non-emppty, to the `eqno-⟨counter⟩` style specific to the counter in question, by default `equation`), as described in the previous section. In other terms, even for standard SILE packages, we may already have provided a style-aware version of their original customization hooks. diff --git a/examples/manual-styling/advanced/toclevels.md b/examples/manual-styling/advanced/toclevels.dj similarity index 94% rename from examples/manual-styling/advanced/toclevels.md rename to examples/manual-styling/advanced/toclevels.dj index 780094b..7f37ae7 100644 --- a/examples/manual-styling/advanced/toclevels.md +++ b/examples/manual-styling/advanced/toclevels.dj @@ -9,9 +9,9 @@ consider: - How page references are formatted. [^toc-fancy]: This section applies to the "standard" table of contents, -as produced with the `\tableofcontents` command from the **resilient.tableofcontents** +as produced with the `\tableofcontents` command from the *resilient.tableofcontents* package. -Specific implementations such as **fancytoc** may use their own +Specific implementations such as *fancytoc* may use their own styling rules. ### Global setup diff --git a/examples/manual-styling/basics/character.md b/examples/manual-styling/basics/character.dj similarity index 96% rename from examples/manual-styling/basics/character.md rename to examples/manual-styling/basics/character.dj index 8d4cae5..694c97d 100644 --- a/examples/manual-styling/basics/character.md +++ b/examples/manual-styling/basics/character.dj @@ -19,7 +19,7 @@ A regular character style obeys to the following specification The ⟨font specification⟩ is an object which can contain any of the usual elements, as used in the SILE `\font` command. -The ⟨color specification⟩ follows the same syntax as defined in the SILE **color** package. +The ⟨color specification⟩ follows the same syntax as defined in the SILE *color* package. As an example, the following style results in a blue italic superscript in the Libertinus Serif font. @@ -35,12 +35,14 @@ my-custom-style-name: position: "super" ``` -#### Properties {.unnumbered} +{.unnumbered} +#### Properties The "properties" might be extended in a future revision; for now they support a position element, to specify a superscript or subscript formatting, and a text case element. The "normal" values may be used to override a parent style definition, when style inheritance is used. -#### Decorations {.unnumbered} +{.unnumbered} +#### Decorations The ⟨decoration specification⟩ is an object which can contain any of the following elements. @@ -70,7 +72,7 @@ It defaults to "solid" and "zizag" respectively. The "thickness" defaults to `0.5pt`. For instance, the `md-mark` style overrides the Markdown or Djot default rendering of the "highlight" syntax. -Let's ==mark some text== for the sake of demonstration, with the following style definition: +Let's {=mark some text=} for the sake of demonstration, with the following style definition: ```yaml md-mark: @@ -116,7 +118,8 @@ Some packages, however, accept negative "before kern" values for specific use cases. See, for instance, the section devoted to footnote markers. -#### Note on units {.unnumbered} +{.unnumbered} +#### Note on units As a rule of thumb, the "kern" widths can include stretch and shrink values (e.g. `10pt plus 2pt minus 1pt`). Be aware, however, that diff --git a/examples/manual-styling/basics/concepts.md b/examples/manual-styling/basics/concepts.dj similarity index 98% rename from examples/manual-styling/basics/concepts.md rename to examples/manual-styling/basics/concepts.dj index 8c243ce..da6439f 100644 --- a/examples/manual-styling/basics/concepts.md +++ b/examples/manual-styling/basics/concepts.dj @@ -53,7 +53,8 @@ and different vertical skips here or there? The styling paradigm offers a powerful generic abstraction towards that goal. -### An opinionated note on alternatives {.unnumbered .notoc} +{.unnumbered .notoc} +### An opinionated note on alternatives If you ever used (La)TeX, one possible way is to provide "hooks" that the user can change. At places, SILE follows that approach too---either via commands that diff --git a/examples/manual-styling/basics/definitions.md b/examples/manual-styling/basics/definitions.dj similarity index 100% rename from examples/manual-styling/basics/definitions.md rename to examples/manual-styling/basics/definitions.dj diff --git a/examples/manual-styling/basics/lists.md b/examples/manual-styling/basics/lists.dj similarity index 100% rename from examples/manual-styling/basics/lists.md rename to examples/manual-styling/basics/lists.dj diff --git a/examples/manual-styling/basics/paragraph.md b/examples/manual-styling/basics/paragraph.dj similarity index 92% rename from examples/manual-styling/basics/paragraph.md rename to examples/manual-styling/basics/paragraph.dj index 19f961a..30746b9 100644 --- a/examples/manual-styling/basics/paragraph.md +++ b/examples/manual-styling/basics/paragraph.dj @@ -29,6 +29,7 @@ there will be applied. The specification additionnaly provides: - The alignment of the paragraph block (center, left, right or justify---the latter is the default but may be useful to overwrite an inherited alignment). - Rules applying before the paragraph block: + - The amount of vertical space before the content, as a variable length or a named skip (such as `bigskip`, `medskip`, `smallskip`). - Whether paragraph indentation is applied to the first paragraph (defaults @@ -36,7 +37,9 @@ there will be applied. The specification additionnaly provides: for section titles not to be indented. - Whether a page break may occur before the block (defaults to `true`). - - Rules applying after the paragraph block + + - Rules applying after the paragraph block + - The amount of vertical space after the content, as a variable length or a named skip (such as `bigskip`, `medskip`, `smallskip`). - Whether paragraph indentation is applied to the next paragraph after the @@ -51,7 +54,8 @@ there will be applied. The specification additionnaly provides: the first paragraph indentation after a section title. The French convention, however, is to always indent regular paragraphs, even after a section title. -::: {custom-style="admon"} +{custom-style="admon"} +::: This version of the specification does not provide any way to configure the margins (left and right text block indents), internal skips, and other low-level paragraph formatting options (paragraph indent, etc.)[^styles-par-margins] @@ -59,8 +63,8 @@ low-level paragraph formatting options (paragraph indent, etc.)[^styles-par-marg [^styles-par-margins]: This might be considered in a future revision, but note that it may also be addressed by defining extra alignment options. -The **resilient.book** class, for instance, defines its own `block` alignment option -(used in block quotes, see further); the **resilient.verbatim** packages defines and `obeylines` alignment, etc. +The *resilient.book* class, for instance, defines its own `block` alignment option +(used in block quotes, see further); the *resilient.verbatim* packages defines and `obeylines` alignment, etc. Please note that changing an existing character style into a paragraph style does not imply that the content is magically turned into paragraphs. @@ -68,12 +72,13 @@ When classes or packages expect a character style at some point, only that part of the style definition is used. Classes and packages are responsible for applying the paragraph part too, depending on context. -### Note on consecutive skips {.unnumbered} +{.unnumbered} +### Note on consecutive skips Consider a "block quote" paragraph style, where you would expect some vertical spaces both above and below a quotation---say, small skips---to make it more distinct from the surrounding text. -The **resilient.book** class, for instance, provides the following default +The *resilient.book* class, for instance, provides the following default style definition. ```yaml diff --git a/examples/manual-styling/basics/sectioning.md b/examples/manual-styling/basics/sectioning.dj similarity index 89% rename from examples/manual-styling/basics/sectioning.md rename to examples/manual-styling/basics/sectioning.dj index 32d9c70..f0846ae 100644 --- a/examples/manual-styling/basics/sectioning.md +++ b/examples/manual-styling/basics/sectioning.dj @@ -30,8 +30,7 @@ With these first assumptions in mind, let’s summarize the requirements: to page headers, and so on.—The list of possibilities could be long here and very dependent on the kind of structure one considers, and it would be boresome to invent a syntax covering all potential needs, so some sort of “hook” has at least to be provided (more on that later). -- The main numbering, when used, may need some text strings prepended or appended to it, - (e.g. "Chapter 1.") + - The main numbering, when used, may need some text strings prepended or appended to it (e.g. "Chapter 1."), - When added to page headers (or in similar contexts), as per the supporting class design, one may want the section number to appear or not, and to be possibly formatted in a different way than in the ToC or in the main text flow. @@ -68,15 +67,12 @@ inheritance mechanism provided by the styles also allows one to reuse existing base specifications. In this author’s opinion, it is quite flexible and clear. The two last options, however, may require a clarification. -The `numberstyle` specification defines which number style should be used for -the section number, depending on the context where it appears (main text flow, -running headers and cross-references).^[In this version, the -numbering in the table of contents is handled with a different mechanism, -as a part of the ToC styles. Whether there is a need to reconcile these -solutions might be considered in a future revision.] +The `numberstyle` specification defines which number style should be used for the section number, depending on the context where it appears (main text flow, running headers and cross-references).[^toc-numbering-incertain] Note that if a given context is absent, the section number will not be displayed. -This might be sufficient to disable inherited numbering in some contexts, but -in these cases, you can just leave the `main` number style present but empty. +This might be sufficient to disable inherited numbering in some contexts, but in these cases, you can just leave the `main` number style present but empty. + +[^toc-numbering-incertain]: In this version, the numbering in the table of contents is handled with a different mechanism, as a part of the ToC styles. +Whether there is a need to reconcile these solutions might be considered in a future revision. For the "main" number style, some sections may expect the number to be on its own standalone line rather than just before the section title.—Chapters and parts, diff --git a/examples/manual-styling/basics/toc.md b/examples/manual-styling/basics/toc.dj similarity index 100% rename from examples/manual-styling/basics/toc.md rename to examples/manual-styling/basics/toc.dj diff --git a/examples/sile-resilient-manual.silm b/examples/sile-resilient-manual.silm index afaa1ad..25620f5 100644 --- a/examples/sile-resilient-manual.silm +++ b/examples/sile-resilient-manual.silm @@ -69,23 +69,23 @@ content: - manual-layouts/layouts.sil - file: manual-parts/part-styling.dj content: - - manual-styling/basics/concepts.md - - manual-styling/basics/definitions.md - - manual-styling/basics/character.md - - manual-styling/basics/lists.md - - manual-styling/basics/paragraph.md - - manual-styling/basics/toc.md - - manual-styling/basics/sectioning.md - - manual-styling/advanced/intro.md - - manual-styling/advanced/folio.md - - manual-styling/advanced/footnotes.md - - manual-styling/advanced/toclevels.md - - manual-styling/advanced/liststyles.md - - manual-styling/advanced/eqno.md - - manual-styling/advanced/dropcap.md - - manual-styling/advanced/other.md - # unfinished - # - manual-styling/captioned.md + - manual-styling/basics/concepts.dj + - manual-styling/basics/definitions.dj + - manual-styling/basics/character.dj + - manual-styling/basics/lists.dj + - manual-styling/basics/paragraph.dj + - manual-styling/basics/toc.dj + - manual-styling/basics/sectioning.dj + - manual-styling/advanced/intro.dj + - manual-styling/advanced/folio.dj + - manual-styling/advanced/footnotes.dj + - manual-styling/advanced/toclevels.dj + - manual-styling/advanced/liststyles.dj + - manual-styling/advanced/eqno.dj + - manual-styling/advanced/dropcap.dj + - manual-styling/advanced/other.dj + # Not written yet... + # - manual-styling/advanced/captioned.dj - file: manual-parts/part-packages.dj content: - manual-packages/packages.sil