Dave Jarvis' Repositories

*.pdf binary

KeenWrite, a free, cross-platform desktop text editor.

Copyright (C) 2025  White Magic Software, Ltd.

This program is free software; you can redistribute it and/or

modify it under the terms of the GNU General Public License

as published by the Free Software Foundation; either version 2

of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

GNU General Public License for more details.

You should have received a copy of the GNU General Public License

along with this program; if not, see <https://www.gnu.org/licenses/>.

# GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

    Copyright (C) 1989, 1991 Free Software Foundation, Inc.  

    <https://fsf.org/>

    Everyone is permitted to copy and distribute verbatim copies

    of this license document, but changing it is not allowed.

## Preamble

The licenses for most software are designed to take away your freedom

to share and change it. By contrast, the GNU General Public License is

intended to guarantee your freedom to share and change free

software--to make sure the software is free for all its users. This

General Public License applies to most of the Free Software

Foundation's software and to any other program whose authors commit to

using it. (Some other Free Software Foundation software is covered by

the GNU Lesser General Public License instead.) You can apply it to

your programs, too.

When we speak of free software, we are referring to freedom, not

price. Our General Public Licenses are designed to make sure that you

have the freedom to distribute copies of free software (and charge for

this service if you wish), that you receive source code or can get it

if you want it, that you can change the software or use pieces of it

in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid

anyone to deny you these rights or to ask you to surrender the rights.

These restrictions translate to certain responsibilities for you if

you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether

gratis or for a fee, you must give the recipients all the rights that

you have. You must make sure that they, too, receive or can get the

source code. And you must show them these terms so they know their

rights.

We protect your rights with two steps: (1) copyright the software, and

(2) offer you this license which gives you legal permission to copy,

distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain

that everyone understands that there is no warranty for this free

software. If the software is modified by someone else and passed on,

we want its recipients to know that what they have is not the

original, so that any problems introduced by others will not reflect

on the original authors' reputations.

Finally, any free program is threatened constantly by software

patents. We wish to avoid the danger that redistributors of a free

program will individually obtain patent licenses, in effect making the

program proprietary. To prevent this, we have made it clear that any

patent must be licensed for everyone's free use or not licensed at

all.

The precise terms and conditions for copying, distribution and

modification follow.

## TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

**0.** This License applies to any program or other work which

contains a notice placed by the copyright holder saying it may be

distributed under the terms of this General Public License. The

"Program", below, refers to any such program or work, and a "work

based on the Program" means either the Program or any derivative work

under copyright law: that is to say, a work containing the Program or

a portion of it, either verbatim or with modifications and/or

translated into another language. (Hereinafter, translation is

included without limitation in the term "modification".) Each licensee

is addressed as "you".

Activities other than copying, distribution and modification are not

covered by this License; they are outside its scope. The act of

running the Program is not restricted, and the output from the Program

is covered only if its contents constitute a work based on the Program

(independent of having been made by running the Program). Whether that

is true depends on what the Program does.

**1.** You may copy and distribute verbatim copies of the Program's

source code as you receive it, in any medium, provided that you

conspicuously and appropriately publish on each copy an appropriate

copyright notice and disclaimer of warranty; keep intact all the

notices that refer to this License and to the absence of any warranty;

and give any other recipients of the Program a copy of this License

along with the Program.

You may charge a fee for the physical act of transferring a copy, and

you may at your option offer warranty protection in exchange for a

fee.

**2.** You may modify your copy or copies of the Program or any

portion of it, thus forming a work based on the Program, and copy and

distribute such modifications or work under the terms of Section 1

above, provided that you also meet all of these conditions:

**a)** You must cause the modified files to carry prominent notices

stating that you changed the files and the date of any change.

**b)** You must cause any work that you distribute or publish, that in

whole or in part contains or is derived from the Program or any part

thereof, to be licensed as a whole at no charge to all third parties

under the terms of this License.

**c)** If the modified program normally reads commands interactively

when run, you must cause it, when started running for such interactive

use in the most ordinary way, to print or display an announcement

including an appropriate copyright notice and a notice that there is

no warranty (or else, saying that you provide a warranty) and that

users may redistribute the program under these conditions, and telling

the user how to view a copy of this License. (Exception: if the

Program itself is interactive but does not normally print such an

announcement, your work based on the Program is not required to print

an announcement.)

These requirements apply to the modified work as a whole. If

identifiable sections of that work are not derived from the Program,

and can be reasonably considered independent and separate works in

themselves, then this License, and its terms, do not apply to those

sections when you distribute them as separate works. But when you

distribute the same sections as part of a whole which is a work based

on the Program, the distribution of the whole must be on the terms of

this License, whose permissions for other licensees extend to the

entire whole, and thus to each and every part regardless of who wrote

it.

Thus, it is not the intent of this section to claim rights or contest

your rights to work written entirely by you; rather, the intent is to

exercise the right to control the distribution of derivative or

collective works based on the Program.

In addition, mere aggregation of another work not based on the Program

with the Program (or with a work based on the Program) on a volume of

a storage or distribution medium does not bring the other work under

the scope of this License.

**3.** You may copy and distribute the Program (or a work based on it,

under Section 2) in object code or executable form under the terms of

