Re: Omit code output going forward

On 15 November 2025 14:10:51 GMT, Larry Garfield <larry@garfieldtech=2Ecom>=
 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 uncle=
ar if we still need to include the output of code samples in manual pages=
=2E  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)=2E
>>>
>>> I'd like to see us formally and explicitly decide on a policy here=2E
>>>
>>> And I will start by proposing that in most cases, we DO NOT need to in=
clude manually-created output, as the in-page runner is superior and takes =
less work for doc writers=2E  The only exception is where the runner doesn'=
t support the code being shown for whatever reason=2E  (Like, it requires a=
 file system, or some non-loaded extension, etc=2E)  In those cases, the tr=
aditional approach with a manual output block still makes sense=2E  But tha=
t's a minority case now=2E
>>
>> My first thought on this was: what about offline docs? Chunked and=20
>> single page HTML downloads on php=2Enet, epub, (man pages still build w=
hen=20
>> I tried recently, tho I haven't checked the content) (and pdf / chm if=
=20
>> anyone gets them working again)
>>
>> My follow-up thought was: Could PHD always generate the static version=
=20
>> of the output and append it to the docs?
>> (I guess there'd be some attribute to attach to define whether or not=
=20
>> 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=
=20
>> to avoid running every single example every time the manual is built)
>>
>> AllenJB
>
>Hm, I like the idea of pre-building it=2E  I don't know how the current b=
uild works so I'm not sure how feasible that is, but that seems like it wou=
ld be the ideal case=2E

They're build on the rsync machine from where it's injected into the web-p=
hp check out=2E=20

Actually running the code on thatvserv and isn't something I would be comf=
ortable with, as it's not sandboxed=2E

Id rather see a script run local by the documentation writer to inject the=
 result into the local XML file=2E=20

>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=2E

We can check downloads, but not usage=2E=20

Is it really that hard to just paste in the results when you're editing fi=
les? Also makes sure that the script works before committing=2E=20

I feel you're trying to make this more complicated than it currently is=2E=
=20

cheers=20
Derick=20