Dave Jarvis' Repositories

Home Files Commits Tags Clone

Repository:

git clone https://repo.autonoma.ca/repo/keenwrite.git

Fixes broken export to text/markdown functionality

Author	DaveJarvis <email>
Date	2025-09-03 17:44:35 GMT-0700
Commit	bdd99ed92d7d8f8d33d3551e5f2dc9c35f228aed
Parent	e906bd2
Delta	35 lines added, 1125 lines removed, 1090-line decrease

src/main/java/com/keenwrite/processors/markdown/extensions/tex/TexInlineDelimiterProcessor.java

		final Delimiter opener,
		final Delimiter closer,
		- final int delimitersUsed ) {
		+ final int delimitersUsed
		+ ) {
		final var node = new TexNode( opener, closer );
		opener.moveNodesBetweenDelimitersTo( node, closer );

src/main/java/com/keenwrite/processors/markdown/extensions/tex/TexNodeRenderer.java

		*/
		private static class TexSvgNodeRenderer extends RendererFacade {
		- void render( final TexNode node,
		- final NodeRendererContext context,
		- final HtmlWriter html ) {
		+ void render(
		+ final TexNode node,
		+ final NodeRendererContext context,
		+ final HtmlWriter html
		+ ) {
		final var tex = node.getText().toStringOrNull();
		final var doc = MathRenderer.toDocument(

		*/
		private static class TexDelimitedNodeRenderer extends RendererFacade {
		- void render( final TexNode node,
		- final NodeRendererContext context,
		- final HtmlWriter html ) {
		+ void render(
		+ final TexNode node,
		+ final NodeRendererContext context,
		+ final HtmlWriter html
		+ ) {
		html.raw( TOKEN_OPEN );
		html.raw( getEvaluator().apply( node.getText().toString() ) );

docs/03-metadata.md

		-# Metadata
		-
		-Metadata is information about a document and often includes a title, author
		-name, copyright date, and keywords. Most systems require injecting metadata
		-directly into the document. {{app.title}} sources variable definitions from
		-an external file, allowing the same information to be applied to multiple
		-documents, without duplicating information or needing additional steps.
		-
		-Metadata can be mapped in the user preferences, shown in [@fig:gui-metadata].
		-When the document is exported to XHTML, the document metadata variables
		-are added to the `<head>` tag as `<meta>` tags.
		-
		-![Metadata screenshot](images/screenshots/09.png)
		-
		-:: Custom metadata {#fig:gui-metadata}
		-
		-
		-The Key column lists metadata names and the Value column lists the
		-metadata content for each corresponding Key. The content may include
		-references to variable definitions. When the document is typeset, the values
		-for the variables will be substituted upon export. When exporting to XHTML
		-format, the header will include the keys and values as `<meta>` tags. For
		-example:
		-
		-``` html
		-<head>
		- <title>Document Title</title>
		- <meta content="science, nature" name="keywords"/>
		- <meta content="Penn Surnom" name="author"/>
		- <meta content="4311" name="count"/>
		-</head>
		-```
		-
		-## Special metadata
		-
		-Certain metadata keys have special handling and formatting rules when documents are exported to different formats. When exporting the document, note the following special metadata:
		-
		-* count -- Document word count, always included.
		-* byline -- Replaces author in PDF metadata (e.g., for pen names).
		-* author -- Included as PDF metadata.
		-* keywords -- Included as PDF metadata.
		-* document.title -- Populates the `<title>` tag, not a `<meta>` tag.
		-
		-Except for count, all of these metadata variables can be customized.
		-

docs/04-cmd.md

		-# Command-line arguments
		-
		-This chapter covers how to use the application from the command line to convert Markdown and R Markdown files to various output formats. The application provides flexible options for batch processing and automation, making it suitable for both simple conversions and complex document generation workflows.
		-
		-The application may be run from the command-line to convert Markdown and R Markdown files to a variety of output formats. Without specifying any command-line arguments, the application will launch a graphical user interface.
		-
		-## Common arguments
		-
		-The following section outlines the most frequently used command-line arguments that provide essential functionality for document conversion and configuration.
		-
		-The most common command-line arguments to use include:
		-
		-* `-h` -- displays all command-line arguments, then exits.
		-* `-i` -- sets the input file name, must be a full path.
		-* `-o` -- sets the output file name, can be a relative path.
		-* `-s` -- sets a variable name and value at build time (dynamic data).
		-
		-## Example usage
		-
		-This section demonstrates practical examples of using the application from the command line, showing both simple and complex conversion scenarios across different operating systems.
		-
		-On Linux, simple usages include:
		-
		-``` bash
		-keenwrite.bin -i "${HOME}/document/01.md" -o document.xhtml
		-keenwrite.bin -i "${HOME}/document/01.md" -o document.md \
		- -v "${HOME}/document/variables.yaml"
		-```
		-
		-That command will convert `01.md` into the respective file formats. In the
		-first case, it will become an XHTML page. In the second case, it will become a
		-Markdown document with all variables interpolated and replaced.
		-
		-A more complex example follows:
		-
		-``` bash
		-keenwrite.bin \
		- -i "${HOME}/document/01.Rmd" \
		- -o document.pdf \
		- --image-dir="${HOME}/document/images" \
		- -v "${HOME}/document/variables.yaml" \
		- --metadata="title={{book.title}}" \
		- --metadata="author={{book.author}}" \
		- --r-dir="${HOME}/document/r" \
		- --r-script="${HOME}/document/r/bootstrap.R" \
		- --theme-dir="${HOME}/document/themes/boschet"
		-```
		-
		-That command will convert `01.Rmd` to `document.pdf` and replace the metadata using values from the variable definitions file.
		-
		-Directory or file names containing spaces must be quoted. For example, on Windows:
		-
		-``` bash
		-keenwrite.bin -i "C:\Users\My Documents\01.Rmd" -o document.pdf
		-```
		-

docs/05-svg.md

		-# SVG compatibility fixes
		-
		-This chapter addresses common compatibility problems that arise when using SVG files created in Inkscape. These issues can prevent proper rendering of vector graphics and result in missing or incorrectly displayed content.
		-
		-## Overview
		-
		-The Scalable Vector Graphics (SVG) drawing software---[EchoSVG](https://github.com/css4j/echosvg)---that's used by the application may be unable to read certain SVG files produced by [Inkscape](https://inkscape.org/). The result is that embedding the vector graphics files may trigger the following issues:
		-
		-* Unable to create nested element
		-* Black blocks, no text displayed
		-* Black text instead of coloured
		-
		-Let's see how to fix them.
		-
		-## Nested element issues
		-
		-This section covers problems related to `flowRoot` elements that can cause rendering failures when SVG files are processed.
		-
		-When referencing a vector graphic using Markdown, the status bar may show the following error:
		-
		-> The current document is unable to create an element of the requested type (namespace: http://www.w3.org/2000/svg, name: flowRoot).
		-
		-This error is due to a version mismatch of the `flowRoot` element that Inkscape creates.
		-
		-### Fix
		-
		-Resolve the issue by changing the SVG version number as follows:
		-
		-1. Edit the vector graphics file using any text editor.
		-1. Find `version="1.1"`.
		-1. Change the version to: `version="1.2"`.
		-1. Save the file.
		-
		-The SVG will now appear inside the application; however, the text may appear as black blocks.
		-
		-## Black blocks
		-
		-This section explains why text elements may render as solid black rectangles and provides steps to resolve this rendering issue.
		-
		-Depending on how text is added to a vector graphic in Inkscape, the text may be inserted within an element called a `flowRoot`. Although `flowRoot` is recognized, the contents may not be fully interpreted. Black blocks are drawn instead of the text, such as those depicted in [@fig:blocked-text].
		-
		-![Missing text](images/blocked-text.png)
		-
		-:: Missing text {#fig:blocked-text}
		-
		-### Fix
		-
		-Resolve the issue by "unflowing" all text elements as follows:
		-
		-1. Start Inkscape.
		-1. Load the SVG file.
		-1. Select all the text elements.
		-1. Click Text → Unflow.
		-
		-The text may change size and position; recreate the text without dragging using the text tool. After all the text areas have been recreated, continue as follows:
		-
		-1. Click Edit → XML Editor.
		-1. Expand the XML Editor to see more elements.
		-1. Delete all elements named `svg:flowRoot`.
		-1. Save the file.
		-
		-When the illustration is reloaded, the black blocks will have disappeared, but the text elements ignore any assigned colour.
		-
		-## Black text
		-
		-This section addresses issues where text renders in black instead of the intended colors due to Inkscape-specific font specification references.
		-
		-When an SVG `style` attribute contains a reference to `-inkscape-font-specification`, all values that follow said reference are ignored. This results in black text, shown in [@fig:blacked-text].
		-
		-![Black text](images/black-text.png)
		-
		-:: Missing text {#fig:blacked-text}
		-
		-### Fix
		-
		-Resolve the issue of colourless text as follows:
		-
		-1. Open the SVG file in a plain text editor.
		-1. Remove all references `-inkscape-font-specification:'<FONT>';`, including the trailing (or leading) semicolon.
		-1. Save the file.
		-
		-[@fig:resolved-text] shows colours having reappeared after reloading.
		-
		-![Resolved text](images/resolved-text.png)
		-
		-:: Resolved text {#fig:resolved-text}
		-

docs/06-r.md

		-# R
		-
		-This chapter describes how to add dynamic content to documents. It covers basic usage, working with scripts, managing the R working directory, and defining YAML variables.
		-
		-## Hello world
		-
		-Follow these steps to run R code within the application:
		-
		-1. Start the application.
		-1. Click File → New to create a new file.
		-1. Click File → Save As.
		-1. Set Name to: `addition.Rmd`
		-1. Click Save.
		-
		-Setting the file name extension tells the application what processor to use when transforming the contents for display in the preview tab. Continue by typing in the following text, including the backticks:
		-
		-```r
		-`r#1 + 1`
		-```
		-
		-The preview tab shows the result of `1` plus `1`:
		-
		-> 2.0
		-
		-## Bootstrap script
		-
		-Running R code while editing an R Markdown document is convenient. This section describes how to define and call custom R functions from your own library to leverage R's power.
		-
		-Complete the following steps to call an R function from your own library:
		-
		-1. Click File → New to create a new file.
		-1. Click File → Save As.
		-1. Browse to your home directory.
		-1. Set Name to: `library.R`.
		-1. Click Save.
		-1. Set the contents to:
		-
		- ```r
		- sum <- function( a, b ) {
		- a + b
		- }
		- ```
		-
		-1. Click the Save icon.
		-1. Click R → Script.
		-1. Set the R Startup Script contents to:
		-
		- ```r
		- source( 'library.R' );
		- ```
		-
		-1. Click OK.
		-1. Create a new file.
		-1. Set the contents to:
		-
		- ```r
		- `r#sum( 5, 5 )`
		- ```
		-
		-1. Save the file as `sum.R`.
		-
		-The preview tab shows the result of calling the `sum` function:
		-
		-> 10.0
		-
		-This shows how the bootstrap script can load `library.R`, which defines a `sum` function that is called by name in the Markdown document.
		-
		-## Working directory
		-
		-R files may be sourced from any directory, not just the user's home directory. This section explains how to change the working directory to manage source files flexibly.
		-
		-Accomplish this as follows:
		-
		-1. Click R → Directory.
		-1. Set Directory to a different directory.
		-1. Click OK.
		-1. Create the directory if it does not exist.
		-1. Move `library.R` into the directory.
		-1. Append a new function to `library.R` as follows:
		-
		- ```r
		- mul <- function( a, b ) {
		- a * b
		- }
		- ```
		-
		-1. Click R → Script.
		-1. Set the R Startup Script contents to:
		-
		- ```r
		- setwd( v$application$r$working$directory );
		- source( "library.R" );
		- ```
		-
		-1. Change `sum.Rmd` to:
		-
		- ```r
		- `r#mul( 5, 5 )`
		- ```
		-
		-1. Close the file `sum.Rmd`.
		-1. Confirm saving the file when prompted.
		-1. Re-open `sum.Rmd`.
		-
		-The preview tab shows:
		-
		-> 25.0
		-
		-Calling `setwd` using `v$application$r$working$directory` changes the working directory where the R engine searches for source files.
		-
		-## YAML variable definitions
		-
		-This section demonstrates how to use YAML files for defining variables that can be referenced dynamically within R code in the application.
		-
		-To see how variable definitions work in R, try the following:
		-
		-1. Create a new file.
		-1. Change the contents to (use spaces not tabs):
		-
		- ```yaml
		- project:
		- title: Project Title
		- author: Author Name
		- ```
		-
		-1. Save the file as `definitions.yaml`.
		-1. Click File → Open.
		-1. Set Source Files to Variable Files.
		-1. Select `definitions.yaml`.
		-1. Click Open.
		-1. Open `sum.Rmd` if it is not already open.
		-1. Type: `je`
		-1. Press [Ctrl+Space]{.kbd}.
		-
		-The editor inserts the following text (matches `je` against Project):
		-
		-```r
		-`r#x( v$project$title )`
		-```
		-
		-The preview tab shows:
		-
		-> Project Title
		-
		-This is because the application inserts variable reference names based on the type of file being edited. By default, the R engine does not have a function named `x` defined.
		-
		-Continue as follows:
		-
		-1. Click R → Script.
		-1. Append the following:
		-
		- ```r
		- x <- function( s ) {
		- tryCatch( {
		- r = eval( parse( text = s ) )
		-
		- ifelse( is.atomic( r ), r, s );
		- },
		- warning = function( w ) { s },
		- error = function( e ) { s } )
		- }
		- ```
		-
		-1. Click OK.
		-1. Close and re-open `sum.Rmd`.
		-
		-The preview tab shows:
		-
		-> 25.0
		->
		-> Project Title
		-
		-The `x` function attempts to evaluate the expression defined by the YAML variable. This means that the YAML variables can also include expressions that R is capable of evaluating.
		-
		-While the `x` function can be defined within the R Startup Script, it is better practice to put it into its own library so that it can be reused outside of the application.
		-

docs/07-typesetting.md

		-# Typesetting
		-
		-This chapter describes how to typeset PDF files using the ConTeXt typesetting system. It covers the steps from downloading and installing the typesetter software to applying themes and typesetting both single and multiple documents. Background information and additional resources are also included to give an in-depth understanding of the system.
		-
		-Broadly, typesetting PDF files entails the following:
		-
		-* Download and install typesetting software
		-* Download a theme pack
		-
		-These are described in the subsequent sections. Once the requirements have been met, continue reading to learn how to typeset a document.
		-
		-## Automatic setup
		-
		-The application uses the [ConTeXt](https://contextgarden.net) typesetting system, the [podman](https://podman.io/) container manager, various [themes](https://gitlab.com/DaveJarvis/keenwrite-themes), and numerous fonts to produce high-quality PDF files. The container manager significantly reduces the number of manual steps in the installation process.
		-
		-When exporting a document to a PDF file for the first time, a wizard will guide you through the installation process. These steps differ depending on the operating system.
		-
		-Run the installation wizard as follows:
		-
		-1. Start the application.
		-1. Click File → Export As → PDF.
		-
		-Follow the steps in the wizard to install the requisite software and typesetting themes.
		-
		-## Manual setup
		-
		-Download the typesetting software as follows:
		-
		-1. Start the text editor.
		-1. Click File → Export As → PDF.
		-1. Track the following details (e.g., Windows X86 64-bit):
		- * operating system name;
		- * instruction set; and
		- * architecture.
		-1. Click the [link](https://wiki.contextgarden.net/Introduction/Installation) in the dialog.
		-1. Download the appropriate archive file.
		-
		-Follow the steps that apply to the computer's operating system:
		-
		-* [Windows](#windows) (includes Windows 7, Windows 10, and similar)
		-* [Unix](#unix) (includes MacOS, FreeBSD, Linux, and similar)
		-
		-### Windows
		-
		-On a Windows installation, install the typesetting software as follows:
		-
		-1. Extract the `.zip` file into `C:\Users\%USERNAME%\AppData\Local\context` (the "root" directory).
		-1. Run install.bat to download and install the software.
		- * If prompted, click Run anyway (or click More info first).
		-1. Download [localpath.bat](https://repo.autonoma.ca/keenwrite.git/raw/HEAD/scripts/localpath.bat).
		-1. Save the file to the typesetting software's "root" directory.
		-1. Rename `localpath.bat.txt` to `localpath.bat`, if necessary.
		-1. Run `localpath.bat` (to set and save the `PATH` environment variable).
		-
		-Verify the installation is complete as follows:
		-
		-1. Type: `context --version`
		-1. Press [⏎ Enter]{.kbd}.
		-
		-If version information is displayed then the software is installed correctly.
		-
		-Continue by installing a [theme pack](#theme-pack).
		-
		-### Unix
		-
		-On Linux, MacOS, FreeBSD, and similar operating systems, proceed as follows:
		-
		-1. Open a terminal.
		-1. Run the following commands (change `LOCAL_FILE` to suit):
		-
		- ``` bash
		- export LOCAL_DIR=.local/bin/context
		- export LOCAL_FILE=context-linuxmusl-64.zip
		- export CONTEXT_DIR="${HOME}/${LOCAL_DIR}"
		- mkdir -p "${CONTEXT_DIR}"
		- cd "${CONTEXT_DIR}"
		- wget "https://lmtx.pragma-ade.nl/install-lmtx/${LOCAL_FILE}"
		- unzip ${LOCAL_FILE}
		- rm ${LOCAL_FILE}
		- chmod +x install.sh
		- ./install.sh
		- echo export CONTEXT_DIR=\"\${HOME}/${LOCAL_DIR}" \
		- >> ${HOME}/.bashrc
		- echo PATH="\"\${PATH}:\${CONTEXT_DIR}/tex/texmf-linux-64/bin\"" \
		- >> ${HOME}/.bashrc
		- source ${HOME}/.bashrc
		- ```
		-
		-Verify the installation is complete as follows:
		-
		-1. Type: `context --version`
		-1. Press [⏎ Enter]{.kbd}.
		-
		-If version information is displayed then the software is installed correctly.
		-
		-Continue by installing a [theme pack](#theme-pack).
		-
		-## Theme pack
		-
		-A theme pack is a set of themes that define how documents appear when typeset. Broadly, themes are applied as follows:
		-
		-* Install a theme pack
		-* Configure individual themes
		-
		-### Install theme pack
		-
		-Install and configure the default theme pack as follows:
		-
		-1. Download the <a href="https://gitlab.com/DaveJarvis/keenwrite-themes/-/releases/permalink/latest/downloads/theme-pack.zip">theme-pack.zip</a> archive.
		-1. Extract archive into a known location.
		-1. Start the text editor, if not already running.
		-1. Click Edit → Preferences.
		-1. Click Typesetting.
		-1. Click Browse beside Themes.
		-1. Navigate to the `themes` directory.
		-1. Click Open.
		-1. Click OK.
		-
		-The theme pack is installed.
		-
		-Each theme has its own requirements, described below.
		-
		-### Configure Boschet theme
		-
		-Download and install the following font families:
		-
		-* [Libre Baskerville](https://fonts.google.com/specimen/Libre+Baskerville)
		-* [Archivo Narrow](https://fonts.google.com/specimen/Archivo+Narrow)
		-* [Inconsolata](https://fonts.google.com/specimen/Inconsolata)
		-
		-The theme is configured.
		-
		-## Typeset single document
		-
		-Follow these steps to typeset a single document:
		-
		-1. Start the text editor, if not already running.
		-1. Click File → New (or type [Ctrl+n]{.kbd}).
		-1. Type in some text.
		-1. Click File → Export As → PDF (or type [Ctrl+p]{.kbd}).
		-1. Select a theme from the drop-down list.
		-1. Click OK (or press [⏎ Enter]{.kbd}).
		-1. Set the File name to the PDF file name.
		-1. Click Save.
		-
		-The document is typeset; open the PDF file in a PDF reader to view the result.
		-
		-## Typeset multiple documents
		-
		-Typeset multiple documents similar to single documents, with one difference:
		-
		-* Click File → Export As → Joined PDF (or type [Ctrl+Shift+p]{.kbd}).
		-
		-All documents having the same file name extension in the same directory
		-(or sub-directories) as the actively edited file are first concatenated then
		-typeset into a single PDF document. The order that files are concatenated
		-is numeric and alphabetic.
		-
		-For example, if `1.Rmd` is in the same directory hierarchy as the following
		-files, then all the files will be included in the PDF:
		-
		-```
		-chapter_1.Rmd
		-chapter_2a.Rmd
		-chapter_3.Rmd
		-chapter_10.Rmd
		-```
		-
		-Basically, sorting honours numbers and letters in file names.
		-
		-## Background
		-
		-This text editor helps keep content separated from presentation. Plain text documents will remain readable long after proprietary formats have become obsolete. However, we've come to expect much more in what we read than mere text: from hyperlinked tables of contents to indexes, from footers to footnotes, from mathematical expressions to complex graphics, modern documents are nuanced and multifaceted.
		-
		-### History
		-
		-Before computer-based typesetting, much of mathematics was put to page by hand. Professional typesetters, who were often expensive and usually not mathematicians, would inadvertently introduce typographic errors into equations. Phototypesetting technology improved upon hand-typesetting, but well-known computer scientist Donald Knuth---whose third volume of The Art of Computer Programming was phototypeset in 1976---expressed dissatisfaction with its typographic quality. He set himself two goals: let anyone create high-quality books without much effort and provide software that typesets consistently on all capable computers. Two years later, he released a typesetting system and a font description language: TeX and METAFONT, respectively.
		-
		-In short, TeX is software that helps typeset plain text documents.
		-
		-### ConTeXt
		-
		-Programming computers to typeset internationalized text automatically at the level we've become accustomed takes decades of development effort. Many free and open source software solutions can typeset text, including: ConTeXt, LaTeX, SILE, and others. ConTeXt, which builds upon TeX, is ideal for typesetting plain text into beautiful documents because it is developed with a notion of setups. These setups can wholly describe how text is to be typeset and---by being external to the text itself---configuring setups provides ample control over the document's final appearance without changing the prose.
		-
		-## Further reading
		-
		-Here are a few documents that introduce the typesetting system:
		-
		-* [What is ConTeXt?](https://www.pragma-ade.com/general/manuals/what-is-context.pdf)
		-* [A not so short introduction to ConTeXt](https://github.com/contextgarden/not-so-short-introduction-to-context)
		-* [Dealing with XML in ConTeXt MKIV](https://pragma-ade.com/general/manuals/xml-mkiv.pdf)
		-* [Typographic Programming](https://www.pragma-ade.com/general/manuals/style.pdf)
		-
		-The [documentation library](https://wiki.contextgarden.net/Documentation) includes the following gems:
		-
		-* [ConTeXt Manual](https://www.pragma-ade.nl/general/manuals/ma-cb-en.pdf)
		-* [ConTeXt command reference](https://www.pragma-ade.nl/general/qrcs/setup-en.pdf)
		-* [METAFUN Manual](https://www.pragma-ade.nl/general/manuals/metafun-p.pdf)
		-* [It's in the Details](https://www.pragma-ade.nl/general/manuals/details.pdf)
		-* [Fonts out of ConTeXt](https://www.pragma-ade.com/general/manuals/fonts-mkiv.pdf)
		-
		-Expert-level documentation includes the [LuaTeX Reference Manual](https://www.pragma-ade.nl/general/manuals/luatex.pdf).
		-

docs/08-div.md

		-# Fenced divs
		-
		-This chapter provides a comprehensive overview of the fenced div syntax used to
		-generate XHTML `div` elements within Markdown documents. It covers the basic,
		-extended, and nested syntax forms, illustrating how to structure fenced divs
		-and how they translate into XHTML.
		-
		-## Basic syntax
		-
		-This section explains the simplest form of fenced divs, outlining the minimal requirements to create an XHTML `div` element using Markdown.
		-
		-A fenced div has the following basic syntax:
		-
		-``` markdown
		-::: name
		-Content
		-:::
		-```
		-
		-To start a fenced div, begin a line with at least three colons (`:::`), followed by at least one space, followed by any word. Content may follow immediately on the next line. Terminate the fenced div with at least three colons. The terminating colons needn't match in number to the starting colons, but it's a good idea to maintain symmetry.
		-
		-The XHTML that is generated from the above fenced div will resemble:
		-
		-``` html
		-<div class="name">
		-<p>Content</p>
		-</div>
		-```
		-
		-## Extended syntax
		-
		-This section describes the extended syntax for fenced divs, which allows adding unique identifiers, multiple class names, and key/value data pairs to the generated XHTML `div`.
		-
		-A fenced div may use an extended syntax. The extended syntax can provide a unique identifier, multiple class names, and key/value data pairs. For example:
		-
		-``` markdown
		-::: {#poem-01 .stanza author="Emily Dickinson" year=1890}
		-Because I could not stop for Death --
		-He kindly stopped for me --
		-The Carriage held but just Ourselves --
		-And Immortality.
		-:::
		-```
		-
		-The above snippet produces:
		-
		-``` html
		-<div id="poem-01" class="stanza" data-author="Emily Dickinson" data-year="1890">
		-<p>Because I could not stop for Death –
		-He kindly stopped for me –
		-The Carriage held but just Ourselves –
		-And Immortality.</p>
		-</div>
		-```
		-
		-Note that when using the extended syntax, class styles must be prefixed with a period (e.g., `.stanza` in the example).
		-
		-## Nested syntax
		-
		-This section covers how fenced divs can be nested within one another, creating nested XHTML `div` structures.
		-
		-Fenced divs may be nested, such as in the following example:
		-
		-``` markdown
		-::: poem
		-:::::: stanza
		-Because I could not stop for Death --
		-He kindly stopped for me --
		-The Carriage held but just Ourselves --
		-And Immortality.
		-::::::
		-:::
		-```
		-
		-The above example produces:
		-
		-``` html
		-<div class="poem"><div class="stanza">
		-<p>Because I could not stop for Death –
		-He kindly stopped for me –
		-The Carriage held but just Ourselves –
		-And Immortality.</p>
		-</div></div>
		-```
		-

docs/09-quotes.md

		-# Quotation marks
		-
		-This chapter explores the history of quotation marks and the various encoding conventions used to represent straight single quotes as curled single quotes. It also discusses the typographical challenges faced in digital and print media, especially concerning apostrophes and quotation marks.
		-
		-Understanding how straight single quotes are converted into curled single quotes involves recognizing the different entities available for encoding. These options allow typographers and developers to select the most appropriate representation based on the context.
		-
		-[@tbl:quote-encoding] lists available encoding choices.
		-
		-\| Option \| Encoding \| Description \|
		-\| ---------- \| ---------- \| ----------- \|
		-\| regular \| \| Do not encode \|
		-\| apos \| `'` \| Curled when typeset to PDF \|
		-\| aposhex \| `'` \| Apostrophe's numeric value \|
		-\| quote \| `’` \| Right single quotation mark, typical for XHTML \|
		-\| quotehex \| `’` \| Right single quotation mark's numeric value \|
		-\| modifier \| `ʼ` \| The modifier letter apostrophe \|
		-
		-:: Single straight quote encoding options {#tbl:quote-encoding}
		-
		-When typesetting into a PDF document, only the semantically correct value of `'` will be curled automatically.
		-
		-## History
		-
		-The origins of quotation marks can be traced back to scholarly annotation
		-practices in Ancient Greece. Rather than punctuation embedded in the text,
		-Greek scribes used marginal symbols to highlight notable or quoted passages.
		-Chief among these was the diplé (`⟩`), a wedge-shaped mark placed beside lines
		-to signal commentary or quotation. A variant, the diplé periestigmene (`⸖`)---a
		-diplé accompanied by dots---was used by scholars to indicate disagreement with
		-earlier interpretations. These marks were not quotation marks in the modern
		-sense, but they laid the groundwork for distinguishing quoted or significant
		-text.
		-
		-By the seventeenth century, quotation marks began appearing regularly in
		-printed texts. During the nineteenth century, Western European typographers
		-adopted the convention of turning the convexity of quotation mark pairs
		-outward, giving rise to the familiar “double curved” style (« » or “ ”),
		-depending on the region.
		-
		-Early mechanical typewriters, dating from around 1825, lacked many punctuation
		-marks. As technology improved, additional keys were added, though some had dual
		-roles (for example, capital `I` often substituted for the number `1`). Straight
		-single and double quotes were used to represent quotation marks, apostrophes,
		-feet and inches, as well as primes and double-primes. Readers had enough
		-context to interpret meaning.
		-
		-Eventually, straight quotes were codified in computer character sets.
		-Apostrophes inherited the straight quote form, and standard encodings
		-failed to distinguish between typographic and semantic roles.
		-
		-Standards bodies later recommended using the right single quotation mark (’)
		-for apostrophes, which does not capture any semantic nuance because it is also
		-used to close dialogue. Consequently, English text---especially British
		-prose---is now riddled with typographic ambiguity.
		-
		-Consider the sentence:
		-
		-> Ambiguity lurks in \"\'cause the horses\'\".
		-
		-Does `'cause` mean _because_ or _induce_? The answer determines whether an open left single quote is used or an apostrophe, semantically speaking. This example highlights how historical typographical decisions still impact modern systems.
		-

docs/10-references.md

		-# Captions and cross-references
		-
		-This chapter provides an overview of captions and cross-references. Captions
		-provide context and descriptions for tables, figures, equations, and custom
		-types. Note that {{app.title}} diverges from CommonMark to provide a syntax
		-that is consistent and easier to remember.
		-
		-## Caption syntax
		-
		-Captions start with a double colon (`::`) separated by a blank line from the item that they are describing. Let's walk through a few examples.
		-
		-### Images
		-
		-For images, add the caption line as follows:
		-
		-``` markdown
		-![image title](https://placecats.com/300/200)
		-
		-:: Figure caption text
		-```
		-
		-The blank line between the item being captioned in the caption is important.
		-Without it, the software will treat the caption as if it was part of the
		-previous paragraph, and inline the text directly.
		-
		-### Table
		-
		-Caption tables in a similar manner:
		-
		-``` markdown
		-\| a \| b \| c \|
		-\|---\|---\|---\|
		-\| 1 \| 2 \| 3 \|
		-\| 4 \| 5 \| 6 \|
		-\| 7 \| 8 \| 9 \|
		-
		-:: Table caption text
		-```
		-
		-### Equation
		-
		-Equations are the same:
		-
		-``` markdown
		-$$E = mc^2$$
		-
		-:: Equation caption text
		-```
		-
		-## Cross-references
		-
		-Cross-references allow you to refer to tables, figures, equations, and headings
		-anywhere in the document using unique anchor names and reference tags. An
		-anchor name uniquely identifies an item, and multiple references may point to
		-it. Anchors are primarily added to captions to enable referencing.
		-
		-The general syntax is:
		-
		-- `{#type-name:label}` for defining an anchor name
		-- `[@type-name:label]` for referencing the anchor elsewhere
		-
		-The `type-name` is an alphanumeric category identifier starting with a letter or ideogram, and `label` is a unique identifier for the item.
		-
		-Consider this example illustrating an image with an anchor and cross-reference:
		-
		-``` markdown
		-In [@fig:animal], a cute animal is shown.
		-
		-![image title](https://placecats.com/300/200)
		-
		-:: World's cutest animal {#fig:animal}
		-
		-There is no cuter animal than the one in [@fig:animal].
		-```
		-
		-This example demonstrates how the anchor name `{#fig:animal}` defines the figure's location, and how the reference `[@fig:animal]` is used to refer to it.
		-
		-Anchors can include a wide variety of type names and labels, such as:
		-
		-``` markdown
		-{#fig:cats}
		-{#図版:猫}
		-{#eq:mass-energy}
		-{#eqn:laplace}
		-```
		-
		-## Type names
		-
		-To simplify writing captions and references, predefined type names correspond to labels commonly used in documents. These labels automatically generate appropriate names like Figure, Table, or Equation.
		-
		-[@tbl:type-names] lists predefined cross-reference type names along with their associated labels, which are inserted automatically into the document.
		-
		-\| Type name \| English name \|
		-\|-----------\|--------------\|
		-\| algorithm \| Algorithm \|
		-\| alg \| Algorithm \|
		-\| equation \| Equation \|
		-\| eqn \| Equation \|
		-\| eq \| Equation \|
		-\| figure \| Figure \|
		-\| fig \| Figure \|
		-\| formula \| Formula \|
		-\| listing \| Listing \|
		-\| list \| Listing \|
		-\| lst \| Listing \|
		-\| lyric \| Lyrics \|
		-\| music \| Score \|
		-\| score \| Score \|
		-\| source \| Listing \|
		-\| src \| Listing \|
		-\| tbl \| Table \|
		-\| table \| Table \|
		-\| tab \| Table \|
		-
		-:: Predefined Cross-Reference Types and Labels {#tbl:type-names}
		-
		-Using captions and cross-references improves document clarity and navigation by providing descriptive labels and links between related items.
		-

docs/11-gui.md

		-# Graphical user interface
		-
		-This chapter covers customizing the graphical user interface (GUI).
		-
		-## Internationalization
		-
		-Internationalization (I18N) support is essential for editing and previewing
		-text in multiple languages. Both fonts and language must be set for
		-non-Latin-based text. [@tbl:editor-font-families] lists example
		-Chinese-Japanese-Korean (CJK) font settings for the editor and preview tabs.
		-
		-\| Tab \| Font Family \| Language \|
		-\| ------- \| ----------------- \| ------------------ \|
		-\| Editor \| Noto Sans CJK KR \| Korean \|
		-\| Editor \| Noto Sans CJK JP \| Japanese \|
		-\| Editor \| Noto Sans CJK HN \| Chinese \|
		-\| Editor \| Noto Sans CJK SC \| Simplified Chinese \|
		-\| Preview \| Noto Serif CJK KR \| Korean \|
		-\| Preview \| Noto Serif CJK JP \| Japanese \|
		-\| Preview \| Noto Serif CJK HN \| Chinese \|
		-\| Preview \| Noto Serif CJK SC \| Simplified Chinese \|
		-
		-:: Editor and preview tab font families {#tbl:editor-font-families}
		-
		-### Editor font
		-
		-Follow these steps to change the editor font:
		-
		-1. Click Edit → Preferences.
		-1. Click Fonts.
		-1. Click Change under Editor Font.
		-1. Find the font name by typing or scrolling.
		-1. Click the desired font family.
		-1. Click OK.
		-1. Click Apply.
		-
		-The text editor font is changed.
		-
		-Note the following:
		-
		-* Install the desired fonts (restart the application).
		-* Enter font name directly if it cannot be selected.
		-
		-## Preview
		-
		-The preview tab uses two categories of fonts: regular and monospace.
		-
		-### Regular font
		-
		-To change the regular preview font, complete the following steps:
		-
		-1. Click Edit → Preferences.
		-1. Click Fonts.
		-1. Click Change under Preview Font for the Preview pane font name.
		-1. Find the font name by typing or scrolling.
		-1. Click the desired font family.
		-1. Click OK.
		-1. Click Apply.
		-
		-The regular preview font is changed.
		-
		-### Monospace font
		-
		-To change the monospace preview font, complete the following steps:
		-
		-1. Click Edit → Preferences.
		-1. Click Fonts.
		-1. Click Change under Preview Font for the Monospace font name.
		-1. Find the font name by typing or scrolling.
		-1. Click the desired font family.
		-1. Click OK.
		-1. Click Apply.
		-
		-The monospace font is changed.
		-
		-## Language
		-
		-Language settings control the locale used by the application, which is important when using CJK fonts or other locale-specific features.
		-
		-Change the locale as follows:
		-
		-1. Click Edit → Preferences.
		-1. Click Language.
		-1. Select a value for Locale.
		-1. Click Apply.
		-
		-The language is set.
		-
		-## Skins
		-
		-Skins define the visual style of the application, controlling colors, fonts, spacing, highlights, drop-shadows, gradients, and more. This section explains what skins are and their role in shaping the user interface.
		-
		-A skin is a set of styles---similar to cascading style sheet classes---that configures the user interface colours, fonts, spacing, highlights, drop-shadows, gradients, and so forth. See the [W3C CSS tutorial](https://www.w3.org/Style/Examples/011/firstcss) for details.
		-
		-### Order
		-
		-The order in which stylesheets are applied is important to ensure proper overriding of styles. The application loads and applies stylesheets to the user interface in the following order:
		-
		-1. scene.css --- Defines toolbar styling.
		-1. markdown.css --- Defines text editor styling.
		-1. skins/skin_name.css --- Main application chrome, extensible.
		-1. custom.css --- User-defined preferences.
		-
		-### Customization
		-
		-This section walks through creating and applying a custom skin step-by-step, allowing users to personalize their application's appearance.
		-
		-Create a custom skin as follows:
		-
		-1. Start the application.
		-1. Click File → New to create a new file.
		-1. Click File → Save As to rename the file.
		-1. Save the file as `custom.css`.
		-1. Change the content to the following:
		-
		- ``` css
		- .root {
		- -fx-base: rgb( 30, 30, 30 );
		- -fx-background: -fx-base;
		- }
		- ```
		-
		-Apply the skin as follows:
		-
		-1. Click Edit → Preferences to open the preferences dialog.
		-1. Click Skins to view the available options.
		-1. Click Browse to select a custom file.
		-1. Browse to and select `custom.css`, created previously.
		-1. Click Open.
		-1. Click Apply.
		-
		-The user interface immediately changes to a dark mode. Continue:
		-
		-1. Click OK to close the dialog.
		-1. Change the rgb numbers in custom.css from `30` to `60`.
		-1. Click File → Save to save the CSS file.
		-
		-The user interface immediately changes colour.
		-
		-### Classes
		-
		-For more control, this section explains how to use pre-existing skin templates with defined classes, making it easier to tweak the GUI. Accomplish this as follows:
		-
		-1. Visit the [skin](https://repo.autonoma.ca/keenwrite.git/tree/main/src/main/resources/com/keenwrite/skins) repository directory
		-1. Click one of the files (e.g., `haunted_grey.css`).
		-1. Click Raw.
		-1. Copy the entire text.
		-1. Return to `custom.css`.
		-1. Delete the contents.
		-1. Paste the copied text.
		-1. Save the file.
		-
		-To see how the CSS styles are applied to the text editor, open [markdown.css](https://repo.autonoma.ca/keenwrite.git/blob/main/src/main/resources/com/keenwrite/editor/markdown.css), which is also in the repository.
		-
		-### Modena
		-
		-This section describes the default look used by the application and points to resources for fully customizing the UI beyond basic changes.
		-
		-The basic look used by the application is _Modena Light_. Typically we only need to override a few classes to completely change the application's look and feel. For a full listing of available styles see the OpenJDK's [Modena CSS file](https://github.com/openjdk/jfx/blob/master/modules/javafx.controls/src/main/resources/com/sun/javafx/scene/control/skin/modena/modena.css).
		-
		-### JavaFX CSS
		-
		-JavaFX CSS have advanced styling capabilities. The [Java CSS Reference Guide](https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/doc-files/cssref.html) shows differences between JavaFX CSS and W3C CSS. The guide covers functions for manipulating colours and gradients using existing colour definitions.
		-
		-### RichTextFX
		-
		-The application uses RichTextFX to render the text editor. Styling various text editor classes can require using the prefix `-rtfx` instead of the regular JavaFX `-fx`.
		-

docs/12-screenshots.md

		-# Screenshots
		-
		-This chapter provides application screenshots from an older version.
		-
		-## Variables
		-
		-Diagrams that include variables are shown in [@fig:screenshot-diagram-graphviz]
		-and [@fig:screenshot-diagram-genealogy].
		-
		-![GraphViz diagram screenshot](images/screenshots/01.png)
		-
		-:: GraphViz diagram {#fig:screenshot-diagram-graphviz}
		-
		-![Family tree diagram screenshot](images/screenshots/05.png)
		-
		-:: Family tree diagram {#fig:screenshot-diagram-genealogy}
		-
		-## PDF themes
		-
		-The background of [@fig:screenshot-pdf-themes] depicts a novel being edited.
		-
		-![PDF themes](images/screenshots/08.png)
		-
		-:: PDF Themes {#fig:screenshot-pdf-themes}
		-
		-Highlighted items of note:
		-
		-* PDF icon in the upper-left
		-* Novel metadata as integrated variables towards the top-left
		-* Theme selection dialog in the upper-middle
		-* Three different styles, including:
		- * Boschet, based on Baskerville font, nicely styled
		- * Handrit, based on Courier font, double-spaced, manuscript format
		- * Tarmes, based on Times Roman font, minimal styling
		-* Variations in page numbers
		-* Manuscript includes word count, automatically
		-* Preferences dialog in the middle
		-
		-## Internationalization
		-
		-[@fig:screenshot-locale] shows a poem with locale settings:
		-
		-![Korean poem screenshot](images/screenshots/02.png)
		-
		-:: Locale settings {#fig:screenshot-locale}
		-
		-## Equations
		-
		-[@fig:screenshot-tex] shows TeX equations in a detached preview tab:
		-
		-![TeX equations screenshot](images/screenshots/03.png)
		-
		-:: TeX equations {#fig:screenshot-tex}
		-
		-## Dockable tabs
		-
		-[@fig:screenshot-outline] shows a document outline opened and docked in
		-bottom-left corner:
		-
		-![Document outline](images/screenshots/04.png)
		-
		-:: Document outline {#fig:screenshot-outline}
		-

docs/13-architecture.md

		-# Architecture overview
		-
		-[@fig:architecture] illustrates the high-level application architecture for converting Markdown documents. The architecture is a processing pipeline that transforms raw Markdown content through multiple stages to produce the final output.
		-
		-``` diagram-graphviz
		-digraph {
		- node [fontname = "Noto Sans" fontsize=6 height=.25 penwidth=.5];
		- edge [fontname = "Noto Sans" fontsize=6 penwidth=.5 arrowsize=.5];
		- node [shape=box color="{{app.palette.primary.light}}" fontcolor="{{app.palette.primary.dark}}"]
		- edge [color="{{app.palette.grayscale.light}}" fontcolor="{{app.palette.grayscale.dark}}"]
		- {{app.classes.processors.variable.definition}} -> {{app.classes.processors.markdown}} [xlabel="{{app.graph.label.chain.next}} "]
		- {{app.classes.processors.markdown}} -> {{app.classes.processors.preview}} [xlabel="{{app.graph.label.chain.next}} "]
		- {{app.classes.processors.markdown}} -> Extensions [label=" contains"]
		-Extensions -> FencedBlockExtension
		-Extensions -> CaretExtension
		-Extensions -> ImageLinkExtension
		-Extensions -> TeXExtension
		-}
		-```
		-
		-:: Architecture overview {#fig:architecture}
		-
		-## Extension System Architecture
		-
		-An extension is an addition to the Markdown parser, flexmark-java, that is used
		-when converting the document's abstract syntax tree into an XHTML document. The
		-`{{app.classes.processors.markdown}}` contains both prepackaged and custom
		-extensions. This extensible architecture allows for specialized processing of
		-various Markdown elements, enabling support for advanced features like
		-mathematical expressions, enhanced image handling, and custom block types.
		-

docs/14-credits.md

		-# Acknowledgments
		-
		-Contributors and inspirations behind the application include:
		-
		-* Tomas Mikula: [RichTextFX](https://github.com/TomasMikula/RichTextFX), [WellBehavedFX](https://github.com/TomasMikula/WellBehavedFX), [Flowless](https://github.com/TomasMikula/Flowless), and [UndoFX](https://github.com/TomasMikula/UndoFX)
		-* Jens Deters: [FontAwesomeFX](https://bitbucket.org/Jerady/fontawesomefx)
		-* Dieter Holz: [PreferencesFX](https://github.com/dlsc-software-consulting-gmbh/PreferencesFX)
		-* David Croft: [File Preferences](http://www.davidc.net/programming/java/java-preferences-using-file-backing-store)
		-* Alex Bertram: [Renjin](https://www.renjin.org/)
		-* Vladimir Schneider: [flexmark](https://github.com/vsch/flexmark-java)
		-* Alberto Fernández, Shy Shalom, Kohei Taketa: [juniversalchardet](https://github.com/takscape/juniversalchardet)
		-* Morten Nobel-Jørgensen: [Java Image Scaling](https://github.com/mortennobel/java-image-scaling)
		-
		-Original concept:
		-
		-* Karl Tauber: [Markdown Writer FX](https://github.com/JFormDesigner/markdown-writer-fx)
		-
		-Typesetting system:
		-
		-* Hans Hagen: [ConTeXt](https://www.pragma-ade.com/)
		-

docs/build.sh

		-o user-manual.pdf \
		--variables=$(pwd)/metadata.yaml \
		- --metadata=title={{document.title}} \
		- --metadata=subtitle={{document.subtitle}} \
		- --metadata=copyright={{document.copyright}} \
		- --metadata=version=$(git describe --tags --abbrev=0) \
		+ --metadata="title={{document.title}}" \
		+ --metadata="subtitle={{document.subtitle}}" \
		+ --metadata="copyright={{document.copyright}}" \
		+ --metadata="version=$(git describe --tags --abbrev=0)" \
		--theme-dir="$HOME/dev/java/keenwrite/themes/texomus"

docs/metadata.yaml

		chain:
		next: successor
		+fonts:
		+ protocol: 'https'
		+ server: 'fonts.keenwrite.com'
		+ path: '/download'
		+ url: "{{fonts.protocol}}://{{fonts.server}}/{{fonts.path}}"
		+
		+repository:
		+ protocol: 'https'
		+ server: 'repo.autonoma.ca'
		+ url: "{{repository.protocol}}://{{repository.server}}"
		+
		+install:
		+ windows:
		+ batch: "{{repository.url}}/keenwrite.git/raw/HEAD/scripts/localpath.bat"
		+
		+skins:
		+ url:
		+ main: "{{repository.url}}/keenwrite.git/tree/main/src/main/resources/com/keenwrite/skins"
		+ markdown: "{{repository.url}}/keenwrite.git/blob/main/src/main/resources/com/keenwrite/editor/markdown.css"

docs/user-manual.pdf

Binary files differ