In a couple of issues now, we've run into an impass because it's unclear if we still need to include the output of code samples in manual pages. There is the new in-page runner, which is guaranteed to give "correct" results (or error if it's showing a feature that is incompatible).
I'd like to see us formally and explicitly decide on a policy here.
And I will start by proposing that in most cases, we DO NOT need to include manually-created output, as the in-page runner is superior and takes less work for doc writers. The only exception is where the runner doesn't support the code being shown for whatever reason. (Like, it requires a file system, or some non-loaded extension, etc.) In those cases, the traditional approach with a manual output block still makes sense. But that's a minority case now.
In a couple of issues now, we've run into an impass because it's unclear if we still need to include the output of code samples in manual pages. There is the new in-page runner, which is guaranteed to give "correct" results (or error if it's showing a feature that is incompatible).
I'd like to see us formally and explicitly decide on a policy here.
And I will start by proposing that in most cases, we DO NOT need to include manually-created output, as the in-page runner is superior and takes less work for doc writers. The only exception is where the runner doesn't support the code being shown for whatever reason. (Like, it requires a file system, or some non-loaded extension, etc.) In those cases, the traditional approach with a manual output block still makes sense. But that's a minority case now.
My first thought on this was: what about offline docs? Chunked and single page HTML downloads on php.net, epub, (man pages still build when I tried recently, tho I haven't checked the content) (and pdf / chm if anyone gets them working again)
My follow-up thought was: Could PHD always generate the static version of the output and append it to the docs?
(I guess there'd be some attribute to attach to define whether or not output is generated, similar to the controls for WASM runnable examples)
(Might want to store the output in separate files so they can be cached to avoid running every single example every time the manual is built)
On 10 November 2025 19:57:08 GMT, Larry Garfield <larry@garfieldtech.com> wrote:
In a couple of issues now, we've run into an impass because it's unclear if we still need to include the output of code samples in manual pages. There is the new in-page runner, which is guaranteed to give "correct" results (or error if it's showing a feature that is incompatible).
I'd like to see us formally and explicitly decide on a policy here.
And I will start by proposing that in most cases, we DO NOT need to include manually-created output, as the in-page runner is superior and takes less work for doc writers. The only exception is where the runner doesn't support the code being shown for whatever reason. (Like, it requires a file system, or some non-loaded extension, etc.) In those cases, the traditional approach with a manual output block still makes sense. But that's a minority case now.
I think we should still include them.. Mostly because the website isn't the only place were the content ends up. And also not everyone or every device can play the Wasm runner.
And the wasm runner does support the file system. And we can even pre-seed it. It's how we do the XML examples. You can also just write to it, and then read it again.
In a couple of issues now, we've run into an impass because it's unclear if we still need to include the output of code samples in manual pages. There is the new in-page runner, which is guaranteed to give "correct" results (or error if it's showing a feature that is incompatible).
I'd like to see us formally and explicitly decide on a policy here.
And I will start by proposing that in most cases, we DO NOT need to include manually-created output, as the in-page runner is superior and takes less work for doc writers. The only exception is where the runner doesn't support the code being shown for whatever reason. (Like, it requires a file system, or some non-loaded extension, etc.) In those cases, the traditional approach with a manual output block still makes sense. But that's a minority case now.
My first thought on this was: what about offline docs? Chunked and
single page HTML downloads on php.net, epub, (man pages still build when
I tried recently, tho I haven't checked the content) (and pdf / chm if
anyone gets them working again)
My follow-up thought was: Could PHD always generate the static version
of the output and append it to the docs?
(I guess there'd be some attribute to attach to define whether or not
output is generated, similar to the controls for WASM runnable examples)
(Might want to store the output in separate files so they can be cached
to avoid running every single example every time the manual is built)
AllenJB
Hm, I like the idea of pre-building it. I don't know how the current build works so I'm not sure how feasible that is, but that seems like it would be the ideal case.
Do we have stats (from the Foundation?) about how often the offline docs are even used? That would help determine how much effort is reasonable to put in here.
On 15 November 2025 14:10:51 GMT, Larry Garfield <larry@garfieldtech.com> wrote:
On Mon, Nov 10, 2025, at 2:31 PM, AllenJB wrote:
On 10/11/2025 19:57, Larry Garfield wrote:
In a couple of issues now, we've run into an impass because it's unclear if we still need to include the output of code samples in manual pages. There is the new in-page runner, which is guaranteed to give "correct" results (or error if it's showing a feature that is incompatible).
I'd like to see us formally and explicitly decide on a policy here.
And I will start by proposing that in most cases, we DO NOT need to include manually-created output, as the in-page runner is superior and takes less work for doc writers. The only exception is where the runner doesn't support the code being shown for whatever reason. (Like, it requires a file system, or some non-loaded extension, etc.) In those cases, the traditional approach with a manual output block still makes sense. But that's a minority case now.
My first thought on this was: what about offline docs? Chunked and
single page HTML downloads on php.net, epub, (man pages still build when
I tried recently, tho I haven't checked the content) (and pdf / chm if
anyone gets them working again)
My follow-up thought was: Could PHD always generate the static version
of the output and append it to the docs?
(I guess there'd be some attribute to attach to define whether or not
output is generated, similar to the controls for WASM runnable examples)
(Might want to store the output in separate files so they can be cached
to avoid running every single example every time the manual is built)
AllenJB
Hm, I like the idea of pre-building it. I don't know how the current build works so I'm not sure how feasible that is, but that seems like it would be the ideal case.
They're build on the rsync machine from where it's injected into the web-php check out.
Actually running the code on thatvserv and isn't something I would be comfortable with, as it's not sandboxed.
Id rather see a script run local by the documentation writer to inject the result into the local XML file.
Do we have stats (from the Foundation?) about how often the offline docs are even used? That would help determine how much effort is reasonable to put in here.
We can check downloads, but not usage.
Is it really that hard to just paste in the results when you're editing files? Also makes sure that the script works before committing.
I feel you're trying to make this more complicated than it currently is.