Add dedicated section or page for the linenums option on source blocks

[mojavelinux]

Source blocks support the linenums option. This option adds line numbers to the rendered source block when supported by the source highlighter or converter.

:source-highlighter: rouge

[source%linenums,js]
----
function fib (n) {
  if (n < 2) return n
  return fib(n - 1) + fib(n - 2)
}

console.log([1, 2, 3, 4, 5].map(fib))
----

The linenums option can also be specified as the third positional (unnamed) attribute on the source block.

:source-highlighter: rouge

[source,js,linenums]
----
function fib (n) {
  if (n < 2) return n
  return fib(n - 1) + fib(n - 2)
}

console.log([1, 2, 3, 4, 5].map(fib))
----

However, the named option is preferred. The option can also be enabled globally by setting the source-linenums-option attribute.

The docs should emphasize that while the option is a part of the AsciiDoc language, it does require support from the toolchain (syntax highlighter adapter, converter, and/or output format), so it may not always be honored.

The linenums option is documented in passing in the Asciidoctor docs on the page for each syntax highlighter adapter. See:

• https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/pygments/
• https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/rouge/
• https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/coderay/

However, this topic deserves its own section or page to define it and solidify it as part of the AsciiDoc language.

[graphitefriction]

This issue has moved to https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues/18