Skip to content
Metanorma
On this page

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 of rendering source code without language specification

Example
[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 metanorma-standoc ≥ 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 metanorma-standoc ≥ 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,...] metanorma-standoc ≥ 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 of rendering source code with language specification, line numbering, and syntax highlighting

Example
.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. metanorma-standoc ≥ 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 of applying inline formatting to source code blocks

Example
[source,ruby]
--
{{{*def*}}} method1(x)
  {{{<<method2-definition,method2>>}}}(x) + 3
end
--

renders as:

def method1(x)&nbsp;&nbsp;&nbsp;&nbsp;method2(x) + 3end

Note
The {{{ ... }}} markup already converts inline AsciiDoc, so it does not need to be combined with the macros substitution (subs="macros" or subs="verbatim,macros"). If it is combined, and a {{{ ... }}} span contains an inline macro such as image:, AsciiDoc resolves that macro into an element before Metanorma processes the delimiters; Metanorma then strips the delimiters around the resolved element, but any non-macro markup in the same span (for example bold) is left as literal text rather than being converted. To have all of a span's content converted, use {{{ ... }}} on its own, without subs="macros".

Edit this page on GitHub →