Skip to content

style-asciidoc.adoc

Latest commit

 

History

History
297 lines (213 loc) · 8.85 KB

style-asciidoc.adoc

File metadata and controls

297 lines (213 loc) · 8.85 KB

AsciiDoc Coding Standards

Table of Contents

This is a very recent (09/2022) part of this document. Please help shaping it if you are familiar with asciidoc.

Preamble, TOC, Anchors etc.

Every file should start with a header. This is typically

:lang: en

and longer documents may also chose to set

:toc:

This should be followed by an anchor for that section or chapter that is represented in that file like

[[cha:<file-title>]]

If a chapter/section header shall be granted the option to be referenced from another part of the documentation then it needs an anchor. The anchor shall be a combination of an indicator of the kind of block that is referenced (cha, sec, fig ,tab, …​) together with a short name identifying the object.

Heading/Title Capitalization

The documentation prefers the "Title Case Capitalization". It is defined by several associations. Here the definition by the APA:

Title Case Capitalization

In title case, major words are capitalized, and most minor words are lowercase. […​]

  • major words: Nouns, verbs (including linking verbs), adjectives, adverbs, pronouns, and all words of four letters or more are considered major words.

  • minor words: Short (i.e., three letters or fewer) conjunctions, short prepositions, and all articles are considered minor words.

Sections and Subsections

The depth of sections shall not exceed 3 levels. If more structure is needed, subheadings can be inserted like this:

= Chapter
== Section
=== Subsection
.Subheading

While "Chapter" corresponds to the document’s title.

Usage of Italic and Monospace Font

Highlighting of special elements like component names, pin names etc. shall be italic. Short code snippets shall be in monospaecd font. Headings shall not be formatted either itlaic nor monospaced.

Example 1. Example
If you are using _component_a_ you have to set the use `parameter_x = 500.0`.

If you are using component_a you have to set the use parameter_x = 500.0.

If you have direction control of your spindle, then the HAL pins spindle.N.forward and spindle.N.reverse are controlled by the G-codes M3 and M4.

Values and Units

Between a value and its unit shall be always a space, preferably a thin space (U+2009).
To enter Unicode characters in most graphical editors,

  1. press and hold the Left Ctrl and Shift keys and hit the u key and then

  2. type the Unicode code with Ctrl + Shift still pressed.

In VIM, press Ctrl + v and then enter the Unicode code with prefixed "u".

Code Blocks

Asciidoc supports syntax highlighting for several languages. The most common used in LinuxCNC are: c, python, sh, tcl, xml.
They are used like this:

 [source,c]
 ----
 // some code
 ----

It also exists some LinuxCNC-specific syntax highlighting for hal, ini, ngc.
To use those, following lines need to be inserted:

// these attributes must come after the document title, to work around a bug in asciidoc 8.6.6
:ini: {basebackend@docbook:'':ini}
:hal: {basebackend@docbook:'':hal}
:ngc: {basebackend@docbook:'':ngc}

The keywords for those need to be surrounded by curly braces:

 [source,{ini}]
 ----
 // some code
 ----

Pin Listings

Compact Form
* **comp.group.**_N_**.pin** '(type, direction)' - Functional description

Example:

  • halui.joint.N.select '(bit, in)' - Pin for selecting joint N

  • halui.joint.N.is-selected '(bit, out)' - Status pin that joint N is selected

  • halui.joint.N.has-fault '(bit, out)' - Status pin telling that joint N has a fault

Where N is the instance number of the component. If it’s a component/module that can only be loaded once, a zero could/should replace N.

Indented Form with Line Break
* **comp.group.**_N_**.pin** '(type, direction)':: Functional description

Example:

pid.N.Pgain '(float, in)'

Proportional gain. Results in a contribution to the output that is the error multiplied by Pgain.

pid.N.Igain '(float, in)'

Integral gain. Results in a contribution to the output that is the integral of the error multiplied by Igain. For example an error of 0.02 that lasted 10 seconds would result in an integrated error (errorI) of 0.2, and if Igain is 20, the integral term would add 4.0 to the output.

pid.N.Dgain '(float, in)'

Derivative gain. Results in a contribution to the output that is the rate of change (derivative) of the error multiplied by Dgain. For example an error that changed from 0.02 to 0.03 over 0.2 seconds would result in an error derivative (errorD) of of 0.05, and if Dgain is 5, the derivative term would add 0.25 to the output.

Listings of Commands/Messages

Example 2. Panelui
home_selected

  • required argument: axis number (int)

unhome_selected

  • required argument: axis number (int)

spindle_forward_adjust

  • optional argument: starting RPM (int) - default 100

  • Description: If the spindle is stopped it will start in the forward direction. If it is already running it will increase or decrease the rpm depending on what direction the spindle is running in.

spindle_forward

  • optional argument: starting RPM (int) - default 100

Example 3. GStat
motion-mode-changed

'(returns integer)' - Sent when motion’s mode has changed

spindle-control-changed

'(returns integer, bool, integer, bool)' - (spindle num, spindle on state, requested spindle direction & rate, at-speed state)
Sent when spindle direction or running status changes or at-speed changes.

current-feed-rate

'(returns float)' - Sent when the current feed rate changes.

current-x-rel-position

'(returns float)' - Sent every 100ms.

current-position

'(returns pyobject, pyobject, pyobject, pyobject)' - Sent every 100ms.
returns tuples of position, relative position, distance-to-go and
the joint actual position. Before homing, on multi-joint axes, only joint
position is valid.

Images

  • Shall be centered

  • Shall have a caption if not embedded in the text

.Caption
image::image.png["Description",align="center"]

Table Formatting (to be filled by smoe 😉)

Tables can be presented with a series of options.

  • header
    With the header-option set, the fist line will be interpreted accordingly.

  • column width
    in ideal column, the column is constituted only by its data. No vertical separators should be required. The horizontal alignment will also not be required since the writing itself is horizontal enough.

    If individual fields have too much text then a line-break within that field should be provoked.

  • what lines are visible
    As motivated above, there should be no grid lines. The top and bottom lines should separate the table from the surrounding text. Another line could be motivated between the header and the main body.

  • captions
    Asciidoc makes it difficult to nicely prepare captions. At the same time, captions are the only bit of the whole document that even with the first flick through the document will not escape the reader’s attention.

  • spaces between ? for po4a

Instruction needs to be added

?

  • reference

    • figure formatting (captions)

  • reference

  • caption ---- Instruction needs to be added ----

    • footnotes

    • comments

    • interaction with other media like videos