include-source attribute

[Rob Beezer]

Likely just for Andrew. While working on PR #2861, I've hit the @include-source
attribute. On #datafile, #program, and #exercise.

It seems to trace to the "view source" stylesheet, for making our "annotated"
samples for the website. But it doesn't appear to be doing much. Maybe I am
missing something. But if that is its only purpose, it does not belong in
authored source, I think.

Any illumination would be appreciated. Thanks.

Rob

[Rob Beezer]

Partially answering my own question after further tracing.

This puts annotations on selected elements/blocks no matter what.

I can't recall the motivation for that. The sample article and sample book are
being built as *fully* annotated versions already.

Rob

[Andrew Scholer]

That got added back in https://github.com/PreTeXtBook/pretext/pull/2298

Yes it is very meta... only useful if you are writing about PreTeXt and trying to show exactly the source you used in that document. It was added to satisfy Brad's request for easy access to readable sources next to Runestone examples. 

Most of that discussion happened in breakout, but I believe his objection to the fully annotated versions was that they destroy whitespace in embeded code listings. Compare the whitespace for programs in these two:

https://pretextbook.org/examples/sample-book/annotated/activecode.html

https://runestone.academy/ns/books/published/PTXSB/activecode.html

Especially for something like Python, the top version ends up pretty useless as a "drop and go" test.

I don't remember exactly why we avoided improving the whitespace for all annotations, but I'm pretty sure it had to do with the string processing routines. I don't remember if it was deemed impossible or just impractical.

Andrew

--
You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAxNy5iZWV6ZXI.1779127748%40pnsh.

[Rob Beezer]

> I don't remember exactly why we avoided improving the whitespace for all
annotations

Well, let's revisit that. I don't think the current setup really belongs (hit
this while working on the schema).

Maybe it is the processing we do *before* making the annotated versions to set
line-breaks, etc, via David Farmer's Python tool?

Thanks for the background.

Rob

On 5/18/26 11:55, Andrew Scholer wrote:
> That got added back in https://github.com/PreTeXtBook/pretext/pull/2298
> <https://github.com/PreTeXtBook/pretext/pull/2298>
>
> Yes it is very meta... only useful if you are writing about PreTeXt and trying
> to show exactly the source you used in that document. It was added to satisfy
> Brad's request for easy access to readable sources next to Runestone examples.
>
> Most of that discussion happened in breakout, but I believe his objection to the
> fully annotated versions was that they destroy whitespace in embeded code
> listings. Compare the whitespace for programs in these two:
> https://pretextbook.org/examples/sample-book/annotated/activecode.html <https://

> pretextbook.org/examples/sample-book/annotated/activecode.html>
> https://runestone.academy/ns/books/published/PTXSB/activecode.html <https://
> runestone.academy/ns/books/published/PTXSB/activecode.html>

> email to pretext-dev...@googlegroups.com <mailto:pretext-
> dev%2Bunsu...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/

> MTAwMDAxNy5iZWV6ZXI.1779127748%40pnsh <https://groups.google.com/d/msgid/
> pretext-dev/MTAwMDAxNy5iZWV6ZXI.1779127748%40pnsh>.

>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email

> to pretext-dev...@googlegroups.com <mailto:pretext-
> dev+uns...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/

> CACm44N8_m9ekm%3D4t76jWBFvBfApMqGcvp0D09n%2Bd%2BVZfdYNb0w%40mail.gmail.com
> <https://groups.google.com/d/msgid/pretext-dev/
> CACm44N8_m9ekm%3D4t76jWBFvBfApMqGcvp0D09n%2Bd%2BVZfdYNb0w%40mail.gmail.com?
> utm_medium=email&utm_source=footer>.

[Rob Beezer]

Some discussion on this at Drop-In with various parties, though seemingly always
while Andrew was in a breakout or had left. :-(

* Oscar has a JS formatter that we can switch to, he will work on making it
command line-friendly. That should solve the immediate problem of wayward
indentation when producing annotated versions for the website.

* Brad is doing the formatting for the Runestone copy of the sample book by
scraping the source for various objects from source hosted on GitHub. A nice hack.

* The @include-source attribute, as implemented today, trades on code meant
only to support the website. So that code should not be expected to be
univesally supportd for all authors and all projects.

* The necessity of having authors display PreTeXt source in their HTML output
is an open question. (Rather than providing documentation of *how* to author
PreTeXt.)

Rob

[Rob Beezer]

The annotated sample article and sample book are now in much better shape, as
the annotations come from a new formatter. In particular, the indentation of
the content of a #program is respected.

So I have deprecated the @include-source attribute. It was only ever in the
"dev" version of the schema, so I don't plan any announcements.

@Brad - you can unwind your scraping of source from GitHub. And if you want an
annotated version of "PTXSB" hosted on Runestone, I think you would have no
trouble integrating Oscar's formatter. The it is just a stringparam to flip.
And I'm happy to help.

Rob