Metanorma: Aequitate Verum

Author's documentation

Source code

Source code

Basics

Metanorma AsciiDoc supports code blocks via the [source] block.

The source code block takes a pre-formatted text block rendered in monospace font, with line breaks and space indentations preserved.

The syntax is as follows:

[source]
----
Rendered in monospace text
----
Example 1. Example of rendering source code without language specification
[source]
----
Identifier(latitude, longitude, elevation, elevationType)

  return concat(
    "ISO.NLI",
    EncodePoint(latitude, longitude),
    EncodeElevation(elevation, elevationType)
  )
----

Syntax highlighting

It is possible to specify the computer language used in the [source] block to enable source code highlighting (syntax highlighting) for supported languages.

Metanorma integrates the Rouge syntax highlighter which applies to all of HTML, DOC, and PDF output [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2].

Note
 Before that date, it used the CodeRay client-side Google Code Prettify, which only applied to HTML output.

Syntax highlighting is enabled by default; it is turned off through the document attribute :source-highlighter: false [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2].

The full list of languages supported is given in Rouge Languages, with the language names that Rouge recognizes; e.g. Literate CoffeeScript is specified as literate_coffeescript.

[source,language]
----
Rendered in monospace with syntax highlighting
----

Line numbering

Line numbering can optionally be specified for a source code snippet through the %linenums option.

i.e. by entering [source%linenums,…​] instead of just [source,…​] [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2].

It can be enabled by default for code snippets through the document attribute source-linenums-option: true.

Line numbering requires syntax highlighting to be enabled.

Example 2. Example of rendering source code with language specification, line numbering, and syntax highlighting
.Ruby code for MyIdentifier#format (1)
[source%linenums,ruby] (2)
---- (3)
class MyIdentifier (4)
  def format(string)
    "did:#{string}"
  end
end
---- (5)

  1. (Optional) Title for source block

  2. (Optional) ruby here denotes the language used within the source block and linenums indicate the rendering of line numbers.

  3. Starting source delimiter of 4 - signs

  4. Source content

  5. Ending source delimiter of 4 - signs

Markup in source code blocks

It is sometimes necessary to introduce markup into source code. For example, hyperlinking words in source code to external definitions, or else introducing formatting in lieu of automated highlighting.

In order to achieve this, Metanorma allows inline AsciiDoc markup to be introduced into source code, isolating it from the rest of the source code through delimiters. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4]

By default, the delimiters are {{{ and }}}. These can be overridden (in case {{{ and }}} are already used in the document) through the document attributes :sourcecode-markup-start: and sourcecode-markup-end:.

Example 3. Example of applying inline formatting to source code blocks
[source,ruby]
--
{{{*def*}}} method1(x)
  {{{<<method2-definition,method2>>}}}(x) + 3
end
--

renders as:

def method1(x)
    method2(x) + 3
end