Re: WASM examples in the manual

On 12 February 2025 21:38:12 GMT, Larry Garfield <[email protected]> wrote:
>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

Gina had a good idea on the foundation's slack, and that's likely the approach I'll be taking:

----
Gina Peter Banyard:
Then I would prefer having interactive=yes at a book level and then add some interactive=no at example levels. Changing 1000+ files is not really something I'm in favour of 

Derick Rethans: 
But yeah, doing it on book level, with overrides makes sense. I'll have a look (later this week
----

This also makes it easier for adding new extensions to run examples for, if we manage to (and decide to) enable more extensions in wasm.

cheers
Derick