evergreen-docs:dig_style_guide
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
evergreen-docs:dig_style_guide [2020/10/26 18:00] – [Linking] aneiman | evergreen-docs:dig_style_guide [2021/10/27 16:12] – [General] jpringle | ||
---|---|---|---|
Line 9: | Line 9: | ||
==== Add a Table of Contents to the top of each AsciiDoc file ==== | ==== Add a Table of Contents to the top of each AsciiDoc file ==== | ||
- | This simply means adding this AsciiDoc line near the top of each '' | + | This simply means adding this AsciiDoc line near the top of each '' |
- | <code asciidoc>: | ||
- | ==== Convert all headings from underline style to prefix/ | + | <code asciidoc> |
+ | : | ||
+ | |||
+ | |||
+ | |||
+ | ==== Use prefix/ | ||
The basic reasons are: | The basic reasons are: | ||
Line 44: | Line 48: | ||
The above breaks down as follows: | The above breaks down as follows: | ||
- | * xref - indicates a cross reference | + | * '' |
- | * reports - indicates the folder in the docs/ | + | * '' |
- | * reporter_folder.adoc - indicates the specific file being referenced | + | * '' |
- | * reporter_creating_folders - indicates the subheading being linked to within the file | + | * '' |
- | * [Creating Folders] - the link text that is displayed | + | * '' |
For historical purposes, the old xref syntax is below | For historical purposes, the old xref syntax is below | ||
- | **DO NOT USE THIS!** | + | The below is an example of the now-deprecated cross reference style. |
<code asciidoc> | <code asciidoc> | ||
<< | << | ||
Line 67: | Line 71: | ||
* 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 ==== | ||
Line 103: | 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 148: | Line 154: | ||
* 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 169: | Line 174: | ||
< | < | ||
- | .Use Case | + | Use Case |
************************************************ | ************************************************ | ||
This feature is useful in cases where | This feature is useful in cases where | ||
Line 182: | 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.txt · Last modified: 2023/06/01 12:22 by gmcharlton