= adoc-mode AsciiDoc Specification Compliance
:toc: left
:toclevels: 2

This document audits how well `adoc-mode` tracks the modern AsciiDoc
language as defined by the
https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang[Eclipse
AsciiDoc Language project] (the AsciiDoc Working Group spec and the
Asciidoctor documentation it is derived from).

`adoc-mode`'s syntax rules originate from the old Python `asciidoc.conf`,
so some constructs reflect AsciiDoc.py / legacy "compat-mode" behaviour
rather than the current language. This audit identifies that drift.

== Scope and method

`adoc-mode` is a font-lock and editing mode, not a parser or converter.
"Compliance" therefore means: does the mode *recognise and highlight*
the constructs the current spec defines, without highlighting syntax the
spec has dropped or redefined? Pure processing concerns (substitution
ordering, ToC generation, include resolution, docinfo, conversion) are
out of scope, except where they have a syntactic surface the editor
highlights (e.g. `include::`/`ifdef::` directives).

Findings are graded:

* *High* - the mode highlights something incorrectly per the current
  spec, or misses a common modern construct, in a way users will hit
  often.
* *Medium* - a real gap or drift, but in a less common construct.
* *Low* - cosmetic, rare, or deprecated-but-harmless.

== Summary of key findings

[cols="1,3,1",options="header"]
|===
| Area | Finding | Severity

| text
| [.line-through]#`+text+` / `++text++` are still highlighted as monospace
  (legacy AsciiDoc.py "compat-mode").# *FIXED* - they are now treated as
  inline passthroughs (normal text, formatting suppressed); the backtick is
  the only monospace delimiter.
| High

| text
| [.line-through]#Modern curved-quote syntax `+"`text`"+` / ``'`text`'`` is
  not recognised.# *FIXED* - recognised; delimiters de-emphasised, enclosed
  text normal (and the inner backticks are no longer mis-read as monospace).
| Medium

