Dave Jarvis' Repositories
git clone https://repo.autonoma.ca/repo/keenwrite.git
Reorders screenshots, adds replacement section, adds x-ref label note
| Author | DaveJarvis <email> |
|---|---|
| Date | 2025-09-05 00:41:14 GMT-0700 |
| Commit | eee9757fa28c91307b91555c9e805d94f377f2b5 |
| Parent | 1511a67 |
docs/01-introduction.md
| ## Think different | ||
| -The core philosophy behind {{app.title}} requires a shift in how we create and | ||
| -format documents. Unlike traditional word processors that mix content and | ||
| -formatting, {{app.title}} aims to completely separate content from | ||
| -presentation. You write in plain text, and let the computer typset the document | ||
| -into print-ready PDF files. This approach offers several benefits: | ||
| +The core philosophy behind {{app.title}} may require shifing 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 offers several benefits: | ||
| * **Rebranding** -- Corporations can redesign documents in weeks, not years | ||
| -* **Consistency** -- Ensure uniform, high-quality output | ||
| +* **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 | ||
| -* **Reproducible** -- Generate identical documents across different systems | ||
| +* **Reproducible** -- Generate the same output using different systems | ||
| * **Focus** -- Write without distraction from formatting concerns | ||
| ## Processing flow | ||
| -Understanding how {{app.title}} transforms your Markdown content into polished | ||
| -PDF files helps you make the most of its capabilities. | ||
| +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, | ||
 | ||
