Evergreen DokuWiki

User Tools

Site Tools

You are here: start » evergreen-docs » dig_style_guide
evergreen-docs:dig_style_guide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
Next revisionBoth sides next revision
evergreen-docs:dig_style_guide [2019/03/07 08:55] – [Headers] rjs7evergreen-docs:dig_style_guide [2020/06/05 12:57] – lfloyd
Line 1: Line 1:
 ====== DIG AsciiDoc Style Guide (draft) ====== ====== DIG AsciiDoc Style Guide (draft) ======
 +
 +===== Proposal: Antora with Some AsciiDoc Changes =====
 +
 +A small working group has been testing Antora as a new "framework" for the Evergreen docs.  Antora requires some minor 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 to these minor changes, the **working group proposes the following changes**, which are not necessary for using Antora but we believe would make the docs better.
 +
 +==== 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 old system added this during the HTML build process.)
 +
 +<code asciidoc>:toc:</code>
 +
 +==== Convert all headings from underline style to prefix/suffix 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
 +
 +
 +----
 +
 +----
 +
 +
  
 ===== General ===== ===== General =====
Line 10: Line 51:
 ==== 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.+  * Headers can be formatted in either of two ways, but a single AsciiDoc file should use the same style consistently. The prefered method is the Header Prefix Suffix format. 
 +  * Start all pages with Title 0.
  
 === Changing A Section Heading === === Changing A Section Heading ===
Line 21: Line 63:
 **Header Prefix Syntax** **Header Prefix Syntax**
 <code> <code>
-== 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 =====
 </code> </code>
  
 **Header Underline Syntax** **Header Underline Syntax**
 <code> <code>
 +Header Level 0
 +==============
 Header Level 1 Header Level 1
 -------------- --------------
Line 63: Line 108:
  
   * 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 81: Line 126:
   * **Menu Bar**: The green bar at the top of the Web Client (includes dropdowns for Search, Circulation, Cataloging, etc.)   * **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)   * **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 ===== ===== Linking =====
Line 94: Line 141:
       * Syntax: ''%%<<section_id,caption>>%%'' (can be inline)       * Syntax: ''%%<<section_id,caption>>%%'' (can be inline)
       * Example:       * Example:
-        * ''Read about <<create_a_provider,creating a provider>> for more details.''+        * ''%%Read about <<create_a_provider,creating a provider>> for more details.%%''
     * http://www.methods.co.nz/asciidoc/asciidoc.html#_internal_cross_references     * http://www.methods.co.nz/asciidoc/asciidoc.html#_internal_cross_references
   * Add terms to the index   * Add terms to the index
evergreen-docs/dig_style_guide.txt · Last modified: 2023/06/01 12:22 by gmcharlton
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.