Dave Jarvis' Repositories

Home Files Commits Tags Clone

Repository:

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

Changes documentation headings and structure

Author	DaveJarvis <email>
Date	2025-08-28 15:01:58 GMT-0700
Commit	a44a23deff7b125adf5f9a6a9a30694b3847e388
Parent	1d7a78d
Delta	350 lines added, 370 lines removed, 20-line decrease

docs/02-variables.md

		-# Introduction
		-
		-This document describes how to use the application.
		-
		# Variable definitions


		Save the variable definitions in a file having an extension of `.yaml` or `.yml`.

		-# Document editing
		+## Document editing

		The application's purpose is to completely separate the document's content from its presentation. To achieve this, documents are composed using a [plain text](http://spec.commonmark.org/0.28/) format.

		-## Create document
		+### Create document

		Start a new document as follows:

		The variable definitions appear in the variable definition pane under the heading of Variables.

		-## Edit document
		+### Edit document

		Edit the document as normal. Notice how the preview pane updates as new content is added. The toolbar shows various icons that perform different formatting operations. Try them to see how they appear in the preview pane. Other operations not shown on the toolbar include:

		* Struck text (enclose the words within `~~` and `~~`)
		* Horizontal rule (use `---` on an otherwise empty line).

		The preview pane shows one way to interpret and format the document, but many other presentations are possible.

		-## Insert variable
		+### Insert variable

		Let's assume that the variable definitions loaded into the application include:

docs/03-metadata.md

		-# Document metadata
		+# Document Metadata Management
		+
		+This chapter covers the fundamentals of document metadata, including basic metadata concepts, custom metadata configuration, and special metadata handling during document export.
		+
		+## Document metadata

		Document metadata is information about a document. Metadata often includes
		a title, author name, copyright date, and keywords.

		-# Custom metadata
		+## Custom metadata
		+
		+Custom metadata allows you to define specific key-value pairs for your documents with variable substitution capabilities.

		The following screenshot shows example metadata preferences:

		```

		-# Special metadata
		+## 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:

docs/04-cmd.md

		# Command-line arguments

		-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.
		+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:

		## Example usage

		-On Linux, simple usages include:
		+This section demonstrates practical examples of using the application from the command line, showing both simple and complex conversion scenarios across different operating systems.

		- keenwrite.bin -i $HOME/document/01.md -o document.xhtml
		+On Linux, simple usages include:

		- keenwrite.bin -i $HOME/document/01.md -o document.md \
		- -v $HOME/document/variables.yaml
		+```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 HTML page. In the second case, it will
		-become a Markdown document with all variables interpolated and replaced.
		+That command will convert `01.md` into the respective file formats. In the first case, it will become an HTML page. In the second case, it will become a Markdown document with all variables interpolated and replaced.

		A more complex example follows:

		- 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
		+```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.
		+That command will convert `01.Rmd` to `document.pdf` and replace the metadata using values from the variable definitions file.

		Directory names containing spaces must be quoted. For example, on Windows:

		- keenwrite.bin -i "C:\Users\My Documents\01.Rmd" -o document.pdf
		+```bash
		+keenwrite.bin -i "C:\Users\My Documents\01.Rmd" -o document.pdf
		+```

docs/05-diagram.md

		-# Introduction
		+# Architecture overview

		-From a high level, the application architecture for converting Markdown documents is captured in the following figure:
		+The high-level application architecture for converting Markdown documents demonstrates a sophisticated processing pipeline that transforms raw Markdown content through multiple stages to produce the final output. This architecture emphasizes modularity and extensibility through its processor chain design.

		-``` diagram-graphviz
		+```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="{{keenwrite.palette.primary.light}}" fontcolor="{{keenwrite.palette.primary.dark}}"]
		edge [color="{{keenwrite.palette.grayscale.light}}" fontcolor="{{keenwrite.palette.grayscale.dark}}"]
		-
		- {{keenwrite.classes.processors.variable.definition}} -> {{keenwrite.classes.processors.markdown}} [xlabel="{{keenwrite.graph.label.chain.next}} "]
		+ {{keenwrite.classes.processors.variable.definition}} -> {{keenwrite.classes.processors.markdown}} [xlabel="{{keenwrite.graph.label.chain.next}} "]
		{{keenwrite.classes.processors.markdown}} -> {{keenwrite.classes.processors.preview}} [xlabel="{{keenwrite.graph.label.chain.next}} "]
		{{keenwrite.classes.processors.markdown}} -> Extensions [label=" contains"]
		-
		Extensions -> FencedBlockExtension
		Extensions -> CaretExtension
		Extensions -> ImageLinkExtension
		Extensions -> TeXExtension
		}
		```

		-An extension is an addition to the Markdown parser, flexmark-java, that is used when converting the document's abstract syntax tree into an HTML document. The {{keenwrite.classes.processors.markdown}} contains both prepackaged and custom extensions.
		+## 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 HTML document. The {{keenwrite.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/06-svg.md

		-# Introduction
		+# SVG Compatibility Fixes
		+
		+This chapter addresses common compatibility problems that arise when using SVG files created in Inkscape with the Batik SVG drawing software. 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---[Batik](https://xmlgraphics.apache.org/batik/)---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

		The remainder of this document explains these problems and how to fix them.

		-# Nested element
		+## Nested Element Issues
		+
		+This section covers problems related to flowRoot elements that can cause rendering failures when SVG files are processed by Batik.

		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
		+### 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"` and change it to `version="1.2"`.
		-1. Save the file.
		+2. Find `version="1.1"` and change it to `version="1.2"`.
		+3. Save the file.

		The SVG will now appear inside the application; however, the text may appear as black blocks.

		-# 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 Batik recognizes `flowRoot` for SVG version 1.2, it cannot fully interpret the contents. Black blocks are drawn instead of the text, such as those depicted in the following figure:

		![Missing text](images/blocked-text.png)

		-## Fix
		+### 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.
		+2. Load the SVG file.
		+3. Select all the text elements.
		+4. 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.
		+2. Expand the XML Editor to see more elements.
		+3. Delete all elements named `svg:flowRoot`.
		+4. Save the file.

		When the illustration is reloaded, the black blocks will have disappeared, but the text elements ignore any assigned colour.

		-# Black text
		+## 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`, Batik ignores all values that follow said reference. This results in black text, such as:

		![Black text](images/black-text.png)

		-## Fix
		+### 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.
		+2. Remove all references `-inkscape-font-specification:'<FONT>';`, including the trailing (or leading) semicolon.
		+3. Save the file.

		When the illustration is reloaded, the colours will have reappeared, such as:

docs/07-r.md

		-# Introduction
		+# R

		-This document describes how to use the [R](https://www.r-project.org/)
		-programming language from within the application. The application uses an
		-interpreter known as [Renjin](https://www.renjin.org/) to integrate with R.
		+This chapter provides a comprehensive guide on how to use the R programming language from within the application using the Renjin interpreter. It covers basic usage, working with scripts, managing the working directory, and defining YAML variables for dynamic content.

		-# Hello world
		+## Introduction

		-Complete the following steps to see R in action:
		+This section explains the overall context of integrating R via Renjin in the application. Renjin is an interpreter that allows R code execution inside the application environment.
		+
		+## Hello world
		+
		+Follow these steps to get started with running R code and seeing immediate results 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 pane. Continue
		-by typing in the following text, including the backticks:
		+Setting the file name extension tells the application what processor to use when transforming the contents for display in the preview pane. Continue by typing in the following text, including the backticks:

		```r

		```

		-# Bootstrap script
		+## Bootstrap script

		-Being able to run R code while editing an R Markdown document is convenient.
		-Having the ability to call functions is where the power of R can be
		-leveraged.
		+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
		- }
		- ```
		+
		+```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' );
		- ```
		+
		+```r
		+source( 'library.R' );
		+```
		+
		1. Click OK.
		1. Create a new file.
		1. Set the contents to:
		- ``` r
		- `r#sum( 5, 5 )`
		- ```
		+
		+```r
		+`r#sum( 5, 5 )`
		+```
		+
		1. Save the file as `sum.R`.

		The preview panel 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.
		+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
		+## Working directory

		-R files may be sourced from any directory, not just the user's home
		-directory. Accomplish this as follows:
		+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
		- }
		- ```
		+
		+```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" );
		- ```
		+
		+```r
		+setwd( v$application$r$working$directory );
		+source( "library.R" );
		+```
		+
		1. Change `sum.Rmd` to:
		- ``` r
		- `r#mul( 5, 5 )`
		- ```
		+
		+```r
		+`r#mul( 5, 5 )`
		+```
		+
		1. Close the file `sum.Rmd`.
		1. Confirm saving the file when prompted.

		```

		-Calling `setwd` using `v$application$r$working$directory` changes the
		-working directory where the R engine searches for source files.
		+Calling `setwd` using `v$application$r$working$directory` changes the working directory where the R engine searches for source files.

		-# YAML variable definitions
		+## 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
		- ```
		+
		+```yaml
		+project:
		+ title: Project Title
		+ author: Author Name
		+```
		+
		1. Save the file as `definitions.yaml`.
		1. Click File → Open.

		The editor inserts the following text (matches `je` against Project):

		-``` r
		+```r
		`r#x( v$project$title )`
		```

		The preview panel shows:

		```
		r#x( '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.
		+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 } )
		- }
		- ```
		+```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 `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.
		+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.
		+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/08-typesetting.md

		# Typesetting

		-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.
		+This chapter explains the typesetting system used by the application and provides step-by-step guidance for exporting documents to PDF for the first time. It covers the core components involved and details the installation wizard process.

		-When exporting a document to a PDF file for the first time, a series of
		-semi-automated steps guides users through the installation process. These
		-steps differ depending on the operating system.
		+## Tooling
		+
		+This section describes the key tools and technologies the application leverages to produce high-quality PDF files.
		+
		+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 series of semi-automated steps guides users 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.
		+Follow the steps in the wizard to install the requisite software and typesetting themes.

docs/09-typesetting-custom.md

		-# Overview
		+# Typesetting
		+
		+This chapter provides a comprehensive guide on 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 a fuller understanding of the system.

		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.

		-# Download typesetter
		+## Download typesetter

		Download the typesetting software as follows:

		1. Download the appropriate archive file.

		-# Install typesetter
		+## Install typesetter

		This section describes the installation steps for various platforms. 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
		+### Windows

		Proceed with a Windows installation of the typesetting software as follows:

		Continue by installing a [theme pack](#theme-pack).

		-## Unix
		+### Unix

		For Linux, MacOS, FreeBSD, and similar operating systems, proceed as follows:

		Continue by installing a [theme pack](#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 theme pack

		Install and configure the default theme pack as follows:

		The theme pack is installed.

		-Each theme has its own requirements, described below.
		+Each theme has its own requirements, described below.

		-## Configure Boschet theme
		+### 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
		+## Typeset single document

		-Typeset a document as follows:
		+Follow these steps to typeset a single document:

		1. Start the text editor, if not already running.

		The document is typeset; open the PDF file in a PDF reader to view the result.

		-# Typeset multiple documents
		+## Typeset multiple documents

		Typeset multiple documents similar to single documents, with one difference:

		directory, then all the files will be included in the PDF, as expected:

		- chapter_1.Rmd
		- chapter_2.Rmd
		- chapter_2a.Rmd
		- chapter_2b.Rmd
		- chapter_3.Rmd
		- chapter_10.Rmd
		+```
		+chapter_1.Rmd
		+chapter_2.Rmd
		+chapter_2a.Rmd
		+chapter_2b.Rmd
		+chapter_3.Rmd
		+chapter_10.Rmd
		+```

		Basically, sorting honours numbers and letters in file names.

		-# Background
		+## 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
		+### 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
		+### 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
		+## Further reading

		Here are a few documents that introduce the typesetting system:

docs/10-skins.md

		# Skins

		-The application provides bundled skins and the ability to add custom
		-skins. This document describes the interplay between bundled skins
		-and building your own look and feel.
		+This chapter provides a comprehensive overview of how skins are managed and customized within the application. It covers bundled skins, the order of stylesheet application, creating custom skins, available CSS classes, and useful resources for advanced styling.

		-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 more.
		+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 more.

		For more information on CSS, see the [W3C CSS tutorial](https://www.w3.org/Style/Examples/011/firstcss).

		-# Order
		+## Order

		-The order that stylesheets are applied matters so that stylesheets can
		-override styles defined previously. The application's user interface
		-is made up of the following stylesheets, applied in the order listed:
		+The order in which stylesheets are applied is important to ensure proper overriding of styles. This section details the sequence in which the application loads stylesheets to achieve the desired look.
		+
		+The application's user interface is made up of the following stylesheets, applied in the order listed:

		* scene.css --- Defines toolbar styling.
		* markdown.css --- Defines text editor styling.
		* skins/skin_name.css --- Bundled skin selected in preferences.
		* custom.css --- User-defined file set in preferences.

		-# Customization
		+## 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
		+
		+```css
		.root {
		-fx-base: rgb( 30, 30, 30 );

		The user interface immediately changes colour.

		-# Classes
		+## Classes

		-When creating your own skin, there many classes that can be styled. The
		-previous section showed how to set up a rudimentary skin. Instead, start
		-with a template that already has a number of classes defined so that you
		-can tweak them to your taste. Accomplish this as follows:
		+For users who want more control, this section explains how to use pre-existing skin templates with defined classes, making it easier to tweak the look to your preferences.
		+
		+When creating your own skin, there many classes that can be styled. The previous section showed how to set up a rudimentary skin. Instead, start with a template that already has a number of classes defined so that you can tweak them to your taste. Accomplish this as follows:

		1. Visit the [skin](https://gitlab.com/DaveJarvis/KeenWrite/-/tree/main/src/main/resources/com/keenwrite/skins) repository directory

		1. Save the file.

		-To see how the CSS styles are applied to the text editor, open
		-[markdown.css](https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/src/main/resources/com/keenwrite/editor/markdown.css), which is also in the repository.
		+To see how the CSS styles are applied to the text editor, open [markdown.css](https://gitlab.com/DaveJarvis/KeenWrite/-/blob/main/src/main/resources/com/keenwrite/editor/markdown.css), which is also in the repository.

		-# Modena
		+## Modena

		-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).
		+This section describes the default look used by the application and points to resources for fully customizing the UI beyond basic changes.

		-# JavaFX CSS
		+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).

		-The [Java CSS Reference Guide](https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/doc-files/cssref.html) is exhaustive. In addition to showing many
		-differences between JavaFX CSS and W3C CSS, the guide introduces numerous
		-helpful functions for manipulating colours and gradients using existing
		-colour definitions.
		+## JavaFX CSS

		-# RichTextFX
		+Learn about JavaFX CSS differences and advanced styling capabilities in this section, with links to the official exhaustive reference.

		-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`.
		+The [Java CSS Reference Guide](https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/doc-files/cssref.html) is exhaustive. In addition to showing many differences between JavaFX CSS and W3C CSS, the guide introduces numerous helpful functions for manipulating colours and gradients using existing colour definitions.

		-# Submit
		+## RichTextFX

		-If you have a look that you'd like to contribute to the project, do pass
		-it along. Either open a new issue in the [issue tracker](https://gitlab.com/DaveJarvis/KeenWrite/-/issues) that contains the CSS file or submit a pull request.
		+This section explains the specific prefix usage for styling the text editor, which uses the RichTextFX library.
		+
		+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`.
		+
		+## Submit
		+
		+If you create a skin you would like to share, this section explains how to contribute it back to the project.
		+
		+If you have a look that you'd like to contribute to the project, do pass it along. Either open a new issue in the [issue tracker](https://gitlab.com/DaveJarvis/KeenWrite/-/issues) that contains the CSS file or submit a pull request.
		+

docs/11-div.md

		-# Fenced divs
		+# Fenced Divs

		-This section describes the syntax to generate HTML `div` elements. The
		-syntax is known as a _fenced div_.
		+This chapter provides a comprehensive overview of the fenced div syntax used to generate HTML `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 HTML.

		-# Basic syntax
		+## Basic syntax
		+
		+This section explains the simplest form of fenced divs, outlining the minimal requirements to create an HTML `div` element using Markdown.

		A fenced div has the following basic syntax:

		-``` markdown
		+```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.
		+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 HTML that is generated from the above fenced div will resemble:

		-``` html
		+```html
		<div class="name">
		<p>Content</p>
		</div>
		```

		-# Extended syntax
		+## Extended syntax

		-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:
		+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 HTML `div`.

		-``` markdown
		+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 —

		The above snippet produces:

		-``` html
		+```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).
		+Note that when using the extended syntax, class styles must be prefixed with a period (e.g., `.stanza` in the example).

		-# Nested syntax
		+## Nested syntax
		+
		+This section covers how fenced divs can be nested within one another, creating nested HTML `div` structures.

		Fenced divs may be nested, such as in the following example:

		-``` markdown
		+```markdown
		::: poem
		:::::: stanza

		The above example produces:

		-``` html
		+```html
		<div class="poem"><div class="stanza">
		<p>Because I could not stop for Death —

docs/12-quotes.md

		-# Quotation marks
		+# Quotation Marks

		-When converting straight single quotes into curled single quotes, the
		-application offers a variety of entities to use for encoding:
		+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.
		+
		+The application offers several encoding choices:

		* regular -- Do not encode.
		* modifier -- Encode as \ʼ, the modifier letter apostrophe.
		* apos -- Encode as \', curled when typeset to PDF.
		* aposhex -- Encode as \', the apostrophe's numeric value.
		-* quote -- Encode as \’, the right single quotation mark, which
		-is typically curled in HTML and XHTML documents by default.
		-* quotehex -- Encode \’, the right single quotation mark's numeric
		-value.
		+* quote -- Encode as \’, the right single quotation mark, which is typically curled in HTML and XHTML documents by default.
		+* quotehex -- Encode \’, the right single quotation mark's numeric value.

		-When typsetting into a PDF document, only the semantically correct value
		-of \' will be curled automatically.
		+When typesetting into a PDF document, only the semantically correct value of \' will be curled automatically.

		-# History
		+## History

		-Quotation marks trace back to Ancient Greek, later adopted to the diplé (⸖)
		-circa 625 BCE, foreshadowing its later curve. By the seventeenth century,
		-quotation marks grew common. During the nineteenth century, Western Europe
		-turned the convexity of quotation mark pairs outward.
		+The origins of quotation marks can be traced back to Ancient Greek, where they were later adopted as the diplé (⸖) around 625 BCE. This early form foreshadowed the curved shape of modern quotation marks.

		-Early mechanical typewriters, circa 1825, lacked many punctuation marks. As
		-technology improved, additional keys were added while some keys played dual
		-roles (such as I for 1). Straight single and double quotes could be co-opted
		-for quotation marks and apostrophes, feet and inches marks, and primes and
		-double-primes. There wasn't a pressing need to type curled versions because
		-humans excel at understanding from context.
		+By the seventeenth century, quotation marks became common in writing. During the nineteenth century, Western Europe adopted the convention of turning the convexity of quotation mark pairs outward.

		-Eventually straight quotes were codified for computers. Unfortunately, the
		-apostrophe carried with it the baggage from typewriters. That is, burgeoning
		-encoding standards failed to let users capture the nuances of the English
		-language; computers forced users to treat the apostrophe as a straight quote.
		-Standards bodies suggested using the right single quotation mark for an
		-apostrophe instead, shirking off its semantic meaning. Consequently,
		-text containing English quotations, especially British English, is now
		-riddled with ambiguity.
		+Early mechanical typewriters, dating from around 1825, lacked many punctuation marks. As technology improved, additional keys were added, though some keys had dual roles (for example, the letter I was used for the number 1). Straight single and double quotes were used to represent quotation marks, apostrophes, feet and inches marks, as well as primes and double-primes. There was no pressing need to type curled versions because readers relied on contextual understanding.
		+
		+Eventually, straight quotes were codified for computers. Unfortunately, this legacy from typewriters created challenges for encoding. Apostrophes inherited the straight quote form, and early encoding standards failed to capture the nuanced meanings in English typography. Computers forced users to treat the apostrophe as a straight quote.
		+
		+Standards bodies recommended using the right single quotation mark for an apostrophe instead, which disregarded its semantic meaning. As a result, text containing English quotations—especially in British English—is now riddled with 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.
		-It's amazing how ancient decisions still affect modern systems.
		+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 ancient typographical decisions continue to impact modern systems.

docs/13-i18n.md

		# Internationalization

		-The application supports internationalization (I18N). There are multiple
		-components to editing and previewing internationalized text documents.
		-These include:
		+This chapter covers how to configure internationalization (I18N) in the application, focusing on font and language settings required to properly display and edit multilingual text documents, especially those using non-Latin scripts.

		-* Fonts
		-* Language
		+Internationalization (I18N) support is essential for editing and previewing text in multiple languages. The application has components dedicated to this, primarily involving font and language configurations.

		-Both fonts and language must be set for non-Latin-based text.
		+Both fonts and language must be set appropriately when working with non-Latin-based text.

		-# Fonts
		+## Fonts

		-The text editors and preview panel have independent font settings. For
		-all Chinese, Japanese, and Korean (CJK) fonts, you may have to type in
		-the font family name directly.
		+The text editors and preview panel have independent font settings to allow for optimal display of various languages, especially Chinese, Japanese, and Korean (CJK) fonts. Often, these font families need to be typed in directly.

		-For example, CJK font families for the editor have the following names:
		+For example, CJK font families for the editor include:

		-* Noto Sans CJK KR --- Korean font
		-* Noto Sans CJK JP --- Japanese font
		-* Noto Sans CJK HN --- Chinese font
		-* Noto Sans CJK SC --- Simplified Chinese font
		+- Noto Sans CJK KR --- Korean font
		+- Noto Sans CJK JP --- Japanese font
		+- Noto Sans CJK HN --- Chinese font
		+- Noto Sans CJK SC --- Simplified Chinese font

		-While CJK font families for the preview have the following names:
		+While CJK font families for the preview panel include:

		-* Noto Serif CJK KR --- Korean font
		-* Noto Serif CJK JP --- Japanese font
		-* Noto Serif CJK HN --- Chinese font
		-* Noto Serif CJK SC --- Simplified Chinese font
		+- Noto Serif CJK KR --- Korean font
		+- Noto Serif CJK JP --- Japanese font
		+- Noto Serif CJK HN --- Chinese font
		+- Noto Serif CJK SC --- Simplified Chinese font

		## Editor

		-Complete the following steps to change the editor font:
		+Follow these steps to change the editor font:

		1. Click Edit → Preferences.

		Note the following:

		-* The font must be installed in the system for this to work.
		-* You may have to edit the font name if it cannot be selected from the list.
		-* Setting the editor font also sets the statistics panel font.
		+- The font must be installed in the system for this to work.
		+- You may have to edit the font name if it cannot be selected from the list.
		+- Setting the editor font also sets the statistics panel font.

		## Preview

		-The preview panel uses regular and monospace fonts.
		+The preview panel uses two categories of fonts: regular and monospace.

		-### Regular
		+### Regular font

		-Complete the following steps to change the regular preview font:
		+To change the regular preview font, complete the following steps:

		1. Click Edit → Preferences.

		The regular preview font is changed.

		-### Monospace
		+### Monospace font

		-Complete the following steps to change the monospace preview font:
		+To change the monospace preview font, complete the following steps:

		1. Click Edit → Preferences.

		The monospace font is changed.

		-# Language
		+## Language

		-Language settings control the locale that the application uses. When using
		-a CJK font, for example, the application must also be instructed to use
		-a particular locale. Change the locale as follows:
		+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.

docs/14-references.md

		-# Captions and cross-references
		-
		-Users may define captions and cross-references to tables, figures,
		-and equations. Unfortunately, at time of writing, the CommonMark
		-specification is frozen. This means cross-references must be implemented
		-as an extension to the Markdown specification, leaving the door open for
		-differing Markdown rendering libraries and applications to diverge with
		-respect to syntax.
		-
		-# Syntax
		+# Captions and Cross-References

		-This section describes how to use captions and cross-references within
		-Markdown documents. The CommonMark standard details different ways to
		-add captions to tables and figures. While those are supported, a more
		-consistent syntax has been implemented.
		+This chapter provides a comprehensive overview of how to define and use captions and cross-references in Markdown documents. It explains the syntax for captioning tables, figures, and equations, and details how to create unique anchors and references for cross-linking within the document.

		## Captions

		-Tables, figures, and equations are captioned using the same syntax. In
		-general, a line that starts with a double colon after a blank line will
		-result in a caption added to the item immediately preceding it. The
		-remainder of this section provides examples.
		+Captions are essential for providing context and descriptions to tables, figures, and equations. This section explains the consistent syntax used for adding captions in Markdown.
		+
		+Generally, captions are added by placing a line starting with a double colon (`::`) immediately after the item to be captioned, following a blank line.

		### Images

		-An image caption:
		+To add a caption to an image, include the image markup followed by a caption line starting with double colons:

		-```
		+```markdown
		![image title](https://loremflickr.com/600/350)

		-:: Figure caption text
		+:: Figure Caption Text
		```

		### Table

		-A table caption:
		+Tables can also be captioned in a similar manner, placing the caption immediately after the table:

		-```
		+```markdown
		\| a \| b \| c \|
		\|---\|---\|---\|
		\| 1 \| 2 \| 3 \|
		\| 4 \| 5 \| 6 \|
		\| 7 \| 8 \| 9 \|

		-:: Table caption text
		+:: Table Caption Text
		```

		### Equation

		-An equation caption:
		+Equations receive captions the same way, following the displayed equation:

		-```
		+```markdown
		$$E = mc^2$$

		-:: Equation caption
		+:: Equation Caption
		```

		-# Cross-references
		+## Cross-references

		-There are two parts to a cross-reference: the anchor name and its references.
		-An anchor name must be uniquely defined. Any number of references may refer
		-to an anchor name. Anchor names can be associated with any item in the
		-document, and are primarily added to captions.
		+Cross-references allow you to refer to tables, figures, equations, or other items anywhere in the document using unique anchor names and reference tags.

		-The general syntax for anchor names and references is:
		+An anchor name uniquely identifies an item, and multiple references may point to it. Anchors are primarily added to captions to enable referencing.

		-* `{#type-name:label}` (anchor name)
		-* `[@type-name:label]` (reference)
		+The general syntax is:

		-The `type-name` can be any alphanumeric value, starting with a letter or
		-ideogram. Type names are user-defined categories for the item type. Labels
		-are user-defined identifiers that must be unique per item.
		+- `{#type-name:label}` for defining an anchor name
		+- `[@type-name:label]` for referencing the anchor elsewhere

		-Consider the following example:
		+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://loremflickr.com/600/350)

		-:: World's cutest animal {#fig:animal}
		+:: World's Cutest Animal {#fig:animal}

		There is no cuter animal than the one in [@fig:animal].
		```

		-The anchor name uniquely defines where an item in a document is located. Any
		-number of references, anywhere in the document, may reference an anchor name.
		-There are few restrictions placed on the possible type names and labels. Here
		-are a few more anchor name examples:
		+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 avoid duplicating writing the label each time (e.g., Figure, Table,
		-Equation), there are a number of predefined labels associated with
		-type names. The following table lists the type names and the label
		-generated by the typesetting system:
		+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 \|

		\| source \| Listing \|
		\| src \| Listing \|
		-\| tab \| Table \|
		-\| table \| Table \|
		\| tbl \| Table \|
		+\| table \| Table \|
		+\| tab \| Table \|

		-These values are defined in the theme's `xhtml/xml-references.tex` file.
		+:: 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, enhancing the reader's experience.
		+

docs/15-credits.md

		-# Credits
		-
		-Using libraries from:
		-
		-* 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)
		-
		-Inspired by:
		-
		-* Karl Tauber: [Markdown Writer FX](https://github.com/JFormDesigner/markdown-writer-fx)

docs/diagram.yaml

		----
		-keenwrite:
		- classes:
		- processors:
		- markdown: MarkdownProcessor
		- variable:
		- definition: DefinitionProcessor
		- preview: PreviewProcessor
		- palette:
		- primary:
		- light: '#51a9cf'
		- dark: '#126d95'
		- secondary:
		- light: '#ec706a'
		- dark: '#7e252f'
		- accent:
		- light: '#76A786'
		- dark: '#385742'
		- grayscale:
		- light: '#bac2c5'
		- dark: '#394343'
		- graph:
		- label:
		- chain:
		- next: successor

docs/metadata.yaml

		title: KeenWrite
		subtitle: User Manual
		+keenwrite:
		+ classes:
		+ processors:
		+ markdown: MarkdownProcessor
		+ variable:
		+ definition: DefinitionProcessor
		+ preview: PreviewProcessor
		+ palette:
		+ primary:
		+ light: '#51a9cf'
		+ dark: '#126d95'
		+ secondary:
		+ light: '#ec706a'
		+ dark: '#7e252f'
		+ accent:
		+ light: '#76A786'
		+ dark: '#385742'
		+ grayscale:
		+ light: '#bac2c5'
		+ dark: '#394343'
		+ graph:
		+ label:
		+ chain:
		+ next: successor