| text
| [.line-through]#The deprecated AsciiDoc.py curved-quote templates
  `` `text' `` and ``\`\`text''`` are still offered in the menu / tempo
  templates.# *FIXED* - replaced with the modern `+"`text`"+` / ``'`text`'``
  templates; the `+...+` templates are relabelled as passthroughs.
| Low

| lists
| Checklist items (`* [ ]`, `* [x]`, `* [*]`) are not recognised.
| Medium

| blocks / sections / attributes
| [.line-through]#The modern block-attribute *ID shorthand* `[#id]` is not
  recognised.# *FIXED* - `[#id]` is highlighted as an anchor and is
  navigable; the `.role`/`%opt` shorthands inside an arbitrary attribute
  list are still not individually faced.
| Medium

| text
| The literal-monospace enclosure `` `+text+` `` is not handled as a unit.
| Low

| blocks
| Collapsible blocks (`[%collapsible]`) have no dedicated handling.
| Low
|===

== Per-module audit

=== text (inline formatting)

[cols="2,2,3,1",options="header"]
|===
| Construct | Spec | adoc-mode | Severity

| Bold `*x*` / `**x**`
| Constrained + unconstrained
| Supported
| -

| Italic `_x_` / `__x__`
| Constrained + unconstrained
| Supported
| -

| Monospace `` `x` `` / ` ``x`` `
| Backtick, constrained + unconstrained
| Supported
| -

| Passthrough `+x+` / `++x++`
| Inline passthroughs (constrained/unconstrained), rendered as normal text
  with formatting suppressed; not monospace
| *Fixed* - treated as passthroughs (`adoc-kw-inline-passthrough`):
  delimiters de-emphasised, content left in the default face and reserved
  so inner formatting is not applied
| -

| Highlight `#x#` / `##x##`
| Marked text
| Supported
| -

| Superscript `^x^` / Subscript `~x~`
| Unconstrained
| Supported
| -

| Curved quotes `+"`x`"+` / ``'`x`'``
| Modern smart-quote syntax (backticks inside straight quotes)
| *Fixed* - delimiters de-emphasised, enclosed text normal
| -

| Legacy curved quotes `` `x' `` / ``\`\`x''``
| Deprecated in Asciidoctor
| Not fontified (good); the menu/tempo templates have been replaced by the
  modern curved-quote forms
| -

| Literal monospace `` `+x+` ``
| Backtick + plus enclosure (a passthrough shorthand)
| Outer/inner delimiters highlighted separately, not as one literal span
| Low

| Roles `[.role]#x#`, strike/underline/overline
| Built-in + custom roles
| Supported (`adoc-role-face-alist`)
| -
|===

=== blocks

[cols="2,3,1",options="header"]
|===
| Construct | adoc-mode | Severity

| Delimited blocks: example `====`, sidebar `****`, listing `----`,
  literal `....`, quote `____`, passthrough `++++`, open `--`, comment `////`
| Supported
| -

| Admonition block `[NOTE]` and paragraph `NOTE:`
| Supported (both styles)
| -

| Block title `.Title`
| Supported
| -

| Block anchor `[[id]]`
| Supported
| -

| Block ID shorthand `[#id]` / `[#id.role]`
| *Fixed* - highlighted as an anchor and navigable (see `block-id-shorthand`)
| -

| Hard line breaks (line ending in ` +`)
| Preserved when filling; `[%hardbreaks]` option not specially handled
| Low

| Collapsible `[%collapsible]`
| No dedicated handling (content still highlights)
| Low

| Discrete headings `[discrete]`
| Heading still highlights; the `[discrete]` style is a generic attr line
| Low
|===

=== lists

[cols="2,3,1",options="header"]
|===
| Construct | adoc-mode | Severity

| Unordered `*` / `-`, nested by repetition
| Supported
| -

| Ordered, explicit (`1.`, `a.`, `i)`) and implicit (`.`, `..`)
| Supported
| -

| Description lists `term::` / `;;` / `:::` / `::::`
| Supported
| -

| Q&A `term::` under `[qanda]`, glossary
| Supported
| -

| Callout list `<1>`
| Supported
| -

| Checklists `* [ ]` / `* [x]` / `* [*]`
| *Fixed* - the checkbox is highlighted with `adoc-checkbox-face`
  (`adoc-kw-checkbox`)
| -

| List continuation `+`
| Supported
| -
|===

=== sections

[cols="2,3,1",options="header"]
|===
| Construct | adoc-mode | Severity

| One-line titles `=` ... `======` (levels 0-5)
| Supported
| -

| Two-line (setext) titles
| Editing commands (promote/demote, imenu, navigation) understand them,
  but highlighting is *off by default* (`adoc-enable-two-line-title` is
  nil) - which matches their deprecated status
| -

| Auto-generated IDs, section refs `<<id>>`
| Refs supported; IDs are a processing concern
| -

| Custom section ID via `[#id]` shorthand
| Fixed (see blocks / attributes)
| -

| Discrete heading, special sections (appendix, bibliography, glossary)
| Styles are generic attribute lines; titles highlight normally
| Low
|===

=== macros

[cols="2,3,1",options="header"]
|===
| Construct | adoc-mode | Severity

| Cross references `<<id>>` / `xref:id[]`
| Supported
| -

| Link / URL macros, autolinks (bare URLs), mailto
| Supported
| -

| Image `image:` / `image::`, with attributes
| Supported (plus inline preview)
| -

| Footnotes `footnote:[]` / `footnoteref:[]`
| Supported (dedicated faces)
| -

| UI macros `kbd:[]`, `btn:[]`, `menu:[]`
| Supported
| -

| STEM `stem:[]`, `latexmath:[]`, `asciimath:[]`
| Supported
| -

| Passthrough macro `pass:[]`
| Supported
| -

| Icon macro `icon:name[]`
| *Fixed* - registered as an inline macro
| -
|===

=== tables

[cols="2,3,1",options="header"]
|===
| Construct | adoc-mode | Severity

| Table delimiter `|===`, cells `|`
| Supported
| -

| Cell / column specifiers (span, align, style)
| Supported (`adoc-re-cell-specifier`)
| -

| Alternative formats (CSV `,`, DSV `:`) via `format=`
| Verify - cell highlighting assumes the `|` PSV format
| Low
|===

=== attributes

[cols="2,3,1",options="header"]
|===
| Construct | adoc-mode | Severity

| Attribute entry `:name: value`, unset `:name!:`
| Supported (dedicated key/value faces)
| -

| Attribute reference `{name}`
| Supported (resolved in image paths too)
| -

| Element attribute list `[positional, name=value]`
| Supported
| -

| ID/role/option shorthand `[#id.role%opt]`
| Partial - a pure `[#id]` line highlights the id as an anchor and is
  navigable; the `.role` / `%opt` shorthands inside an arbitrary attribute
  list are still not individually faced
| Medium

| Counters `{counter:name}`, character-replacement refs
| Verify
| Low
|===

=== subs, pass, verbatim

[cols="2,3,1",options="header"]
|===
| Construct | adoc-mode | Severity

| Passthrough delimited block `++++`, macro `pass:[]`, triple-plus `+++`, `$$`
| Supported
| -

| Listing `----`, literal `....` blocks
| Supported
| -

| Source blocks `[source,lang]` with native fontification
| Supported
| -

| Callouts in verbatim blocks `<1>`
| Supported
| -
|===

=== Lower-priority / processing-only modules

These are largely conversion concerns with little or no editor surface:

* *directives* - `include::`, `ifdef::`/`ifndef::`/`endif::`, `ifeval::`
  are highlighted as preprocessor lines (supported).
* *toc* - generated output; no source syntax to highlight.
* *docinfo* - external files; out of scope.
* *stem* - the `[stem]` block and `stem:[]` macro surfaces are covered
  under blocks/macros.
* *document* - header (title, author, revision, attribute entries) is
  highlighted; most of this module is processing semantics.

== Recommended follow-ups (prioritised)

[NOTE]
====
Items are checked off as they are addressed. The legacy `compat-mode`
monospace behaviour was simply dropped rather than gated behind a
defcustom, since it is no longer part of the language Asciidoctor
implements.
====

. [x] *Stop highlighting `+text+` / `++text++` as monospace.* Done -
  reclassified as inline passthroughs (`adoc-kw-inline-passthrough`).
  Note: the menu / tempo templates still offer `+...+` / `++...++` under a
  "Monospaced" label; fold that into the template cleanup (item 5).
. [x] *Recognise checklist items* (`* [ ]`, `* [x]`, `* [*]`) with a
  dedicated face for the checkbox. Done - `adoc-kw-checkbox` /
  `adoc-checkbox-face`.
. [x] *Recognise the block-attribute ID shorthand* `[#id]`. Done -
  `[#id]` / `[#id.role%opt]` lines highlight the id as an anchor
  (`block-id-shorthand`) and `adoc-goto-ref-label` follows `[#id]` (and
  `[style#id]`) targets. Faceting `.role` / `%opt` inside arbitrary
  attribute lists is left as a smaller follow-up.
. [x] *Add modern curved-quote highlighting* `+"`text`"+` and ``'`text`'``.
  Done.
. [x] *Drop the deprecated `` `text' `` / ``\`\`text''`` templates* and
  relabel the `+...+` / `++...++` ones. Done - the curved-quote templates
  are replaced with the modern forms and the plus templates are relabelled
  as passthroughs.
. [x] *Add the `icon:name[]` inline macro* to the recognised macro set.
  Done.
. [ ] *Verify* CSV/DSV table formats, counters, and the literal-monospace
  `` `+text+` `` enclosure, and add handling where it is missing.
