Re: WASM examples in the manual

Hi,

On Tue, Feb 11, 2025 at 7:06 AM Derick Rethans <[email protected]> wrote:
> There are going to be a lot of them where having WASM enabled for them
> don't make a lot of sense. Especially for category "c". And the category
> "b" ones just sit there eat CPU cycles.

For code examples that run fast or fail fast, I think running them at
each configure.php would have no impact (see below). This leaves the
case of slow ones. Only these I think is necessary to preserve in a
"database" related file, say `wasm-slow.json`, git tracked and side by
side with the runner, to avoid unnecessary slow build times.

The runner, modeled as an stand alone step on configure.php (see, for
example, how script/file-entities.php can be run outside
configure.php), with a option to test all code examples and regenerate
`wasm-slow.json`, may be sufficient.

I'm also planning [1] to move all "PhD stuff" and otherwise
non-building or non-validating related code to run after validation,
and to put all file generations of PhD related files behind a --no-phd
option, so there is no impact for manual editors and translators.

> 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'm inclined to make this opt-in (by havin to add the 'annotations'
> attribute. What do you think?

On `doc-base/temp/manual.xml` generated file, yes. As it will need
changes both in configure.php and PhD, this would also help in movingo
all generated files into `doc-base/temp`, so the PHP manual building
truly becomes idempotent. See "Idempotent" and "Performance/tools" on
the link below.

Best regards,
André L F S Bacci

[1] https://github.com/php/doc-base/issues/199