====== 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 "framework" for the Evergreen docs.  Antora requires some changes to the directory structure, and it reveals some AsciiDoc syntax errors (since it uses the more strict AsciiDoctor for converting to HTML).

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 ''.adoc'' file. The toc designation should go on the 2nd line of your file, just below the top header. (The old system added this during the HTML build process.)


<code asciidoc>= Heading =
:toc:</code>



==== Use prefix/suffix style headings instead of underline style ====

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/suffix style solves these problems, and is more readable in text format than prefix-only style

**Example: Change this**
<code asciidoc>
Heading 1
---------
</code>

**To this**
<code asciidoc>
== Heading 1 ==
</code>

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://github.com/JanusGraph/janusgraph/pull/115/commits/dc67ce73c08e79fa65b30bc8280861056070c573

==== 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:reports:reporter_folder.adoc#reporter_creating_folders[Creating Folders]
</code>

The above breaks down as follows:
  * ''xref'' - indicates a cross reference
  * ''reports'' - indicates the folder in the docs/modules/ directory
  * ''reporter_folder.adoc'' - indicates the specific file being referenced
  * ''reporter_creating_folders'' - indicates the subheading or anchor being linked to within the file 
  * ''[Creating Folders]'' - the link text that is displayed

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>
<<reporter_creating_folders,Creating Folders>>
</code>

----



===== 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.
  * 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 main).
  * AsciiDoc code lines should be 80 characters long or shorter. (Occasionally, exceptions are necessary for correct syntax.)
  * 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 =====
==== Headers ====
  * Headers should be in title case (i.e. capitalize important words)
  * 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 ===
To prevent breaking internal links:
  - Any time we edit a section heading (even fixing a typo), first check the HTML of the docs for the autogenerated anchor name.  (This will be in an <a id=""> tag, just inside the "<h2>" tag, or "<h3>", etc. Example anchor name: "_shelving_location_groups")
  - Search the docs code for that exact anchor name to find any references. (These will look like "<<anchor_name,link text>>".)
  - Update the section heading and any references you found (it's okay to guess at the new anchor name; the docs committer can double-check this after it's published).
  - NOTE: This may change the docs page URL, which would break external links and bookmarks. To prevent this, ask the [[open-ils-documentation@list.georgialibraries.org|DIG email list]] how they handle redirecting pages that move.

**Header Prefix Syntax**
<code>
= Header Level 0 =
== Header Level 1 ==
=== Header Level 2 ===
==== Header Level 3 ====
===== Header Level 4 =====
</code>

**Header Underline Syntax**

As noted above, we are no longer using the header underline syntax as of the 3.6 documentation due to the Antora move.


==== Other Formatting ====
  * **Actions** that leave the page should be in *bold* (buttons, navigation [links, tabs, menu trails])
  * **Field names** (and other special terms) may be in _italics_ for clarity, at the author's discretion
  * A **sequence of actions** should have this arrow %%->%% between them
    * Example: Click %%Administration -> Local Administration -> Library Settings Editor%%
  * Names for **keyboard keys** should be in all caps (e.g. "Press CTRL-TAB to switch browser tabs...")
  * **Numbered list items** should simply start with ". " (e.g. ". Text Goes Here"), instead of "1. ", etc.
    * 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).
    * If an ampersand appears in the staff client or OPAC use the ampersand in the documentation.  In all other cases use the word 'and' instead of an ampersand. 
  * 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:
<code asciidoc>
.Optional Title
[source,perl]
----
# This is a *source* block
print "Hello world!";
----
</code>

===== Wording =====

  * Use consistent action words
    * **Enter** a value into the text box
    * **Check** or **Uncheck** the check box if the situation applies
    * **Choose** or **Select** an option from the drop down menu
    * **Select** the button, tab or menu -> menu2 -> menu3
    * **Right-click** to show the *Actions* menu
  * Location words should use hyphens
    * On the **top-right** of the page
  * Use clear, standard terms
    * **Public catalog**, **staff catalog** or **catalog** (not TPAC or OPAC)
  * Use words that match the wording in the module you are describing
    * Example: The "MARC Batch Import/Export" interface is also sometimes labeled "Evergreen MARC File Upload". Both of these names are equally appropriate within the documentation. However, this interface is commonly called "Vandelay" throughout the code. Since the name "Vandelay" is not used in the staff client interface, it should be avoided in the documentation.
  * Add after each required field description: "This field is required."
    * (Or is it nicer to have a summary of required fields in a note at the end of the form?)

