Re: WASM examples in the manual

On Wed, Feb 12, 2025, at 12:33 PM, André L F S Bacci wrote:

>> Now my question is, should we specifically mark examples (using
>> <programlisting role="php" annotations="interactive">) or rather mark
>> them as not runnable (think <programlisting role="php"
>> annotations="no-wasm">. I am thinking rather the former than the latter,
>> as there will be so many that won't run (due to missing extensions,
>> mostly).
>
> Marking only as annotations="no-wasm", both for slow ones and
> extension related ones is the way to go.
>
> But these marikings would be placed only in generated `manual.xml`
> files, specifically `doc-base/temp/manual.xml`, and not in individual
> source files. This will avoid generating cascading changes on all
> translations, and will keep this information, that is specific to WASM
> runner version/compilation as an PhD detail, mostly unrelated to what
> version is documented in manual sources.

I would strongly recommend at least allowing the value to be specified in the original source, even if defaults are provided in a separate file to ease the job for translators on existing blocks.  Going forward, it makes far more sense to let the page author just specify that flag on the code block itself, regardless of whether it's opt-in or opt-out.  The only reason to separate it is to minimize jitter for translators, which is fine, but a backward-looking requirement.  New pages shouldn't need to deal with that.

--Larry Garfield