Dave Jarvis' Repositories
git clone https://repo.autonoma.ca/repo/keenwrite.git
Rephrases docs to have nicer layout
| Author | DaveJarvis <email> |
|---|---|
| Date | 2025-09-04 17:05:10 GMT-0700 |
| Commit | 1511a671d7c6e1901535794330f227b1a8e4e47a |
| Parent | 9f0a93e |
docs/01-introduction.md
| into print-ready PDF files. This approach offers several benefits: | ||
| -* **Rebranding** -- Corporations can rebrand technical documents in weeks, instead of years | ||
| +* **Rebranding** -- Corporations can redesign documents in weeks, not years | ||
| * **Consistency** -- Ensure uniform, high-quality output | ||
| -* **Future-proofing** -- Plain text files will remain readable long after proprietary formats go obsolete | ||
| +* **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 and times | ||
| +* **Reproducible** -- Generate identical documents across different systems | ||
| * **Focus** -- Write without distraction from formatting concerns | ||
docs/02-installation.md
| When exporting a document to a PDF file for the first time, a wizard will guide | ||
| -you through the installation process. These steps will differ depending on the | ||
| +you through the installation process. The steps will vary based on the | ||
| operating system. | ||
| -Launch the installation wizard as follows: | ||
| +Launch the installation wizard to install the typesetter and themes: | ||
| 1. Start {{app.title}}. | ||
| 1. Click **File → Export As → PDF**. | ||
| - | ||
| -Use the wizard to install the requisite software and typesetting themes. | ||
| ## Manual |
docs/05-metadata.md
| # Metadata | ||
| -Metadata is information about a document and often includes a title, author | ||
| -keywords, copyright date, ISBN, word counts, and more. Most systems require | ||
| -coupling metadata directly to the source document. {{app.title}} fetches | ||
| -variable definitions from variable definitions file instead. This allows | ||
| -reusing the same metadata across documents. | ||
| +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 injected into a document either through the document properties | ||
| -settings in the user interface or by passing in `--metadata` arguments when | ||
| -run from the command line. | ||
| +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. | ||
|  | ||
| -:: Custom metadata {#fig:gui-metadata} | ||
| +:: Document metadata preferences {#fig:gui-metadata} | ||
| The **Key** column lists metadata names and the **Value** column lists the |
docs/06-basic-markdown.md
| # Basic Markdown | ||
| -This section outlines the basic formatting elements supported by {{app.title}}, | ||
| -including paragraphs, headers, lists, links, and tables. There are countless | ||
| -resources available on Markdown syntax, so only the most basic review is given | ||
| -here. | ||
| +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 | ||
 | ||
| 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. | ||
| +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 | ||
| ``` | ||
| ||
| My preference is to use `1.` for each ordered item and let the computer | ||
| -renumber them because it makes adding and removing items faster. | ||
| +renumber them because it makes adding and removing items faster, and | ||
| +guarantees that there will never be a number skipped. | ||
| ``` markdown | ||
| ||
| ## Links | ||
| -Links are created using square brackets for the link text followed by | ||
| -parentheses for the URL. | ||
| +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 separate columns and hyphens (`-`) to define the | ||
| -header row. | ||
| +Tables use pipes (`|`) to indicate separate columns and hyphens (`-`) to define | ||
| +the header row. Markdown does not define a syntax for table footers. | ||
| ``` markdown | ||
| ||
| | Value 4 | Value 5 | Value 6 | | ||
| ``` | ||
| + | ||
| +The colon location suggests columnar alignment to the presentation layer. | ||
docs/07-advanced-markdown.md
| ## Code blocks | ||
| -In technical documentation, including source code snippets can help illustrate | ||
| -concepts. The syntax for such snippets is exemplified in the following | ||
| -quintessential BASIC program: | ||
| +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` provides a hint to the presentation layer to 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. | ||
| +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. | ||
| ## Captions and cross-references | ||
| Captions provide context and descriptions for tables, figures, equations, and | ||
| -so forth. Cross-references allow linking to these captioned items throughout | ||
| -the document. | ||
| +so forth. Cross-references allow linking to captioned items throughout the | ||
| +document. | ||
| ### Caption syntax | ||
| ||
| opening quote or apostrophe, highlighting how historical decisions still impact | ||
| modern typography. | ||
| - | ||
| -## Mathematics | ||
| - | ||
| -Mathematical expressions can be embedded using TeX notation, to typeset | ||
| -formulas and equations. | ||
| - | ||
| -### Inline mathematics | ||
| - | ||
| -For inline mathematical expressions, enclose TeX code in single dollar signs: | ||
| - | ||
| -``` tex | ||
| -The equation $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ is the quadratic formula. | ||
| -``` | ||
| - | ||
| -### Display mathematics | ||
| - | ||
| -For standalone equations, use double dollar signs: | ||
| - | ||
| -``` tex | ||
| -$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$ | ||
| -``` | ||
| - | ||
| -### Common TeX notation | ||
| - | ||
| -Basic mathematical elements use standard TeX syntax: | ||
| - | ||
| -- Fractions: `\frac{numerator}{denominator}` | ||
| -- Square roots: `\sqrt{expression}` | ||
| -- Superscripts: `x^2` | ||
| -- Subscripts: `x_1` | ||
| -- Greek letters: `\alpha`, `\beta`, `\gamma`, etc. | ||
| -- Integrals: `\int` | ||
| -- Summations: `\sum` | ||
| -- Limits: `\lim_{x \to 0}` | ||
| - | ||
| -More complex expressions combine these elements: | ||
| - | ||
| -``` tex | ||
| -$$\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}$$ | ||
| - | ||
| -$$\lim_{x \to 0} \frac{\sin x}{x} = 1$$ | ||
| -``` | ||
| - | ||
| -When exported to XHTML, mathematical expressions can be output as TeX | ||
| -notation for use with KaTeX or MathJax. Or as SVG images. When exported to PDF, | ||
| -the typesetting system renders expressions directly. | ||
docs/11-math.md
| # Math | ||
| -Mathematical expressions are embedded using TeX notation, to typeset formulas | ||
| -and equations. TeX is a powerful typesetting system created by Donald Knuth for | ||
| -producing high-quality documents, especially those with complex mathematical | ||
| -and scientific notation. With TeX, you write plain text files with commands and | ||
| -then compile them into a final output, like a PDF. | ||
| +Mathematical expressions use TeX notation to typeset formulas and equations. | ||
| +TeX is a powerful typesetting system created by Donald Knuth for producing | ||
| +documents complex mathematical and scientific notation. With TeX, you write | ||
| +plain text commands and then build the final output as a separate step. | ||
| -{{app.title}} recognizes only plain TeX so as to be compatible with both | ||
| -ConTeXt and LaTeX typesetting systems. | ||
| +{{app.title}} supports only plain TeX, allowing usage of either ConTeXt or | ||
| +LaTeX. | ||
| ## TeX notation | ||
| -All TeX commands start with a backslash (`\\`), followed by the name of the | ||
| -command, and often use braces (`{}`) to contain their arguments. | ||
| +All TeX commands start with a backslash (`\`), followed by the name of the | ||
| +command, and often use braces (`{}`) for any arguments. | ||
| Some simple mathematical elements using standard TeX syntax include: | ||
| -- Fractions: `\frac{numerator}{denominator}` | ||
| -- Square roots: `\sqrt{expression}` | ||
| -- Superscripts: `x^2` | ||
| -- Subscripts: `x_1` | ||
| -- Greek letters: `\alpha`, `\beta`, `\gamma`, etc. | ||
| -- Integrals: `\int` | ||
| -- Summations: `\sum` | ||
| -- Limits: `\lim_{x \to 0}` | ||
| +* Fractions: `\fraction{numerator}{denominator}` | ||
| +* Square roots: `\sqrt{expression}` | ||
| +* Superscripts: `x^2` | ||
| +* Subscripts: `x_1` | ||
| +* Greek letters: `\alpha`, `\beta`, `\gamma`, etc. | ||
| +* Integrals: `\int` | ||
| +* Summations: `\sum` | ||
| +* Limits: `\lim_{x \to 0}` | ||
| More complex expressions combine these elements: | ||
| ``` tex | ||
| -\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6} | ||
| +\sum_{n=1}^{\infty} \fraction{1}{n^2} = \fraction{\pi^2}{6} | ||
| ``` | ||
| Produces: | ||
| + | ||
| +$$\sum_{n=1}^{\infty} \fraction{1}{n^2} = \fraction{\pi^2}{6}$$ | ||
| +:: Equation doohickey {#eqn:matter} | ||
| When exported to XHTML, mathematical expressions can be output as: | ||
| * TeX notation for use with KaTeX or MathJax; or | ||
| -* as SVG images. | ||
| +* SVG images. | ||
| When exported to PDF, the typesetting system renders expressions directly. | ||
| + | ||
| +## Syntax | ||
| + | ||
| +Mathematical expressions must be enclosed within sigils. Spaces are not | ||
| +allowed after the opening or before the closing sigil. | ||
| ## Inline expressions | ||
| -For inline mathematical statements, enclose TeX code in single dollar signs (`$`): | ||
| +Enclose inline TeX code within single dollar sign sigils (`$`): | ||
| ``` tex | ||
| -The equation $x=\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ is the quadratic formula. | ||
| +The quadratic formula is: $x=\fraction{-b \pm \sqrt{b^2 - 4ac}}{2a}$ | ||
| ``` | ||
| ## Standalone expressions | ||
| -For standalone statements, use double dollar signs (`$$`): | ||
| +Enclose standalone TeX code within double dollar sign sigils (`$$`): | ||
| ``` tex |
docs/12-r.md
| 1. Set the contents to: | ||
| - ``` r | ||
| - sum <- function( a, b ) { | ||
| - a + b | ||
| - } | ||
| - ``` | ||
| + ``` r | ||
| + sum <- function( a, b ) { | ||
| + a + b | ||
| + } | ||
| + ``` | ||
| 1. Click the **Save** icon. | ||
| ||
| ``` | ||
| -1. Save the file as `sum.R`. | ||
| +1. Save the file as `math.R`. | ||
| The preview tab shows the result of calling the `sum` function: | ||
| ||
| ``` | ||
| -1. Change `sum.Rmd` to: | ||
| +1. Change `math.Rmd` to: | ||
| ``` r | ||
| `r#mul( 5, 5 )` | ||
| ``` | ||
| -1. Close the file `sum.Rmd`. | ||
| +1. Close the file `math.Rmd`. | ||
| 1. Confirm saving the file when prompted. | ||
| -1. Re-open `sum.Rmd`. | ||
| +1. Re-open `math.Rmd`. | ||
| The preview tab shows: | ||
| ||
| 1. Select `definitions.yaml`. | ||
| 1. Click **Open**. | ||
| -1. Open `sum.Rmd` if it is not already open. | ||
| +1. Open `math.Rmd` if it is not already open. | ||
| 1. Type: `je` | ||
| 1. Press [Ctrl+Space]{.kbd}. | ||
| ||
| 1. Click **OK**. | ||
| -1. Close and re-open `sum.Rmd`. | ||
| +1. Close and re-open `math.Rmd`. | ||
| The preview tab shows: | ||
docs/13-gui.md
| ## Internationalization | ||
| -Internationalization (I18N) support is essential for editing and previewing | ||
| -text in multiple languages. Both fonts and language must be set for | ||
| -non-Latin-based text. [@tbl:editor-font-families] lists example | ||
| -Chinese-Japanese-Korean (CJK) font settings for the editor and preview tabs. | ||
| +Internationalization support is essential for editing and previewing text in | ||
| +multiple languages. Both fonts and language must be set for non-Latin-based | ||
| +text. [@tbl:editor-font-families] lists example Chinese-Japanese-Korean (CJK) | ||
| +font settings for the editor and preview tabs. | ||
| | Tab | Font Family | Language | |
docs/15-troubleshooting.md
| The SVG will now appear inside the application; however, the text may appear as black blocks. | ||
| -## Black blocks | ||
| +### Black blocks | ||
| Depending on how text is added to a vector graphic in Inkscape, the text may be | ||
| inserted within an element called a `flowRoot`. Although `flowRoot` is | ||
| recognized, the contents may not be fully interpreted, resulting in black | ||
| -blocks being drawn instead of text. | ||
| +blocks being drawn instead of text, as shown in [@fig:blocked-text]. | ||
|  | ||
| ||
| the text elements may ignore any assigned colour. | ||
| -## Black text | ||
| +### Black text | ||
| When an SVG `style` attribute contains a reference to `-inkscape-font-specification`, all values that follow said reference are ignored. This results in black text, shown in [@fig:blacked-text]. | ||
docs/17-appendix.md
| The background of [@fig:screenshot-pdf-themes] depicts a novel being edited. | ||
| - | ||
| - | ||
| - | ||
| -:: PDF Themes {#fig:screenshot-pdf-themes} | ||
| - | ||
| -Highlighted items of note: | ||
| +Note the following: | ||
| * 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 | ||
| +* Multiple styles (*Boschet*, *Handrit*, and *Tarmes*) | ||
| * Variations in page numbers | ||
| -* Manuscript includes word count, automatically | ||
| * Preferences dialog in the middle | ||
| + | ||
| + | ||
| + | ||
| +:: PDF Themes {#fig:screenshot-pdf-themes} | ||
| ### Internationalization | ||
| ||
| [@fig:screenshot-outline] shows a document outline opened and docked in | ||
| -bottom-left corner: | ||
| +the bottom-left corner: | ||
|  | ||
docs/user-manual.pdf
Binary files differ
| Delta | 90 lines added, 133 lines removed, 43-line decrease |
|---|