==== Standard Terminology ====

  * **Menu Bar**: The green bar at the top of the Web Client (includes dropdowns for Search, Circulation, Cataloging, etc.)
  * **Table Action Bar** or **Grid Function Row**: The row just above most grid/tables in the web client (includes table title on the left, and dropdowns on the right for Actions, paging, and column settings)
  * See the [[evergreen-docs:glossary|Glossary]] for preferred versions of Evergreen terms. Here are some common examples:
    * **Library Setting** (instead of "org unit setting" or "yaous")
    * **Library** or **Organizational Unit** (instead of "org unit")

===== Linking =====

  * Internal Links (i.e. cross references) have two parts
    * ANCHOR (must be unique throughout the docs):
      * Syntax: ''%%[[section_id]]%%'' (on its own line)
      * Example:
        * Heading of "Creating Folders" in the Reports documentation could be named ''reporter_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 ''create_a_provider_details''.
    * LINK
      * Syntax: ''%%xref:module:filename.adoc#section_id[caption]%%'' (can be inline)
      * Example:
        * ''%%Read about xref:reports:reporter_folder.adoc#reporter_creating_folders[Creating Folders] for more details.%%''
  * Add terms to the index
    * Syntax: ''indexterm:[<primary>,<secondary>,<tertiary>]''
    * Example: ''indexterm:[Tigers,Big cats]''
    * http://www.methods.co.nz/asciidoc/asciidoc.html#_indexes

<html><!--
  * LINK
    * Syntax: ''xref:section-id[<caption>]''
--></html>

===== Special blocks =====

==== Use case ====

When you want to document __why__ a particular feature might be used, it's helpful to put that in an Asciidoc "sidebar" (though it often is displayed as a callout block).  Syntax:

<code>
Use Case
************************************************
This feature is useful in cases where
your library wants to catalog books about
tigers and other big cats.
************************************************
</code>
===== Screenshots =====

  * Keep them as **small and focused** as possible while still **giving enough context** to make them useful to readers. If a screenshot focuses on a small portion of the screen, then it takes up less space in the docs and is less likely to need updating when future versions of Evergreen modify other parts of the screen.
  * **Highlight** parts of the screen using a border or arrow, when it seems helpful.
  * **Don't add a border or shadow** to the screenshot image. That can be done globally to all screenshots in the docs via CSS, if we want it.
  * **When replacing a screenshot**, if the intention of the image isn't changing, then create a new image with the same file name as the old image.  However, if you are essentially removing a screenshot and adding a different one (with a different focus or purpose), it is better to use a different file name (and update the reference to it in the docs!), and probably to change the related text in the documentation also.
  * Image syntax: ''image::ascii_doc_name/imagename.png[alt text]''. Starting with version 3.8 screenshots should be put into folders with the same name as the page the images appear on.  For example, if your page is circulation_policies.adoc in the admin folder the image folder would be called circulation_policies and would be in admin -> assets -> images -> circulation_policies.
  * 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, and is based on stock Evergreen. 
===== 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:
    * ''Here's a list: . Item 1 . Item 2 . Item 3''
  * Callouts should be formatted as ''<1>'' and not as ''<––! <1> ––>''
  * Images, text blocks, or code blocks that are part of a numbered lists need to have a ''+'' preceding and following the image or block so the numbering continues in the correct order. See example below.

<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::media/receipt1.png[select checkout]
+
. Make edits to the Receipt on the right hand side.
</code>
 
Note how this preserves the numbering:

{{:evergreen-docs:image_in_numbered_list.png?nolink&600|}}

===== Further Reading =====

  * Consider incorporating ideas from [[documentation:style_guide|The Book of Evergreen: Style Guide]]