| In a nutshell: **Markdown → XHTML → TeX → PDF** | ||
| + | ||
| +This chain allows separating content (the Markdown source) from presentation | ||
| +(the 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}} offers a numerous tools to assist with document creation. | ||
| +{{app.title}} has numerous tools to assist with document creation. | ||
| ### Writing and editing | ||
| ||
| ### Advanced capabilities | ||
| -Beyond basic document creation, {{app.titile}} includes: | ||
| +Beyond basic document creation, {{app.title}} includes: | ||
| * **Data visualization** through R integration | ||
| * **Diagram generation** supporting PlantUML, GraphViz, Mermaid, and other text-based formats | ||
| * **Variable interpolation** enables a single source of truth for content | ||
| * **Internationalization** with font handling for multiple languages | ||
| ### User interface | ||
| -The user interface offers: | ||
| +The user interface has: | ||
| -* **Customizable** with dark mode and custom skins | ||
| +* **Dark mode** and other skin customizations | ||
| * **Multi-document editing** with detachable tabs | ||
| * **Live preview** showing formatted output as you write | ||
| -* **Distraction-free** when you need to focus | ||
| +* **Distraction-free** settings when you need to focus | ||
| ## Target users | ||
docs/02-installation.md
| 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: | ||
| +specific requirements. For example, the _Boschet_ theme requires downloading | ||
| +and installing specific font families, which include: | ||
| * [Inconsolata]({{fonts.url}}/inconsolata.zip) |
docs/03-quick-start.md
| | Inline code | `` `code` `` | | ||
| | Links | `[label](url)` | | ||
| -| Images | `` | | ||
| +| Images | `` | | ||
| | Blockquotes | `> quoted text` | | ||
| | Headings | `#`, `##`, `###` | |
docs/04-variables.md
| with its corresponding value. | ||
| -## YAML file format | ||
| +## 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 uses indentation to represent hierarchy and | ||
| -supports key-value pairs. | ||
| +readability and simplicity. YAML files allow encoding key-value pairs within | ||
| +a nested hierarchy. | ||
| Any number of variables can be defined, in any order: |
docs/06-basic-markdown.md
| 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. | ||
| +make the document easier to read in its plain-text format. | ||
| ``` markdown | ||
| ||
| ``` | ||
| -Alignment can be suggested using a colon (`:`) on the left, right, or both sides | ||
| -(centering) of the header separator line. | ||
| +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 suggests columnar alignment to the presentation layer. | ||
| +The colon location is a hint to the presentation layer, which has the | ||
| +freedom to ignore it. | ||
docs/07-advanced-markdown.md
| -# Advanced Markdown | ||
| +# 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. | ||
| +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 | ||
| ||
| ### Caption syntax | ||
| -Captions start with a double colon (`::`) separated by a blank line from the item they describe. The blank line is essential for proper formatting. | ||
| +A caption *must* start with a double colon (`::`) and *must* be separated by a | ||
| +blank line from the item it describes. | ||
| For images: | ||
| ||
| ### Cross-references | ||
| -Cross-references use anchor names and reference tags to link to captioned | ||
| -items. The syntax is: | ||
| +Cross-references use anchor type names and unique identifiers to captions: | ||
| -- `{#type-name:label}` for defining an anchor name | ||
| -- `[@type-name:label]` for referencing the anchor elsewhere | ||
| +- `{#type-name:id}` -- defines an anchor name | ||
| +- `[@type-name:id]` -- references the anchor | ||
| -Example with image and cross-reference: | ||
| +Example image with cross-reference: | ||
| ``` markdown | ||
| -In [@fig:animal], a cute animal is shown. | ||
| +There is no cuter animal than the one in [@fig:animal]. | ||
|  | ||
| :: World's cutest animal {#fig:animal} | ||
| - | ||
| -There is no cuter animal than the one in [@fig:animal]. | ||
| ``` | ||
| -Anchors can include a wide variety of type names and labels, such as: | ||
| +Anchors can include any type name and identifier, such as: | ||
| ``` markdown | ||
| ||
| To simplify writing captions and references, predefined type names correspond | ||
| -to labels commonly used in documents. These labels automatically generate | ||
| -suitable names. [@tbl:type-names] lists predefined cross-reference type names | ||
| -along with their associated labels, which are inserted automatically into the | ||
| -document. | ||
| +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 | English name | | ||
| +| Type name | Label | | ||
| |----------------------------------|--------------| | ||
| | algorithm, alg | Algorithm | | ||
| ||
| | table, tbl, tab | Table | | ||
| -:: Predefined cross-reference types and labels {#tbl:type-names} | ||
| +:: 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 | ||
| -Understanding quotation mark encoding helps ensure proper typography in both digital and print formats. Different encoding options provide flexibility for various output requirements. | ||
| +{{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. | ||
| ||
| When typesetting to PDF, only the semantically correct `'` value will be | ||
| -curled automatically. | ||
| +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é | ||
| accompanied by dots—was used by scholars to indicate disagreement with earlier | ||
| -interpretations. These marks laid groundwork for distinguishing quoted text. | ||
| +interpretations. These marks laid the groundwork for distinguishing quoted | ||
| +text. | ||
| By the seventeenth century, quotation marks appeared regularly in printed | ||
| texts. Western European typographers in the nineteenth century adopted the | ||
| convention of turning quotation mark pairs outward, creating the familiar | ||
| "double curved" style. | ||
| Early mechanical typewriters lacked many punctuation marks. Straight single and | ||
| double quotes served multiple roles: quotation marks, apostrophes, feet and | ||
| inches, and mathematical primes. Computer character sets later codified | ||
| -straight quotes, creating ongoing typographical challenges. | ||
| +straight quotes (such as ASCII character 34, `"`), creating ongoing | ||
| +typographical challenges. | ||
| Modern standards recommend using the right single quotation mark (`’`) for | ||
| apostrophes, though this creates semantic ambiguity since the same character | ||
| -closes dialogue. Consider the sentence: | ||
| +also closes dialogue. Consider the sentence: | ||
| > Ambiguity lurks in \"\'cause the horses\'\". | ||
| The meaning of `'cause` (*because* vs. *induce*) determines whether to use an | ||
| -opening quote or apostrophe, highlighting how historical decisions still impact | ||
| -modern typography. | ||
| +opening quote or apostrophe. Historical decisions still impact modern | ||
| +typography. | ||
docs/09-exporting.md
| Some themes include: | ||
| -* **Boschet** -- Based on Baskerville font with elegant styling. | ||
| -* **Handrit** -- Based on Courier font in double-spaced manuscript format. | ||
| -* **Tarmes** -- Based on Times Roman font with minimal styling. | ||
| -* **TeXomus** -- A technical format suitable for user manuals. | ||
| +* ***Boschet*** -- Based on Baskerville font with elegant styling. | ||
| +* ***Handrit*** -- Based on Courier font in double-spaced manuscript format. | ||
| +* ***Tarmes*** -- Based on Times Roman font with minimal styling. | ||
| +* ***TeXomus*** -- A technical format suitable for user manuals. | ||
| Theme selection is available during PDF export through the theme drop-down menu | ||
| in the export dialog. Each theme may have specific font requirements that must | ||
| be installed separately. | ||
| -Create themes by copying and modifying existing ones, such as *TeXomus* or | ||
| -*Tarmes*. | ||
| +Create themes by copying and modifying existing ones (e.g., *TeXomus* or | ||
| +*Tarmes*). | ||
docs/10-themes.md
| to select when exporting. | ||
| +## Text replacement | ||
| + | ||
| +Sometimes we want to bend typography to our will. {{app.title}} themes | ||
| +provide a mechanism to leverage the power of TeX to change the typesetting | ||
| +for particular words without adding hints to the source document. This | ||
| +truly exhibits the power of moving presentation logic elsewhere. | ||
| + | ||
| +Lua is a programming language that is tightly integrated with ConTeXt. Here's | ||
| +an example of using Lua to create a list of replacements: | ||
| + | ||
| +``` lua | ||
| +\startluacode | ||
| +userdata = userdata or {} | ||
| + | ||
| +userdata.TextReplacements = { | ||
| + [1] = { "a.m.", "\\cap{am}" }, | ||
| + [2] = { "TeX", "\\TeX{}" }, | ||
| +} | ||
| +\stopluacode | ||
| +``` | ||
| + | ||
| +This will cause `a.m.` to be replaced with its smallcaps version as well as all | ||
| +occurrences of the word `TeX` with its iconic lowered-E. Case is sensitive. | ||
| +Most themes, such as *Boschet*, include a list of replacements inside a file | ||
| +named `replace.tex` in the theme-specific subdirectory. | ||
| + | ||
| ## Resources | ||
docs/14-cli.md
| The following invocations will convert `01.md` into the respective file | ||
| formats, determined by the file name extension. In the first case, it will | ||
| -become an XHTML page. In the second case, it will become a plain text document | ||
| +become an XHTML page. In the second case, it will become a plain-text document | ||
| with all variables interpolated and replaced. | ||
docs/15-troubleshooting.md
| Resolve the issue of colourless text as follows: | ||
| -1. Open the SVG file in a plain text editor. | ||
| +1. Open the SVG file in a plain-text editor. | ||
| 1. Remove all references `-inkscape-font-specification:'<FONT>';`, including the trailing (or leading) semicolon. | ||
| 1. Save the file. |
docs/16-oss.md
| ## Architecture overview | ||
| -[@fig:architecture] illustrates the software's high-level application architecture. The architecture involves a processing pipeline that transforms | ||
| -Markdown content through multiple stages to produce the final output. The | ||
| -Markdown processor contains both prepackaged and custom extensions. This | ||
| -extensible architecture allows for specialized processing of various Markdown | ||
| -syntaxes. | ||
| +[@fig:architecture] illustrates the software's high-level application | ||
| +architecture. The processing pipeline transforms textual content through | ||
| +multiple stages to produce the final document. Each processor in the | ||
| +chain receives a document from its predecessor. This allows each | ||
| +processor to handle a single responsibility, such as curling quotation | ||
| +marks, replacing variable names, or inserting a caret position. | ||
|  |
docs/17-appendix.md
| This section provides application screenshots. | ||
| -### 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 | ||
| ||
| :: PDF Themes {#fig:screenshot-pdf-themes} | ||
| -### Internationalization | ||
| +### Dockable tabs | ||
| -[@fig:screenshot-locale] shows a poem with locale settings: | ||
| +[@fig:screenshot-outline] shows a document outline opened and docked in | ||
| +the bottom-left corner: | ||
| - | ||
| + | ||
| -:: Locale settings {#fig:screenshot-locale} | ||
| +:: Document outline {#fig:screenshot-outline} | ||
| + | ||
| +### Variables | ||
| + | ||
| +A diagram that includes variables is shown in [@fig:screenshot-diagram-genealogy]. | ||
| + | ||
| + | ||
| + | ||
| +:: Family tree diagram {#fig:screenshot-diagram-genealogy} | ||
| ### Equations | ||
| [@fig:screenshot-tex] shows TeX equations in a detached preview tab: | ||
|  | ||
| :: TeX equations {#fig:screenshot-tex} | ||
| -### Dockable tabs | ||
| +### Internationalization | ||
| -[@fig:screenshot-outline] shows a document outline opened and docked in | ||
| -the bottom-left corner: | ||
| +[@fig:screenshot-locale] shows a poem with locale settings: | ||
| - | ||
| + | ||
| -:: Document outline {#fig:screenshot-outline} | ||
| +:: Locale settings {#fig:screenshot-locale} | ||
| ## Acknowledgments | ||
docs/user-manual.pdf
Binary files differ
| Delta | 135 lines added, 85 lines removed, 50-line increase |
|---|