Sections 1 and 2 above provided that you also do one of the following:

**a)** Accompany it with the complete corresponding machine-readable

source code, which must be distributed under the terms of Sections 1

and 2 above on a medium customarily used for software interchange; or,

**b)** Accompany it with a written offer, valid for at least three

years, to give any third party, for a charge no more than your cost of

physically performing source distribution, a complete machine-readable

copy of the corresponding source code, to be distributed under the

terms of Sections 1 and 2 above on a medium customarily used for

software interchange; or,

**c)** Accompany it with the information you received as to the offer

to distribute corresponding source code. (This alternative is allowed

only for noncommercial distribution and only if you received the

program in object code or executable form with such an offer, in

accord with Subsection b above.)

The source code for a work means the preferred form of the work for

making modifications to it. For an executable work, complete source

code means all the source code for all modules it contains, plus any

associated interface definition files, plus the scripts used to

control compilation and installation of the executable. However, as a

special exception, the source code distributed need not include

anything that is normally distributed (in either source or binary

form) with the major components (compiler, kernel, and so on) of the

operating system on which the executable runs, unless that component

itself accompanies the executable.

If distribution of executable or object code is made by offering

access to copy from a designated place, then offering equivalent

access to copy the source code from the same place counts as

distribution of the source code, even though third parties are not

compelled to copy the source along with the object code.

**4.** You may not copy, modify, sublicense, or distribute the Program

except as expressly provided under this License. Any attempt otherwise

to copy, modify, sublicense or distribute the Program is void, and

will automatically terminate your rights under this License. However,

parties who have received copies, or rights, from you under this

License will not have their licenses terminated so long as such

parties remain in full compliance.

**5.** You are not required to accept this License, since you have not

signed it. However, nothing else grants you permission to modify or

distribute the Program or its derivative works. These actions are

prohibited by law if you do not accept this License. Therefore, by

modifying or distributing the Program (or any work based on the

Program), you indicate your acceptance of this License to do so, and

all its terms and conditions for copying, distributing or modifying

the Program or works based on it.

**6.** Each time you redistribute the Program (or any work based on

the Program), the recipient automatically receives a license from the

original licensor to copy, distribute or modify the Program subject to

these terms and conditions. You may not impose any further

restrictions on the recipients' exercise of the rights granted herein.

You are not responsible for enforcing compliance by third parties to

this License.

**7.** If, as a consequence of a court judgment or allegation of

patent infringement or for any other reason (not limited to patent

issues), conditions are imposed on you (whether by court order,

agreement or otherwise) that contradict the conditions of this

License, they do not excuse you from the conditions of this License.

If you cannot distribute so as to satisfy simultaneously your

obligations under this License and any other pertinent obligations,

then as a consequence you may not distribute the Program at all. For

example, if a patent license would not permit royalty-free

redistribution of the Program by all those who receive copies directly

or indirectly through you, then the only way you could satisfy both it

and this License would be to refrain entirely from distribution of the

Program.

If any portion of this section is held invalid or unenforceable under

any particular circumstance, the balance of the section is intended to

apply and the section as a whole is intended to apply in other

circumstances.

It is not the purpose of this section to induce you to infringe any

patents or other property right claims or to contest validity of any

such claims; this section has the sole purpose of protecting the

integrity of the free software distribution system, which is

implemented by public license practices. Many people have made

generous contributions to the wide range of software distributed

through that system in reliance on consistent application of that

system; it is up to the author/donor to decide if he or she is willing

to distribute software through any other system and a licensee cannot

impose that choice.

This section is intended to make thoroughly clear what is believed to

be a consequence of the rest of this License.

**8.** If the distribution and/or use of the Program is restricted in

certain countries either by patents or by copyrighted interfaces, the

original copyright holder who places the Program under this License

may add an explicit geographical distribution limitation excluding

those countries, so that distribution is permitted only in or among

countries not thus excluded. In such case, this License incorporates

the limitation as if written in the body of this License.

**9.** The Free Software Foundation may publish revised and/or new

versions of the General Public License from time to time. Such new

versions will be similar in spirit to the present version, but may

differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program

specifies a version number of this License which applies to it and

"any later version", you have the option of following the terms and

conditions either of that version or of any later version published by

the Free Software Foundation. If the Program does not specify a

version number of this License, you may choose any version ever

published by the Free Software Foundation.

**10.** If you wish to incorporate parts of the Program into other

free programs whose distribution conditions are different, write to

the author to ask for permission. For software which is copyrighted by

the Free Software Foundation, write to the Free Software Foundation;

we sometimes make exceptions for this. Our decision will be guided by

the two goals of preserving the free status of all derivatives of our

free software and of promoting the sharing and reuse of software

generally.

**NO WARRANTY**

**11.** BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO

WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.

EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR

OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY

KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE

IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR

PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE

PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME

THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

**12.** IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN

WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY

AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU

FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR

CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE

PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING

RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A

FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF

SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH

DAMAGES.

END OF TERMS AND CONDITIONS

