| Author | DaveJarvis <email> |
|---|---|
| Date | 2025-08-30 16:02:55 GMT-0700 |
| Commit | 38f9569f48001b4b596b73e3fb3fb4385e0fc459 |
| Parent | 702ac98 |
| Delta | 189 lines added, 687 lines removed, 498-line decrease |
| # Typesetting | ||
| -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. | ||
| +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. | ||
| -## Tooling | ||
| +Broadly, typesetting PDF files entails the following: | ||
| -This section describes the key tools and technologies the application leverages to produce high-quality PDF files. | ||
| +* 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 series of semi-automated steps guides users through the installation process. These steps differ depending on the operating system. | ||
| +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**. | ||
| + * Note the following details (e.g., Windows X86 64-bit): | ||
| + * operating system name; | ||
| + * instruction set; and | ||
| + * architecture. | ||
| +1. Click the [link](https://wiki.contextgarden.net/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. Right-click [localpath.bat](https://repo.autonoma.ca/keenwrite.git/raw/HEAD/scripts/localpath.bat). | ||
| +1. Select **Save Link As** (or similar). | ||
| +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_HOME="${HOME}/${LOCAL_DIR}" | ||
| + mkdir -p "${CONTEXT_HOME}" | ||
| + cd "${CONTEXT_HOME}" | ||
| + 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_HOME=\"\${HOME}/${LOCAL_DIR}" \ | ||
| + >> ${HOME}/.bashrc | ||
| + echo PATH="\"\${PATH}:\${CONTEXT_HOME}/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). | ||
| -# 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 the typesetting software as follows: | ||
| - | ||
| -1. Start the text editor. | ||
| -1. Click **File → Export As → PDF**. | ||
| - * Note the following details (e.g., Windows X86 64-bit): | ||
| - * operating system name; | ||
| - * instruction set; and | ||
| - * architecture. | ||
| -1. Click the [link](https://wiki.contextgarden.net/Installation) in the dialog. | ||
| -1. Download the appropriate archive file. | ||
| - | ||
| -## 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 | ||
| - | ||
| -Proceed with a Windows installation of 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. Right-click [localpath.bat](https://gitlab.com/DaveJarvis/KeenWrite/-/raw/main/scripts/localpath.bat). | ||
| -1. Select **Save Link As** (or similar). | ||
| -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). | ||
| - | ||
| -Installation is complete. Verify the installation as follows: | ||
| - | ||
| -1. Type: `context --version` | ||
| -1. Press `Enter`. | ||
| - | ||
| -If version information is displayed then the software is installed correctly. | ||
| - | ||
| -Continue by installing a [theme pack](#theme-pack). | ||
| - | ||
| -### Unix | ||
| - | ||
| -For Linux, MacOS, FreeBSD, and similar operating systems, proceed as follows: | ||
| - | ||
| -1. Create `$HOME/.local/bin/context` | ||
| -1. Extract the `.zip` file within `$HOME/.local/bin/context` | ||
| -1. Run `sh install.sh` | ||
| -1. Add `export PATH=$PATH:$HOME/.local/bin/context/tex/texmf-linux-64/bin` to the login script. | ||
| - | ||
| -Installation is complete. Verify the installation as follows: | ||
| - | ||
| -1. Open a new terminal (to export the new PATH setting). | ||
| -1. Type: `context --version` | ||
| -1. Press `Enter`. | ||
| - | ||
| -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`). | ||
| -1. Type in some text. | ||
| -1. Click **File → Export As → PDF** (or type `Ctrl+p`). | ||
| -1. Select a theme from the drop-down list. | ||
| -1. Click **OK** (or press `Enter`). | ||
| -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`). | ||
| - | ||
| -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 a sibling of the following files in the same | ||
| -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 | ||
| -``` | ||
| - | ||
| -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). | ||
| - | ||
| -# Skins | ||
| - | ||
| -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. | ||
| - | ||
| -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 | ||
| - | ||
| -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 | ||
| - | ||
| -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; | ||
| -} | ||
| -``` | ||
| - | ||
| -Next, 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 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. 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://gitlab.com/DaveJarvis/KeenWrite/-/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 | ||
| - | ||
| -Learn about JavaFX CSS differences and advanced styling capabilities in this section, with links to the official exhaustive reference. | ||
| - | ||
| -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. | ||
| - | ||
| -## RichTextFX | ||
| - | ||
| -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. | ||
| - | ||
| - | ||
| -# Fenced divs | ||
| - | ||
| -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 | ||
| - | ||
| -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 | ||
| -::: 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 HTML 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 HTML `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 HTML `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> | ||
| -``` | ||
| - | ||
| -# 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 XHTML encoding. | | ||
| -| 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 Ancient Greek, where they were later adopted as the diplé (⸖) around 625 BCE. This early form foreshadowed the curved shape of modern quotation marks. | ||
| - | ||
| -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. | ||
| - | ||
| -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. This example highlights how ancient typographical decisions continue to impact modern systems. | ||
| - | ||
| -# Internationalization | ||
| - | ||
| -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. | ||
| - | ||
| -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 appropriately when working with non-Latin-based text. | ||
| - | ||
| -## Fonts | ||
| - | ||
| -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 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 | ||
| - | ||
| -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 | ||
| - | ||
| -## Editor | ||
| - | ||
| -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: | ||
| - | ||
| -- 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 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. | ||
| - | ||
| -# Captions and Cross-References | ||
| - | ||
| -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 | ||
| - | ||
| -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 | ||
| - | ||
| -To add a caption to an image, include the image markup followed by a caption line starting with double colons: | ||
| - | ||
| -```markdown | ||
| - | ||
| - | ||
| -:: Figure caption text | ||
| -``` | ||
| - | ||
| -### Table | ||
| - | ||
| -Tables can 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 | ||
| -``` | ||
| - | ||
| -### Equation | ||
| - | ||
| -Equations receive captions the same way, following the displayed equation: | ||
| - | ||
| -```markdown | ||
| -$$E = mc^2$$ | ||
| - | ||
| -:: Equation caption text | ||
| -``` | ||
| - | ||
| -## Cross-references | ||
| - | ||
| -Cross-references allow you to refer to tables, figures, equations, or other items 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. | ||
| - | ||
| - | ||
| - | ||
| -:: 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, enhancing the reader's experience. | ||
| - | ||
| -# 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 {#fig:screenshot-diagram-graphviz} | ||
| - | ||
| - | ||
| - | ||
| -:: Family tree diagram {#fig:screenshot-diagram-genealogy} | ||
| - | ||
| -## PDF themes | ||
| - | ||
| -The background of [@fig:screenshot-pdf-themes] depicts a novel being edited: | ||
| - | ||
| - | ||
| - | ||
| -:: 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: | ||
| - | ||
| - | ||
| - | ||
| -:: Locale settings {#fig:screenshot-locale} | ||
| - | ||
| -## Equations | ||
| - | ||
| -[@fig:screenshot-tex] shows TeX equations in a detached preview pane: | ||
| - | ||
| - | ||
| - | ||
| -:: TeX equations {#fig:screenshot-tex} | ||
| - | ||
| -## Dockable tabs | ||
| - | ||
| -[@fig:screenshot-outline] shows a document outline opened and docked in | ||
| -bottom-left corner: | ||
| - | ||
| - | ||
| - | ||
| -:: Document outline {#fig:screenshot-outline} | ||
| - | ||
| -# 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) | ||
| - | ||