Potential Extensions (Parser Plugins) - gmarpons/asciidoc-hs GitHub Wiki

Table of Contents

Syntactic extensions (aka plugins) can be:

  • Enabled/disabled on user demand.

  • Easily defined using a small and clear API.

This page documents AsciiDoc syntactic features (existent or imagined) that are good candidates at being implemented as syntactic extensions.

Asciidoctor / AsciiDoc Python Differences

Being able to enable/disable differentiating features can be useful in the transition from one tool to another.

Differences are documented here:

Differences in Inline Parsing

  • Different formatting marks, for example for italic text: 'italic text' or _italic text_ in AsciiDoc Python, only _italic text_ in Asciidoctor (without the compat-mode attribute).

    Example 1. Use of single quoted text with and without compat-mode in Asciidoctor.

    With compat-mode enabled: single-quoted text.

    Without compat-mode: 'single-quoted text' (quotes are copied verbatim).

Differences in Block Parsing

  • Asciidoctor allows the document id to be set using above the document header (adds id attribute to <body> tag).

  • In Asciidoctor, section title underlines must be within 1 character of the length of the title (AsciiDoc allows an offset of 3).

  • Asciidoctor supports up to 6 section levels (to cover all heading levels in HTML) whereas AsciiDoc stops at 5; note the 6 section level is only available using the single-line section title syntax.

  • Asciidoctor enforces symmetric block delimiters (the length of start and end delimiters for a block must match!).

  • Asciidoctor is nice about using a section title syntax inside a delimited block by simply ignoring it (AsciiDoc issues warnings).

  • Asciidoctor skips over line comments in tables, whereas AsciiDoc doesn’t.

  • Asciidoctor only recognizes the single character notation for column and cell formatting (e.g., a but not asciidoc).

  • Asciidoctor supports markdown-style blockquotes as well as a shorthand for a blockquote paragraph.

  • Asciidoctor supports markdown-style headings (section titles).

Differences in Attributes and Attribute Lists

  • Asciidoctor adds the type attribute on ordered lists to provide hint for numbering style when stylesheet is absent (such as in embedded mode).

  • Asciidoctor recognizes opts as an alias for the options attribute.

  • Asciidoctor introduces the hardbreaks attribute, which inserts a line break character after each line of wrapped text.

  • Asciidoctor parses attributes in link macros if an equal sign is found after a comma.

  • Asciidoctor >= 1.5.7 allows attribute names to contain any word character as defined by Unicode. AsciiDoc Python requires attribute names to be Basic Latin.

  • Asciidoctor introduces the idseparator attribute to customize the separator used in generated section ids (AsciiDoc hardcodes _).

  • Asciidoctor does not require commas between attributes with quoted values in a block attribute list.

    Example 2. No commas between attributes syntax.
    ["horizontal" role="green"]
property 1:: does stuff
property 2:: does different stuff

    If this possible extension was disabled, possible results would be:

    • Ignore the complete attribute list and emit a warning.

    • Accept and process as an attribute the text until the first space, ignore the rest and emit a warning.

  • The Admonition block caption can be overridden in Asciidoctor using the caption block attribute.

  • In Asciidoctor, a horizontal ruler can have attributes.

  • Asciidoctor can set the extension for icons using the icontype attribute (AsciiDoc defaults to .png).

  • Asciidoctor has shorthand syntax for attaching id, role, style and options to blocks: https://asciidoctor.org/docs/user-manual/#new-syntax.

  • Find other attributes deleted and deprecated in Asciidoctor here: https://asciidoctor.org/docs/user-manual/#migrate-deprecated.

Differences in Other Elements

  • Asciidoctor supports partial includes.

  • Asciidoctor allows multiple authors to be defined, separated by semicolon.

Asciidoctor Extensions

Asciidoctor Inline Extensions

Formula and Equation Inline Content

When the stem attribute is set in the document header, Asciidoctor recognizes:

Example 3. Inline equation syntax.
stem:[sqrt(4) = 2]

Water (stem:[H_2O]) is a critical component.

AsciiDoc Python has different syntax for mathematical formulas an LaTeX integration: https://asciidoctor.org/docs/user-manual/#mathematical-expressions.

Asciidoctor’s UI macros