1. Download the *Full version* of the Java Runtime Environment, [JRE 24](https://bell-sw.com/pages/downloads).

    classpath "com.github.spotbugs.snom:spotbugs-gradle-plugin:6.3.0"

  id 'com.github.spotbugs' version '6.3.0'

  '--enable-native-access=javafx.graphics',

  '--sun-misc-unsafe-memory-access=allow',

  '--add-opens=javafx.graphics/com.sun.javafx.scene=ALL-UNNAMED',

  implementation 'org.fxmisc.richtext:richtextfx:0.11.6'

  implementation "com.vladsch.flexmark:flexmark-ext-footnotes:${v_flexmark}"

  implementation 'org.yaml:snakeyaml:2.5'

  implementation 'org.jsoup:jsoup:1.21.2'

  implementation 'org.xhtmlrenderer:flying-saucer-core:10.0.0'

  implementation 'jakarta.validation:jakarta.validation-api:3.1.1'

  implementation 'org.slf4j:slf4j-nop:2.0.17'

  // Required to satisfy SpotBugs missing class warnings.

  implementation 'org.jspecify:jspecify:1.0.0'

  implementation 'com.google.errorprone:error_prone_annotations:2.41.0'

# Define font list to avoid duplication

ENV FONTS_LIST="andada-pro archivo-narrow arimo carlito courier-prime \

  inconsolata inter libre-baskerville libre-franklin niconne nunito \

  open-sans-emoji pt-mono pt-sans pt-serif roboto roboto-mono source-serif-4 \

  snickles tw-kai underwood"

# Download fonts

RUN mkdir -p "$FONTS_DIR" && \

  for font in $FONTS_LIST; do \

    wget "https://fonts.keenwrite.com/download/${font}.zip"; \

  done

ADD "http://lmtx.pragma-ade.nl/install-lmtx/context-${CONTEXT_ARCH}.zip" "context.zip"

  for font in $FONTS_LIST; do \

    unzip -j -o -d $FONTS_DIR "$DOWNLOAD_DIR/${font}.zip" '*.ttf' '*.otf'; \

  done && \

  ln -s $CONTEXT_HOME/tex/texmf-fonts/tex/context/user $HOME/.fonts && \

  source $PROFILE && \

1. Ensure the host path file exists; it must include remote server name:

    test -f host-path.txt && echo "exists"

    sha256sum *setup.exe | cut -f1 -d' '

1. Set `Wizard.typesetter.container.version` to the new executable version.

  [[ -n "${mount_source}" ]] && \

    read -ra source_parts <<< "${mount_source}" && \

    mount_args+=("${source_parts[@]}")

  [[ -n "${mount_target}" ]] && \

    read -ra target_parts <<< "${mount_target}" && \

    mount_args+=("${target_parts[@]}")

  [[ -n "${mount_images}" ]] && \

    read -ra images_parts <<< "${mount_images}" && \

    mount_args+=("${images_parts[@]}")

  [[ -n "${mount_fonts}" ]] && \

    read -ra fonts_parts <<< "${mount_fonts}" && \

    mount_args+=("${fonts_parts[@]}")

  # Create host directories for mount points

  [[ -n "${ARG_MOUNTPOINT_SOURCE}" && ! -d "${ARG_MOUNTPOINT_SOURCE}" ]] && \

    mkdir -p "${ARG_MOUNTPOINT_SOURCE}"

  [[ -n "${ARG_MOUNTPOINT_TARGET}" && ! -d "${ARG_MOUNTPOINT_TARGET}" ]] && \

    mkdir -p "${ARG_MOUNTPOINT_TARGET}"

  [[ -n "${ARG_MOUNTPOINT_IMAGES}" && ! -d "${ARG_MOUNTPOINT_IMAGES}" ]] && \

    mkdir -p "${ARG_MOUNTPOINT_IMAGES}"

  [[ -n "${ARG_MOUNTPOINT_FONTS}"  && ! -d "${ARG_MOUNTPOINT_FONTS}" ]]  && \

    mkdir -p "${ARG_MOUNTPOINT_FONTS}"

# Introduction

{{app.title}} is a free desktop editor that transforms Markdown documents into

beautifully typeset PDF files. Whether you're crafting technical documentation,

reports, academic papers, or creative content, {{app.title}} combines the

simplicity and readability of Markdown with high-quality publishing

capabilities.

## Rethink

The core philosophy behind {{app.title}} may require shifting how you think

about writing documents. Unlike traditional word processors that mix content

and styling, {{app.title}} aims to completely separate what is written from how

it appears. You write in plain text and instruct the computer to typset the

document into print-ready PDF files. This approach allows for:

* **Rebranding** -- Corporations can redesign documents in weeks, not years

* **Consistency** -- Ensure uniform, high-quality output across documents

* **Future-proof** -- Plain-text files will be readable long after proprietary formats go obsolete

* **Version control** -- Plain text works seamlessly with version control systems

* **Reproducibility** -- Generate the same output using different systems

* **Focus** -- Write without distraction from formatting concerns

## Reflow

Learning how {{app.title}} converts plain text into PDF can help understand its

usage.

The original intent of Markdown was to simplify writing web pages. As such,

there are numerous tools to convert Markdown to HTML. {{app.title}} goes one

step further and converts Markdown to XHTML, which is a *well-formed* version

of HTML and also a type of XML. The typesetting system can transform XML

documents, and therefore XHTML documents, into typesetting instructions. Those

instructions add styling (colours, fonts, layout, etc.) to the final output

document.

In a nutshell: **Markdown → XHTML → TeX → PDF**

This chain allows separating content (the Markdown source) from presentation

(a TeX typesetting system), allowing the two to vary independently.

Incidentally, it also allows publishing the same content to the web, styled

using cascading stylesheets.

## Features

{{app.title}} has numerous tools to assist with document creation.

### Writing and editing

Built-in features to help write and edit documents include:

* **User-defined variables** for consistency, with autocomplete

* **Spell checking** to catch typos as you type

* **Document outline** for easy navigation in long documents

* **File manager** to view related files within the editor

* **Word count** and document statistics

### Export formats

{{app.title}} provides multiple export formats from Markdown:

* **PDF files** typeset using the ConTeXt typesetting system

* **XHTML files** for publishing to the web

* **Markdown** with variables interpolated and substituted

### Advanced capabilities

Beyond basic document creation, {{app.title}} includes:

* **Data visualization** through R integration

* **Diagram generation** supporting PlantUML, Mermaid, and other text formats

* **Variable interpolation** enables a single source of truth for content

* **Internationalization** with font handling for multiple languages

* **Mathematical** equations and formulas rendered beautifully

### User interface

The user interface has:

* **Dark mode** and other skin customizations

* **Multi-document editing** with detachable tabs

* **Live preview** showing formatted output as you write

* **Distraction-free** settings when you need to focus

## Target users

{{app.title}} is designed for anyone who needs to produce high-quality

documents while maintaining control over content and presentation:

* **Technical writers** creating documentation, user manuals, and specifications

* **Researchers and academics** writing papers with mathematical content

* **Authors** producing books and long-form content

## Quick start

The easiest way to begin using {{app.title}}:

1. **Download** the application from [keenwrite.com](https://keenwrite.com).

1. **Run** the application (no installation necessary).

1. **Create** your first document by clicking **File → New**.

1. **Start writing** in Markdown format.

1. **Preview** your work in the preview tab.

1. **Export** to PDF when ready.

To generate PDF files, you'll also need:

* The theme pack to apply a look and feel

* ConTeXt typesetting system (can be installed automatically)

If you have opted to download the Java version of {{app.title}}, see

[@sec:java-runtime-environment] for installation instructions.

## Document structure

This manual is organized to support both newcomers and experienced users

seeking specific information. You can read the manual sequentially to build

expertise gradually, or jump to specific chapters as needed.

## Getting help

When you need assistance or encounter challenges, multiple resources are

available to help. If you encounter issues or need assistance:

* Check the **Troubleshooting** chapter for common problems and solutions

* Visit the **Screenshots** chapter to see the interface in action

* Consult the **Command-line reference** for automation tasks

* Review the **Architecture** chapter if you're interested in extending {{app.title}}

The remaining chapters will guide you through installation, basic usage, and

gradually introduce advanced features.

# Installation

This chapter covers installing the application and its dependencies, including

the typesetting software required for PDF generation. Generating PDF files

requires the following components:

* {{app.title}} binary

* {{app.title}} theme pack

* ConTeXt typesetting system

The easiest way to get started is to download a {{app.title}} binary for your

operating system, run it, then launch the guided wizard as per [@sec:wizard].

The wizard will download and install all necessary components.

{{app.title}} binaries are self-installing, except for the Java archive

(`.jar`) version. Installing the Java archive version is useful for platforms

that don't have prebult {{app.title}} binaries. The Java archive version is

described in [@sec:java-runtime-environment].

## Wizard

Launch the wizard as follows:

1. [Download](https://keenwrite.com) {{app.title}}.

1. Start {{app.title}}.

1. Click **File → Export As → PDF**.

The installation wizard installs a container manager and typesetter container

image. The container image is a self-contained operating system that includes

the typesetting software, theme pack, and fonts. Using a container reduces the

number of manual installation steps.

## Java Runtime Environment

Using the Java archive version of {{app.title}} requires the following:

* `{{install.java}}` file.

* Java Runtime Environment (JRE) **{{version.java}}** with JavaFX.

* {{app.title}} launch script.

Software developers may choose to use the Java Development Kit (JDK)

**{{version.java}}**.

### Download {{app.title}}

[Download](https://keenwrite.com/) the Java archive version of {{app.title}}.

On Windows:

1. Create `C:\Users\%USERNAME%\keenwrite`.

1. Save `{{install.java}}` into the new directory.

### JRE with JavaFX

Install a JRE **{{version.java}}** version that bundles JavaFX.

1. Visit the BellSoft's Liberica JDK [download page](https://bell-sw.com/pages/downloads/#jdk-24).

1. Select the JDK corresponding to **{{version.java}}**.

1. Scroll down to the desired operating system.

1. Optionally, change the target CPU architecture.

1. Set **Package** to: `Full JRE`.

1. Download the `.zip` or `.tar.gz` file.

After downloading the *full* JRE, install it and make sure Java can be found

when run. On Unix systems, my preferred installation method follows:

1. Edit `$HOME/.bashrc`.

1. Add `export JAVA_HOME="/opt/jre"`.

1. Add `export PATH="${PATH}:{{install.path.unix.bin}}:${JAVA_HOME}/bin"`.

1. Save the file.

1. Install into `/opt/jre-{{version.java}}-full` and link to `/opt/jre`:

    ``` bash

    sudo su -

    cd /opt

    JAVA_DIR="jre-{{version.java}}-full"

    mkdir "${JAVA_DIR}"

    tar xf bellsoft-jre{{version.java}}-linux-amd64-full.tar.gz \

      -C "${JAVA_DIR}" --strip-components=1

    ln -sf "${JAVA_DIR}" jre

    ```

Pointing the symbolic link `/opt/jre` to `/opt/jre-{{version.java}}-full`

enables upgrading the JRE without having to update the `.bashrc` for each

new version.

### Unix launch script

On Unix-based systems (Linux, macOS, FreeBSD, alpine, etc.), install the

launch script as follows:

1. Open a terminal.

1. Download the launcher script into `{{install.path.unix.bin}}`.

   ``` bash

   wget --quiet --content-on-error \

     "{{install.url.unix.launcher}}"

   ```

1. Make the script executable.

   ``` bash

   chmod +x "{{install.unix.java}}"

   ```

1. Download or move the `.jar` file into `{{install.path.unix.bin}}`.

Provided `{{install.path.unix.bin}}` is part of the `PATH` environment

variable, {{app.title}} can be run by typing `{{install.unix.java}}` and

pressing [⏎ Enter]{.kbd}.

### Windows launch script

On Windows-based systems, install the launch script as follows:

1. Browse to the [launcher script]({{install.url.windows.script}}).

1. Right-click anywhere on the page.

1. Click **Save Page As** (or similar).

1. Browse to `C:\Users\%USERNAME%\keenwrite`.

1. Confirm saving the file.

1. Rename the file from `.bat.txt` to `.bat`, if necessary.

The Java version of {{app.title}} is installed.

## ConTeXt LMTX

For users who prefer more control over the installation process, manually

download and configure the typesetting software as follows:

1. Start {{app.title}}.

1. Click **File → Export As → PDF**.

1. Note the following details (e.g., Windows x86 64-bit):

    * operating system name;

    * instruction set; and

    * architecture.

1. Click the [install page](https://wiki.contextgarden.net/Introduction/Installation) link in the dialog.

1. Download the archive file for your operating system and architecture.

Follow the steps that apply to the computer's operating system:

* [Unix](#unix) (includes macOS, FreeBSD, Linux, and similar)

* [Windows](#windows) (includes Windows 7, Windows 10, and similar)

### Unix

On Linux, macOS, FreeBSD, and similar systems, replace `context-linux-64.zip`

with the version appropriate to your operating system and CPU architecture.

Proceed:

1. Open a terminal.

1. Run the following commands:

   ``` bash

   sudo su -

   export CONTEXT_FILE="context-linux-64.zip"

   export CONTEXT_DIR="/opt/context"

   mkdir -p "${CONTEXT_DIR}"

   cd "${CONTEXT_DIR}"

   wget "https://lmtx.pragma-ade.nl/install-lmtx/${CONTEXT_FILE}"

   unzip "${CONTEXT_FILE}"

   rm "${CONTEXT_FILE}"

   chmod +x install.sh

   ./install.sh

   exit

   echo export CONTEXT_HOME=\"${CONTEXT_DIR}\" >> ${HOME}/.bashrc

   echo PATH="\"\${PATH}:\${CONTEXT_HOME}/tex/texmf-linux-64/bin\"" \

     >> ${HOME}/.bashrc

   source ${HOME}/.bashrc

   ```

ConTeXt is installed; jump to [@sec:verification].

### Windows

On a Windows operating system, 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** (or click **More info** first).

1. Download [localpath.bat]({{install.url.windows.path}}).

1. Save the file to the typesetting software's "root" directory.

1. Rename the file from `.bat.txt` to `.bat`, if necessary.

1. Run `localpath.bat` (to set and save the `PATH` environment variable).

ConTeXt is installed.

### Verification

After completing the installation process, verify that the typesetting software

has been installed correctly as follows:

1. Open a new terminal or command prompt.

1. Type: `context --version`

1. Press [⏎ Enter]{.kbd}.

If version information is displayed then the software is installed correctly.

## Theme packs

Theme packs define the visual appearance and styling of typeset documents.

Installing and configuring theme packs is essential for producing high-quality

PDF files. Each theme has its own requirements.

### Install theme pack

Install and configure the theme pack as follows:

1. Download the [theme-pack.zip](https://gitlab.com/DaveJarvis/keenwrite-themes/-/releases/permalink/latest/downloads/theme-pack.zip) archive.

1. Extract the archive.

   - On Unix, use `{{install.config.unix}}/`.

   - On Windows, use `{{install.config.win}}\`.

1. Start {{app.title}}, if not already running.

1. Click **Edit → Preferences**.

1. Click **Typesetting**.

1. Click **Browse** beside **Themes**.

1. Navigate to the `themes` directory.

   - On Unix, `{{install.config.unix}}/themes/`.

   - On Windows, `{{install.config.win}}\themes\`.

1. Click **Open**.

1. Click **OK**.

The theme pack is installed.

### Configure theme

Once a theme pack is installed, additional configuration may be required based

on the theme's formatting needs. Configure individual themes based on their

specific requirements. For example, the _Boschet_ theme requires downloading

and installing specific font families, which include:

* [Inconsolata]({{fonts.url}}/inconsolata.zip)

* [Libre Baskerville]({{fonts.url}}/libre-baskerville.zip)

* [Niconne]({{fonts.url}}/niconne.zip)

* [Open Sans Emoji]({{fonts.url}}open-sans-emoji.zip)

* [Source Serif 4]({{fonts.url}}/source-serif-4.zip)

* [TW Kai]({{fonts.url}}/tw-kai.zip)

* [Underwood Quiet Tab]({{fonts.url}}/underwood.zip)

See your operating system instructions for how to install a font.

When running ConTeXt within the typesetter container image, all fonts are

included.

## Run

Running {{app.title}} will depend on the operating system and installation

method. [@tbl:install-app-launchers] lists the executable file name used to

start the application.

| Operating System | Method       | Launcher file name |

|------------------|--------------|-----------------|

| Unix             | Binary       | `{{install.unix.native}}` |

| Unix             | Java archive | `{{install.unix.java}}`   |

| macOS            | Binary       | `{{install.mac.native}}`  |

| macOS            | Java archive | `{{install.mac.java}}`    |

| Windows          | Binary       | `{{install.win.native}}`  |

| Windows          | Java archive | `{{install.win.java}}`    |

:: {{app.title}} launchers {#tbl:install-app-launchers}

# Overview

This chapter describes how to basic editing functionality.

## First document

Create and open a document as follows:

1. Start {{app.title}}.

1. Click **File → Save As** to save the untitled file.

1. Set the file name to: `metadata.yaml`

1. Save the (empty) file.

1. Click **File → Open** to load the variable definition file.

1. Change **Source Files** to **Variable Files** to list variable definition files.

1. Browse to and select the `.yaml` file.

1. Click **Open**.

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

## Basic syntax

The editor supports standard Markdown features listed in [@tbl:markdown-syntax-basic]. While editing, try the toolbar icons to see how formatting appears in the preview tab.

| Style              | Syntax                        |

|--------------------|-------------------------------|

| **Bold**           | `**strong**`                  |

| *Italic*           | `*emphasis*` or `_emphasis_`  |

| ~~Struck text~~    | `~~struck~~`                  |

| Horizontal rule    | `---` on an empty line        |

| Unordered lists    | `- item` or `* item`          |

| Ordered lists      | `1. item`                     |

| Inline `code`      | `` `code` ``                  |

| Links              | `[label](url)`                |

| Images             | `![alt text](resource)`       |

| Blockquotes        | `> quoted text`               |

| Headings           | `#`, `##`, `###`              |

:: Basic Markdown syntax {#tbl:markdown-syntax-basic}

Remember that most of these items are suggestions to the presentation layer.

How they may appear in the final document may differ from what you anticipate.

## Preview

The preview tab updates in real time as you type. For example, if your variable file contains:

```yaml

novel:

  title: "Diary of {{novel.author}}"

  author: "Anne Frank"

```

Then typing:

```

The novel *{{novel.title}}* is a widely read book.

```

Will render as:

> The novel *Diary of Anne Frank* is a widely read book.

To autocomplete variable names:

1. Create a new file.

1. Type in a partial variable value, such as `Dia`.

1. Press [Ctrl+Space]{.kbd} (hold down the [Control]{.kbd} key and tap [Space]{.kbd}).

The editor inserts:

```

{{novel.title}}

```

And the preview tab shows:

> Diary of Anne Frank

## Export

To export your document as a PDF:

1. Click **File → Export As → PDF**.

1. Select a theme from the drop-down list.

1. Click **OK** or press [⏎ Enter]{.kbd}.

1. Choose a file name and location.

1. Click **Save**.

The document will be typeset using ConTeXt and saved as a PDF. You can view it in any PDF reader.

To combine multiple documents into one PDF:

1. Click **File → Export As → Joined PDF**.

1. Or press [Ctrl+Shift+p]{.kbd}.

# Variables

Variables are placeholders for values that can be defined once and reused

throughout the document. When the document is built, each variable is replaced

with its corresponding value.

## File format

YAML (meaning, *YAML Ain't Markup Language*) is a plain-text format used for

storing structured data. It's commonly used in configuration files due to its

readability and simplicity. YAML files allow encoding key-value pairs within

a nested hierarchy.

Any number of variables can be defined, in any order:

``` yaml

key_1: Value 1

key_2: Value 2

```

A variable's value can reference other variables by enclosing the referenced

key in double curly braces (`{{ }}`)---also known as "moustache"

notation---wrapped in quotation marks:

``` yaml

key: Value

key_1: "{{key}} 1"

key_2: "{{key}} 2"

```

Variables can be nested to group related information:

``` yaml

document:

  title: Document Title

  author: Author Name

  isbn: 978-3-16-148410-0

```

Reference nested keys using a period, such as:

``` yaml

novel:

  author: Author Name

copyright:

  owner: "{{novel.author}}"

```

## Usage

The preview tab updates as you type. Imagine a variable file contains:

``` yaml

novel:

  title: "Diary of {{novel.author}}"

  author: "Anne Frank"

```

Then typing:

```

The novel *{{novel.title}}* is a widely read book.

```

Displays in the preview pane as:

> The novel *Diary of Anne Frank* is a widely read book.

## Autocomplete

Typing variable names is laborious. To autocomplete variable names:

1. Type in a partial variable value, such as `Dia`.

1. Press [Ctrl+Space]{.kbd} (hold down the [Control]{.kbd} key and tap [Space]{.kbd}).

The editor inserts:

```

{{novel.title}}

```

And the preview tab shows:

> Diary of Anne Frank

# Metadata

Metadata is information about a document such as title, author keywords,

copyright date, ISBN, and more. Most systems require coupling metadata directly

to the source document. {{app.title}} fetches reads metadata from the variable

definitions file instead. This allows reusing the same metadata across

documents.

Metadata can be inserted into the output document either through the document

properties in the user interface or via the command line.

## Document properties

Metadata can be mapped in the user preferences, shown in [@fig:gui-metadata].

When the document is exported, the document metadata variables are added to the

`<head>` tag as `<meta>` tags.

![Metadata screenshot](images/screenshots/09.png)

:: Document metadata preferences {#fig:gui-metadata}

The **Key** column lists metadata names and the **Value** column lists the

metadata content for each corresponding **Key**. The content may include

references to variable definitions. When the document is typeset, the values

for the variables will be substituted upon export. When exporting to XHTML

format, the header will include the keys and values as `<meta>` tags. For

example:

``` html

<head>

  <title>Document Title</title>

  <meta content="science, nature" name="keywords"/>

  <meta content="Penn Surnom" name="author"/>

  <meta content="4311" name="count"/>

</head>

```

## Command-line

Recall the document metadata from earlier:

``` yaml

document:

  title: Document Title

  author: Author Name

```

These data can be provided via command-line arguments as follows:

``` bash

keenwrite.bin \

  -i "01-introduction.md" \

  -v "metadata.yaml" \

  --metadata="title={{document.title}}" \

  --metadata="author={{document.author}}"

```

The resulting XHTML document will resemble:

``` html

<head>

  <title>Document Title</title>

  <meta content="Author Name" name="author"/>

  <meta content="1234" name="count"/>

</head>

```

We'll take a deeper look at command-line usages in

[@cha:command-line-interface].

## Special fields

Certain metadata keys have special handling and formatting rules when documents

are exported to different formats. When exporting the document, note the

following special metadata:

* **count** -- Document word count, always included.

* **author** -- Included as PDF metadata.

* **keywords** -- Included as PDF metadata.

* **document.title** -- Populates the `<title>` tag, not a `<meta>` tag.

Except for **count**, all of these metadata variables can be customized.

Some themes, such as *Handrit*, have additional metadata that may be included

in the final document automatically. *Handrit*, in particular, has a way to

pass in a pseudonym (or by-line) for publishing manuscripts under a pseudonym.

# Basic Markdown

This section outlines the basic Markdown syntax supported by {{app.title}},

including paragraphs, headers, lists, links, and more. Countless Markdown

syntax resources exist, so only a brief refresher is provided.

## Paragraphs

Paragraphs are created by separating blocks of text with one or more blank

lines.

``` markdown

This is the first paragraph.

This is the second paragraph.

```

Without a blank line, the prose will be typeset as a single paragraph.

## Headers

Headers are created using one or more hash (`#`) symbols followed by a space

and the header text. The number of hash symbols indicates the level of the

header. While not strictly necessary, adding a blank line after a header can

make the document easier to read in its plain-text format.

``` markdown

# Header level 1

## Header level 2

### Header level 3

```

In technical documents, try to limit subheading levels to maintain clarity;

usually, three levels are sufficient.

## Lists

Ordered lists use numbers followed by a period and a space. Unordered lists

use asterisks (`*`), plus signs (`+`), or hyphens (`-`) followed by a space.

### Ordered list

My preference is to use `1.` for each ordered item and let the computer

renumber them because it makes adding and removing items faster, and

guarantees that there will never be a number skipped.

``` markdown

1. First item

1. Second item

1. Third item

```

### Unordered list

My preference is to use `*` for the first level of unordered items.

``` markdown

* Item one

* Item two

* Item three

```

## Links

Create links using square brackets for the link text followed by parentheses

for the URL.

``` markdown

[Download](https://keenwrite.com)

```

## Tables

Tables use pipes (`|`) to indicate separate columns and hyphens (`-`) to mark

the header row. Markdown does not define a syntax for table footers.

``` markdown

| Column A | Column B | Column C |

|----------|----------|----------|

| Value 1  | Value 2  | Value 3  |

| Value 4  | Value 5  | Value 6  |

```

Table cell justification can be suggested using a colon (`:`) on the left,

right, or both sides (centering) of the header separator line.

``` markdown

| Column A   | Column B  |  Column C |

|:-----------|:---------:|----------:|

| Value 1    |  Value 2  |   Value 3 |

| Value 4    |  Value 5  |   Value 6 |

```

The colon location is a hint to the presentation layer, which has the

freedom to ignore it.

# Extended Markdown

This chapter covers advanced formatting features that enhance document

structure and presentation. These features help create professional documents

with rich content organization, proper cross-referencing, and typographic

excellence.

## Fenced divs

Fenced divs are transformed into XHTML `div` elements. They allow semantic

organization and styling beyond standard Markdown.

### Basic syntax

A fenced div starts with at least three colons (`:::`), followed by one or more

spaces, and then any word. Content follows immediately on the next line.

Fences must be terminated with at least three colons alone on a line. For

example:

``` markdown

::: name

Content

:::

```

The output resembles:

``` html

<div class="name">

<p>Content</p>

</div>

```

### Extended syntax

Fenced divs have an extended syntax for more influence over the presentation.

The syntax allows for a unique identifier (marked with a hash, `#`), multiple

classes (each starting with a period, `.`), and key-value pairs (of the form

`name=value`):

``` 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.

:::

```

This 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>

```

While this syntax is not standard Markdown (i.e., CommonMark), it is supported

by many tools, including pandoc.

### Nested syntax

Fenced blocks may be nested to create hierarchical document structures:

``` markdown

::: poem

:::::: stanza

Because I could not stop for Death --

He kindly stopped for me --

The Carriage held but just Ourselves --

And Immortality.

::::::

:::

```

This produces nested `div` elements:

``` 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>

```

Such nesting can help with complex presentation logic.

## Code blocks

In technical documentation, source code snippets help explain algorithms.  An

example snippet syntax is given in the following quintessential BASIC program:

    ``` basic

    10 print "hi"

    20 goto 10

    ```

The word `basic` suggests that the presentation layer colourise the syntax

according to the rules of the BASIC programming language. Code blocks are also

used to draw diagrams using text-based syntaxes. See [@sec:text-diagrams] for

details.

## Inline classes

Inline classes can be assigned to words or phrases. This allows presentation

logic to stylize words based on their classification. The general form of

inline classes follows:

``` markdown

[word]{.class}

```

For example:

``` markdown

[radiation]{.glossary .warning}

```

The given example outputs the following XHTML:

``` html

<span class="glossary warning">radiation</span>

```

Note the semantic `warning` class instead of a direct colour class such

as `red`. This allows the colour to be changed at the presentation layer

without the class name becoming stale.

## Captions and cross-references

Captions provide context and descriptions for tables, figures, equations, and

so forth. Cross-references allow linking to captioned items throughout the

document.

### Caption syntax

A caption *must* start with a double colon (`::`) and *must* be separated by a

blank line from the item it describes.

For images:

``` markdown

![image title](https://example.com/image.png)

:: Figure caption text

```

For tables:

``` markdown

| a | b | c |

|---|---|---|

| 1 | 2 | 3 |

| 4 | 5 | 6 |

:: Table caption text

```

For equations:

``` markdown

$$E = mc^2$$

:: Equation caption text

```

Note that this syntax is not supported by any other Markdown tool.

### Cross-references

Cross-references use anchor type names and unique identifiers such as:

- `{#type-name:id}` -- defines an anchor name

- `[@type-name:id]` -- references the anchor

Example image with cross-reference:

``` markdown

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

![image title](https://placecats.com/500/300)

:: World's cutest animal {#fig:animal}

```

Anchors can include any type name and identifier, such as:

``` markdown

{#fig:cats}

{#图版:猫}

{#eq:mass-energy}

{#eqn:laplace}

```

### Predefined type names

To simplify writing captions and references, predefined type names correspond

to labels commonly used in documents. [@tbl:type-names] lists predefined

cross-reference type names along with their associated labels. Labels are

inserted into the document automatically.

| Type name                        | Label        |

|----------------------------------|--------------|

| algorithm, alg                   | Algorithm    |

| equation, eqn, eq                | Equation     |

| figure, fig                      | Figure       |

| formula                          | Formula      |

| listing, list, lst, source, src  | Listing      |

| lyric                            | Lyrics       |

| music, score                     | Score        |

| table, tbl, tab                  | Table        |

:: Cross-reference types and labels {#tbl:type-names}

You may add your own labels as follows:

1. Edit `xml-references.tex` in the `xhtml` theme subdirectory.

1. Insert a new line within the `ReferenceLabels` data set:

   ``` tex

   \setdataset[ReferenceLabels][en][

     typename=label,

   ]

   ```

1. Ensure there's a trailing comma (`,`).

1. Save the file.

## Quotation marks

{{app.title}} integrates KeenQuotes, a library for curling straight quotes in

both British and American English, with a high degree of

accuracy. To achieve this, all straight quotes are examined throughout the

document and, based on context, emitted as a particular entity encoding.

Understanding quotation mark encoding helps ensure proper typography in both

digital and print formats. Different encoding options provide flexibility for

various output requirements. [@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                 |

| quotehex | `’`  | Right single quotation mark's numeric value |

| modifier | `ʼ`  | The modifier letter apostrophe              |

:: Single straight quote encoding options {#tbl:quote-encoding}

When typesetting to PDF, only the semantically correct `'` value will be

curled. Authors may enter quotation marks by hand (`“”`), which will typeset as

expected.

### History

The origins of quotation marks trace back to scholarly annotation practices in

Ancient Greece. Greek scribes used marginal symbols like the diplé (`⟩`) to

highlight notable passages. A variant, the diplé periestigmene (`⸖`)—a diplé