evergreen-docs:dig_style_guide
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
evergreen-docs:dig_style_guide [2019/05/23 11:19] – [Standard Terminology] rjs7 | evergreen-docs:dig_style_guide [2023/06/01 12:22] (current) – update branch name from master to main gmcharlton | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== DIG AsciiDoc Style Guide (draft) ====== | + | ====== DIG AsciiDoc Style Guide ====== |
+ | |||
+ | ===== New AsciiDoc Style Changes for Antora ===== | ||
+ | |||
+ | As of the 3.6 release of Evergreen, we are using Antora as a new " | ||
+ | |||
+ | In addition, DIG recommends the following changes. | ||
+ | |||
+ | ==== Add a Table of Contents to the top of each AsciiDoc file ==== | ||
+ | |||
+ | This simply means adding this AsciiDoc line near the top of each '' | ||
+ | |||
+ | |||
+ | <code asciidoc> | ||
+ | : | ||
+ | |||
+ | |||
+ | |||
+ | ==== Use prefix/ | ||
+ | |||
+ | The basic reasons are: | ||
+ | |||
+ | * It's hard to remember which character means which level heading | ||
+ | * It's hard to maintain the correct number of characters (must match length of heading line) | ||
+ | * Prefix/ | ||
+ | |||
+ | **Example: Change this** | ||
+ | <code asciidoc> | ||
+ | Heading 1 | ||
+ | --------- | ||
+ | </ | ||
+ | |||
+ | **To this** | ||
+ | <code asciidoc> | ||
+ | == Heading 1 == | ||
+ | </ | ||
+ | |||
+ | Here's a Python script that could help with the conversion (only adds prefix; we'd need to modify it to add the suffix): | ||
+ | * https:// | ||
+ | |||
+ | ==== Changes to cross-reference structure | ||
+ | |||
+ | Antora requires a new cross-reference structure. All existing cross references were converted via script, but new docs will need to indicate cross references in this manner: | ||
+ | |||
+ | <code asciidoc> | ||
+ | xref: | ||
+ | </ | ||
+ | |||
+ | The above breaks down as follows: | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | For historical purposes, the old xref syntax is below | ||
+ | |||
+ | The below is an example of the now-deprecated cross reference style. **DO NOT USE THIS!** | ||
+ | <code asciidoc> | ||
+ | << | ||
+ | </ | ||
+ | |||
+ | ---- | ||
+ | |||
===== General ===== | ===== General ===== | ||
* **Avoid changing section titles**. These are used to auto-generate anchor tags which are often used for links. Change with care, and check for links in other docs. | * **Avoid changing section titles**. These are used to auto-generate anchor tags which are often used for links. Change with care, and check for links in other docs. | ||
- | * Always **review changes** before committing to master | + | * Always **review changes** before committing to main (and check the updated web page the next day to make sure it worked right). |
- | * Always use **spell-check** on new content (including when porting old docs into master). | + | * Always use **spell-check** on new content (including when porting old docs into main). |
* AsciiDoc code lines should be 80 characters long or shorter. (Occasionally, | * AsciiDoc code lines should be 80 characters long or shorter. (Occasionally, | ||
* Screenshots should be smaller than 1050 pixels wide (when possible). | * Screenshots should be smaller than 1050 pixels wide (when possible). | ||
+ | * Rather than recreating documentation text in multiple adoc files, instead link directly to the main adoc for the feature. | ||
===== Formatting ===== | ===== Formatting ===== | ||
==== Headers ==== | ==== Headers ==== | ||
* Headers should be in title case (i.e. capitalize important words) | * Headers should be in title case (i.e. capitalize important words) | ||
- | * Headers can be formatted in either of two ways, but a single AsciiDoc file should use the same style consistently. | + | * As noted above, the preferred Header format is the Header Prefix Suffix format. |
+ | * Start all pages with Title 0, followed by :toc: | ||
=== Changing A Section Heading === | === Changing A Section Heading === | ||
Line 21: | Line 87: | ||
**Header Prefix Syntax** | **Header Prefix Syntax** | ||
< | < | ||
- | == Header Level 1 | + | = Header Level 0 = |
- | === Header Level 2 | + | == Header Level 1 == |
- | ==== Header Level 3 | + | === Header Level 2 === |
- | ===== Header Level 4 | + | ==== Header Level 3 ==== |
+ | ===== Header Level 4 ===== | ||
</ | </ | ||
**Header Underline Syntax** | **Header Underline Syntax** | ||
- | < | + | |
- | Header Level 1 | + | As noted above, we are no longer using the header underline syntax as of the 3.6 documentation due to the Antora move. |
- | -------------- | + | |
- | Header Level 2 | + | |
- | ~~~~~~~~~~~~~~ | + | |
- | Header Level 3 | + | |
- | ^^^^^^^^^^^^^^ | + | |
- | Header Level 4 | + | |
- | ++++++++++++++ | + | |
- | </ | + | |
Line 49: | Line 108: | ||
* This allows AsciiDoc to auto-number the items as needed. | * This allows AsciiDoc to auto-number the items as needed. | ||
* **Ampersands** should be left as is (&). Don't use an HTML entity (which ironically causes errors in our HTML generator). | * **Ampersands** should be left as is (&). Don't use an HTML entity (which ironically causes errors in our HTML generator). | ||
+ | * If an ampersand appears in the staff client or OPAC use the ampersand in the documentation. | ||
* Any **code and command line commands** should be marked as +code+ or `code` | * Any **code and command line commands** should be marked as +code+ or `code` | ||
* If the code or command is hard to read when included in the paragraph, consider using a code block: | * If the code or command is hard to read when included in the paragraph, consider using a code block: | ||
Line 63: | Line 123: | ||
* Use consistent action words | * Use consistent action words | ||
- | * **Enter** or **Type** a value into the text box | + | * **Enter** a value into the text box |
- | * **Check** the check box if the situation applies | + | * **Check** or **Uncheck** the check box if the situation applies |
- | * **Choose** or **Select** an option from the drop down box (or drop down menu?) | + | * **Choose** or **Select** an option from the drop down menu |
- | * **Click** the button, tab or menu -> menu2 -> menu3 | + | * **Select** the button, tab or menu -> menu2 -> menu3 |
* **Right-click** to show the *Actions* menu | * **Right-click** to show the *Actions* menu | ||
* Location words should use hyphens | * Location words should use hyphens | ||
Line 91: | Line 151: | ||
* Syntax: '' | * Syntax: '' | ||
* Example: | * Example: | ||
- | * Heading of "Create a provider" could be named '' | + | * Heading of "Creating Folders" |
* CAUTION: If you define an anchor that already exists, it will cause errors while building the HTML pages. If there are two sections with the same name, give them more specific names, like '' | * CAUTION: If you define an anchor that already exists, it will cause errors while building the HTML pages. If there are two sections with the same name, give them more specific names, like '' | ||
* LINK | * LINK | ||
- | * Syntax: '' | + | * Syntax: '' |
* Example: | * Example: | ||
- | * '' | + | * '' |
- | * http:// | + | |
* Add terms to the index | * Add terms to the index | ||
* Syntax: '' | * Syntax: '' | ||
Line 115: | Line 174: | ||
< | < | ||
- | .Use Case | + | Use Case |
************************************************ | ************************************************ | ||
This feature is useful in cases where | This feature is useful in cases where | ||
Line 128: | Line 187: | ||
* **Don' | * **Don' | ||
* **When replacing a screenshot**, | * **When replacing a screenshot**, | ||
+ | * Image syntax: '' | ||
+ | * Alt text: Please remember to include alt text in the image syntax for descriptive and accessibility reasons. | ||
+ | * Screen shots can be from any installation of Evergreen, as long as it does not contain any personal identifiable information, | ||
===== Common Mistakes ===== | ===== Common Mistakes ===== | ||
* AsciiDoc lists (numbered or bulleted) need to be preceded by a blank line. If not, they will be absorbed into the previous paragraph of text, like this: | * AsciiDoc lists (numbered or bulleted) need to be preceded by a blank line. If not, they will be absorbed into the previous paragraph of text, like this: | ||
* '' | * '' | ||
+ | * Callouts should be formatted as ''< | ||
+ | * Images, text blocks, or code blocks that are part of a numbered lists need to have a '' | ||
+ | |||
+ | <code asciidoc> | ||
+ | To edit a Receipt: | ||
+ | |||
+ | . Select *Administration -> Workstation -> Print Templates*. | ||
+ | . Choose the Receipt in the drop down list. | ||
+ | . If you are using Hatch, you can choose different printers for different types | ||
+ | of receipts with the Force Content field. If not, leave that field blank. | ||
+ | Printer Settings can be set at *Administration -> Workstation -> Printer | ||
+ | Settings*. | ||
+ | + | ||
+ | image:: | ||
+ | + | ||
+ | . Make edits to the Receipt on the right hand side. | ||
+ | </ | ||
+ | |||
+ | Note how this preserves the numbering: | ||
+ | |||
+ | {{: | ||
===== Further Reading ===== | ===== Further Reading ===== |
evergreen-docs/dig_style_guide.1558624782.txt.gz · Last modified: 2022/02/10 13:34 (external edit)