When the experimental attribute is set in the document header, Asciidoctor recognizes:

  • A macro for creating keyboard shortcuts using the syntax kbd:[key(+key)*.]

    Example 4. Keyboard macro syntax.
    Use kbd:[F11] to Toggle fullscreen.

    Result: F11

    If this extension was disabled, the result for the above example would be the verbatim string kbd:[F11], and possibly a warning suggesting activating the extension.

  • A similar menu macro for menu selections.

    Example 5. Menu macro syntax.
    To save the file, select menu:File[Save].

  • A similar btn macro for UI buttons.

    Example 6. UI button macro syntax.
    Press the btn:[OK] button when you are finished.

Inline Icons

Example 7. Inline icon syntax.
= Document Title
:icons: font

icon:tags[role="blue"] ruby, asciidoctor

Callout Targets

Asciidoctor Block Extensions

Formula and Equation Block Content

When the stem attribute is set in the document header, Asciidoctor recognizes:

Example 8. Equation block syntax.
[stem]
++++
sqrt(4) = 2
++++

Callout Annotations

Example 9. Callout annotation syntax.
[source,ruby]
----
require 'sinatra' <1>

get '/hi' do <2> <3>
  "Hello World!"
end
----
<1> Library import
<2> URL mapping
<3> Response block

Asciidoctor Diagram

Anatomy of a diagram
[diagram-type, generated-file-name, generated-image-format] // (1) (2) (3)
.... // (4)
Diagram in appropriate syntax
....

  1. The first positional attribute in the attribute list specifies the diagram that is being used.

  2. The second, optional positional attribute assigns a file name (i.e. target) to the generated diagram. If a target is not specified an auto-generated name will be used.

  3. The third, optional positional attribute specifies the image format to create, specified as a three character file extension.

  4. Place the attribute list directly on top of the delimited literal block (....). You can also use an open block as an alternative (--).

Example 10. Asciidoctor Diagram block syntax with PlantUML diagram.
[plantuml, diagram-classes, png] // (1) (2) (3)
....
class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock

BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
....

  1. The diagram is written in PlantUML so the first positional attribute is assigned the plantuml diagram type.

  2. The name of the generated diagram file (target) is written in the second positional attribute.

  3. The output format is entered in the third positional attribute.

Extensions Derived From AsciiDoc Recommended Practices

Some Asciidoctor features are valid syntax but not recommended practice, nonetheless. It would be useful to offer the following possibilities to the user:

  • Disable this syntax.

  • Allow the syntax but emit a warning when detected.

Other Possible Extensions

Fluent Integration

Fluent is a localization system for natural-sounding translations, supported by Mozilla.

It would be nice to be able to write parameterized text that, relying on certain AsciiDoc attributes (maybe marked syntactically), and using Fluent selectors, embeds the localization logic in pure AsciiDoc.

Example 13. Fluent syntax for parameterized localized text.
{$userName} {$photoCount ->
        [one] added a new photo
       *[other] added {$photoCount} new photos
} to {$userGender ->
        [male] his stream
        [female] her stream
       *[other] their stream
}.

Fluent has functions for formatting dates and numbers and would be also useful to call them within AsciiDoc.

Ideas Borrowed From Org Mode

  • Org Mode timestamps and time ranges.

  • Org mode syntax for section titles, including:

  • Org Mode radio tagets. See https://orgmode.org/org.html#Radio-Targets. Convert any text in an automatic internal reference. Syntax: <<<My target>>>.

  • Org mode section properties as Asciidoc Attributes. The idea is that attribute definitions in consecutive lines from de section title would be considered properties attached to the section, maybe using a special syntax marker for the attribute name or the attribute value.

  • Spreadsheed formulas in tables.

Ideas Borrowed From (La)TeX

Ideas Borrowed From DocBook

DocBook has a long list of labels to attach meaning to document elements: https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/111.

Other

  • Idea taken from a comment in the proposal for the AsciiDoc Language WG:

    Instead of relying on styling for things like:

      Pass an [.type]#std::string# object to the [.func]#setName# function.

    Have a specific special syntax, like:

      Pass an [:type]#std::string# object to the [:function]#setName# function.

  • Idea taken from a chanel in the Write the Docs Slack space:

    Is there a way to stop Asciidoc from substituting “...” for the single ellipsis character (&#8230;)?We never want it to make this substitution.

    There is a way: backslash escaping. But we could make a customization option to decide what substitutions are applied.

⚠️ **GitHub.com Fallback** ⚠️