Clarify the use of a default value for the context variable in modules

[vikram-redhat]

As per the mod docs requirements, modules require a context be available to create proper anchor ids (although the context can be used for other decisions within modules as well). This value of the context is defined within the containing assembly and is then available to the module.

However, PV2 allows us to publish standalone modules. In those cases, the value of the context in standalone modules is undefined. This creates a problem, from an engineering point of view, but also a process point of view.

Having discussed this with the PV2 team, a suggestion is that the authors add a ifndef clause in all modules to define a default context, provided one hasn't already been defined by a containing assembly (https://projects.engineering.redhat.com/browse/CCS-4421).

I wanted to put this out here for further discussion:

• Should we do this?
• If yes, should we modify the templates to define a 'common' context used by all for cases where a module is going to get published independently?

I realize that these mod docs guidelines are independent from the target implementation (in this case, PV2) and that there will probably need to be a software solution to this as well.

[VladimirSlavik]

Just so the technical alternative is on the table: Attributes can be defined when invoking asciidoctor: asciidoctor --attribute context=standalone (...) some-module-file.adoc (...) and that's it. No need to add anything to templates, you get the "default" context value of standalone before the file is interpreted. In (b)ccutil, the authors of the tool can do the same: Add a context value before they convert the document using asciidoctor api. The principle is the same. A quick glance at the api docs suggests this should be possible.

That could free writers from yet more programming inside the documents. However, it also moves control of the default context to ccutil or Pantheon. That is a different consideration.

[vikram-redhat]

@VladimirSlavik - correct. Somehow, we need to provide a default value for the context variable, otherwise independently published modules won't have a value for it, and that could lead to unknown problems down the line.

[sterobin]

We discussed this issue in the FCC board and I had a phone call with @vikram-redhat to walk through some considerations around this.

TLDR version:

We've confirmed that this doesn't actually seem to be a problem with Pv2 today, and even if it were, we agreed that it still is best to not define explicit module-level context value. Instead, in edge cases where module-level context values are needed, it should be the implementation's job to account for that, whether through build methods like @VladimirSlavik mentions, through tooling ID definitions like in Pv2 at Red Hat or another tool among community FCC users, etc. Therefore closing this issue here.

Detailed review of discussion points and decisions:

• This concern is a valid one, but doesn't seem to actually be an issue with Pv2 today. A possible reason is that the tooling already translates anchor ID + context ID for both assemblies and modules to a string of letters and numbers as the unique published ID for all published artifacts. For example, see this Getting started assembly and also this Creating a service account module within it. Note the string at the end of the URL in each case, which replaces the anchor-ID_context-ID in both. Also see this standalone module preview of the same Creating a service account module, and note that the module is rendered without any issue even though it uses the standard undefined context variable in the source. Again note the string ID at the end of that URL, which identifies that module regardless of whether there is a default context ID defined or just the variable.
• That said, if this does pose a problem later, we agree that it should be left to the implementation (Pv2) to ensure that unique identification for standalone modules is achieved. FCC is a community project and should avoid being over burdened by tooling specific to Red Hat. But again, this seems to already be a non issue today.
• Furthermore, from even a community perspective (beyond Pv2), we also agree that regardless of who picks up the FCC initiative out there, it still should be the implementation's job to define the context ID for individual modules in those edge cases when individual modules need to be published, which again, in a community-based vanilla ascii world, would be quite rare. Also think about code development, where variables are often defined centrally in pom.xml or wherever, not in the actual code files themselves. So this approach follows suit.
• Therefore, we've agreed to close this issue and leave it either as something that's no longer a concern, or something to be taken up by the implementation/tooling (whether Pv2 or Jupiter) if it ever poses a problem.