User Tools

Site Tools


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 revision Previous revision
Next revision
Previous revision
evergreen-docs:dig_style_guide [2019/05/23 11:19]
rjs7 [Standard Terminology]
evergreen-docs:dig_style_guide [2020/06/05 12:57] (current)
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 96: 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.1558624782.txt.gz · Last modified: 2019/05/23 11:19 by rjs7

© 2008-2017 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.