description.adoc

FIXME: add a description

Why is this an issue?

This rule is not really a rule, but a demonstration of the features from Asciidoc that can appear in a rule description.

All titles should be in sequence

No title 3 directly below title 1

Titles

There can be 4 different levels of titles, as demonstrated in this rule, usually with standard text.

Character format

It is not uncommon to have text in bold, italic, both. Less common are ^exponents and _indices.

We don’t directly use highlighting, but use a specific form of it to underline and strikethrough.

Source code

Code appears in embedded within a sentence, in some cases as part of words, without spaces surrounding it. Embedded code can also be an hyperlink.

It can also appear as a separate block:

private void OtherSourceCode()
{
    // We usually indicate what language is used for the code
}

But not always

private void YetAnotherSourceCode()
{
    // One rule may contain several languages
}

// And the code can contain information

// And the code can contain diff information

Diff-views are documented here.

When using diff-views, there should be one noncompliant example.

When using diff-views, there should be at least one compliant solution.
However, the diff-view feature was first designed to have only one compliant solution.

When using diff-views,
Be mindful that providing more than one compliant solution
is "supported" but may completely disable the diff highlighting.

This limitation is discussed here.

// We have cases where we are missing the [source,language] attributes
// TODO: Maybe we should detect and prevent this

Lists

There can be bullet lists:

• With

• three

  • An sublists

  • Up to

    • Three nested levels

    • But no more

• bullets

Or numbered lists:

1. A list

2. with numbers

   1. And also possible sublists

   2. with more items

Admonitions

They are not supported.

Warning: They are simulated with manual layout.

Links

There are links in the text, see https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#links for the various ways they can appear. Of course, the link can have another text.

We can also link to other rules, such as S100. We cannot specify which language is the target of this link, it is always the same as the current RSPEC language.

Tables

Title	What we use	Details
Tables	A simple table
Alignment	Can differ between cols
Header	The first line is often a header
Strong	A cell can be put in bold
Tables	A table	Nested asciidoc, with, for instance: Nested lists See for instance S5131
Merged cells	They are not supported
Borders	Most often all around
Nested tables	They are not supported

Includes

It is possible to include other files.

included1.adoc

Sometimes, the content of the included files can vary, with the use of a variable.

included2.adoc

Which file is included can also depend on a variable:

a.adoc

b.adoc

How to fix it

Code examples

Noncompliant code example

FIXME

Compliant solution

FIXME