Allow playbook to enable sourcemap option on AsciiDoc processor

The sourcemap option on the AsciiDoc processor (Asciidoctor) enables line and file tracking on source blocks. It's not enabled by default because it adds additional processing and object allocation to the build process. So enabling it is a decision left up to the user.

There are two use cases for wanting to enable this option. First, an Asciidoctor extension may rely on this information being set, and thus the extension author may request that the user enable this option when calling Asciidoctor. So we need to give the user the ability to do so. Enabling this setting can also make certain log messages more informative. For example, when enabled, the error message about an unresolved xref (see #403 (closed)) could be automatically enhanced to include the file and line number (tying into the existing logger adapter between Asciidoctor and Antora).

The option would be specified in the playbook as follows:

asciidoc:
  sourcemap: true

This should be mapped to the boolean CLI option --sourcemap. (or --asciidoc-sourcemap?)

Technically, it's already possible to enable this option using the following Asciidoctor extension:

module.exports = {
  register (registry) {
    registry.preprocessor(function () {
      this.process((doc) => {
        doc.sourcemap = true
      })
    })
  }
}

This extension then must be registered in the playbook as follows:

asciidoc:
  extensions:
  - ./enable-sourcemap.js

However, it's rather clear that being able to specify this using a key in the playbook is a much more pleasant experience for the user.

added [Domain] Backend [Type] Feature labels

assigned to @mojavelinux

changed milestone to %v3.0.x

mentioned in issue #403 (closed)

What's so exciting about this change is that, for the first time, we'll be able to report the file and line number of a broken xref. The line number will be the location where the block that contains the broken xref starts (so the first line of the paragraph, for instance). But that already gets you looking at the right screen.

mentioned in merge request !665 (merged)

@graphitefriction The MR is ready, but we can't merge until we decide whether the CLI option should be named --asciidoc-sourcemap or --sourcemap. The precedence is that the attributes key is mapped to --attribute instead of --asciidoc-attribute, but that could change in the future.

I prefer --asciidoc-sourcemap.

My reasoning goes like this:

• Assumption 1: Playbook keys are developmentally defined within the context of the playbook first and foremost. We've got lots of keys that are grouped under top- or mid-level keys. That is, they're sub-keys and the keys they're nested under provide fundamentally important context.
• Assumption 2: Many playbook keys can be configured from the CLI using a command line option as a way of setting or overriding a playbook key without updating the playbook when in a local environment, testing, etc. Command line options aren't nested, so only using a sub-key's name as the option name often decreases clarity and, in some cases, causes collisions with other Antora, extension, dependency, or system options. This leads to my next, roughly proposed assumptions:
  • Assumption 2.a: The name of the corresponding command line option should provide enough identification that it definitively maps by its name to its most unique mid-or top-level key and sub-key that it shadows.
  • Assumption 2.b: The name should contain enough unique context (often provided by that mid- or top-level key name) that it doesn't collide with common integration, extension, or dependency options that may be used in the same command line statement.
  • Assumption 2.c: A group of options that shadow sub-keys that belong to the same mid-level key group should use the same naming pattern to ease naming and make the mental model for end users consistent.
  • Assumption 2.d: Exceptions to specifying the mid- or top-level context in the option's name include:
    • The option's name is incredibly unique (there'd never, in your wildest dreams (think quantum computing, your favorite futuristic sci-fi scenario) ever, ever be a collision)
    • The option's name would be exhaustively long.
  • Assumption 2.e: In most cases, using the mid-level key's name in an option's name should provide enough unique context. If it doesn't, we can evaluate adding the top-level key name in concert with the mid-level, or dropping the mid-level key name and only using the top-level name. These would be rare occurrences.

In practice, what do these assumptions look like? Here are some examples:

Log playbook keys and matching command line options

runtime:
  log:
   level: debug --> --log-level=debug
   failure_level: warn --> --log-failure-level=warn
   format: json --> --log-format=json

Wait, but we don't really follow these patterns except in the case of the mid-level log group...

You're right! (and yes, I'm having a conversation with myself here and playing both characters )

This lack of a pattern/naming guidelines has backed us into a corner and is highly likely to end with us having to do the deprecation-and-remove doe-see-doe. An existing conundrum is --url. Is that site URL? sources URL? some future supplemental or other category URL? ui URL (which happens to be --ui-bundle-url, an option named using both its top-level and mid-level keys context)?

Here's a (hypothetical) example of an option where Assumptions could have been applied and 2.e was invoked:

--html-url-extension-style

This option is a little lengthy and differs from the name of the playbook key, so if past me could have had a conversation with future me, I would have considered:

1. Is --urls-html-extension-style exhaustively long?
2. Does --urls-html-extension-style collide with another option?
3. Is --html-extension-style incredibly unique and unlikely to ever get grouped under a mid-level key while being removed from directly applying to the top-level key group? If yes, could it stand without further context and the top-level key name (urls) be dropped?
4. Does --urls-html-extension-style and --html-extension-style collide with other options? (and in that case, its name can break the recommended naming pattern...)

Obviously, this whole naming pattern discussion needs to be moved to a new issue and probably result in an ADR.

As for --attributes that adds an extra level to consider since it accepts multiple key-value pairs where each key-value pair has to be preceded by --attributes (unless we changed this...) so --asciidoc-attributes seems exhausting if many key-value pairs are being assigned from the CLI. I'd ask is --attributes unique enough (it would only and always apply globally to the entire pipeline (extensions/extended Antora components/docs components won't ever specify a subset of attributes from the playbook (and therefore the CLI), other common use cases/integrations/systems don't have "attributes" that could collide in the same statement)). If those factors were true, then --attributes is probably fine.

I agree with your reasoning for using --asciidoc-sourcemap. There's a lot of functionality in Antora and, without the prefix, it can be unclear what sourcemap we're actually referring to (even if we know what we mean). For example, we could imagine a user might think that this enables the sourcemap for UI assets, which is not the case. So context is very important.

In general, I like the "unique enough context". We don't need be so explicit that it becomes tedious, like --urls-redirect-facility. The redirect facility can only apply to URLs, so that much we can assume. The --html-url-extension-style is a tricky one since it uses the category key (-ish), but not in the normal way. That's just a weird one. And I think we will have to be flexible in some cases.

This whole naming pattern discussion needs to be moved to a new issue and probably result in an ADR.

I also think there is a strong case for changing (with a backwards compatible shim) --attribute to --asciidoc-attribute. In the context of Antora, it's not so clear what attribute refers to (even if we know what it means). We choose --attribute to try to align with the asciidoctor CLI, but I think we've grown beyond that point. Something to consider, though, is that we can still map a long form attribute to a short one. This would be where supporting -a would make sense (e.g., -a product-name=ACME). We only get to use each short option once, but I think this is an option that's used so often, it deserves that promotion. But we can relocate this debate to the ADR, where we can weight the benefits and drawbacks of such a change.

For now, --asciidoc-sourcemap it is!

closed with commit b036f073

mentioned in commit 21e9da5f

@graphitefriction It's important for users to understand that they must enable this option to get the line number and guarantee the correct file for xref errors. If they don't expect xref errors (perhaps because they have already checked for them), there is no need for this option (for that use case).

added [Version] 3.0.0 label

mentioned in commit b036f073