| Author | DaveJarvis <email> |
|---|---|
| Date | 2025-08-30 16:03:14 GMT-0700 |
| Commit | d13e5b82f23c480459fdbc883f1266b1c2a5c445 |
| Parent | 38f9569 |
| Delta | 482 lines added, 0 lines removed, 482-line increase |
| +# 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. | ||
| + | ||
| +# 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. | ||
| + | ||
| +# Graphical User Interface | ||
| + | ||
| +This chapter covers customizing the graphical user interface (GUI). | ||
| + | ||
| +## Internationalization | ||
| + | ||
| +Internationalization (I18N) support is essential for editing and previewing text in multiple languages. The application has components dedicated to this, primarily involving font and language configurations. | ||
| + | ||
| +Both fonts and language must be set for non-Latin-based text. [@tbl:editor-font-families] lists possible font settings for the editor and preview tabs. | ||
| + | ||
| +| Tab | Font Family | Language | | ||
| +| ------- | ------------------- | ------------------ | | ||
| +| Editor | Noto Sans CJK KR | Korean | | ||
| +| Editor | Noto Sans CJK JP | Japanese | | ||
| +| Editor | Noto Sans CJK HN | Chinese | | ||
| +| Editor | Noto Sans CJK SC | Simplified Chinese | | ||
| +| Preview | Noto Serif CJK KR | Korean | | ||
| +| Preview | Noto Serif CJK JP | Japanese | | ||
| +| Preview | Noto Serif CJK HN | Chinese | | ||
| +| Preview | Noto Serif CJK SC | Simplified Chinese | | ||
| + | ||
| +:: Editor and preview tab font families {#tbl:editor-font-families} | ||
| + | ||
| +### Editor font | ||
| + | ||
| +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: | ||
| + | ||
| +* Install the desired fonts (restart the application). | ||
| +* Enter font name directly if it cannot be selected. | ||
| + | ||
| +## 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. | ||
| + | ||
| +## Skins | ||
| + | ||
| +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 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: | ||
| + | ||
| +1. **scene.css** --- Defines toolbar styling. | ||
| +1. **markdown.css** --- Defines text editor styling. | ||
| +1. **skins/skin_name.css** --- Bundled skin selected in preferences. | ||
| +1. **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; | ||
| +} | ||
| +``` | ||
| + | ||
| +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 more control, this section explains how to use pre-existing skin templates with defined classes, making it easier to tweak the GUI. Accomplish this as follows: | ||
| + | ||
| +1. Visit the [skin](https://repo.autonoma.ca/keenwrite.git/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://repo.autonoma.ca/keenwrite.git/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 | ||
| + | ||
| +JavaFX CSS have advanced styling capabilities. The [Java CSS Reference Guide](https://openjfx.io/javadoc/21/javafx.graphics/javafx/scene/doc-files/cssref.html) shows differences between JavaFX CSS and W3C CSS. The guide covers functions for manipulating colours and gradients using existing colour definitions. | ||
| + | ||
| +### RichTextFX | ||
| + | ||
| +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`. | ||
| + | ||
| +# 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) | ||
| + | ||