Design Discussion: Calendar and date-aware authoring for course materials

[Oscar Levin]

Hi everyone,

TL;DR: Wouldn't it be great if you could set up a few dates in a single place in your source materials, and have that impact actual dates in the output and change what components are included, based on the build date?  The rest of this goes into a first possible implementation, with a request for feedback both on the technical implementation and author interface concerns.

Two related use cases: author adds <p> The first exam will be on <date at="exam1-date"/>.</p>.  Each semester, inside a <calendar> element (living inside either <docinfo> or <publication>) they add <event xml:id="exam1-date" at="week3.fri"/>.  Their calendar also has attributes: 

                               start="2026-08-24" end="2026-12-11" meets="MTWF"

so when building, pretext computes the correct date of the first exam and the output is correct (some formatting allowed for date display format).

A second use: after the first exam, the instructor wants to release exam solutions.  So they put a component="ex1-sol" on the relevant divisions or blocks.  In their calendar, they add <release component="ex1-sol" from="exam1-date+2d"/> which means that pretext versioning will include those components whenever the source is built on a date that is at least 2 days after exam1.

Some questions for discussion about authoring:

1. We can do dates as week6.wed (or w6.w) or week6.d2 (for the second class meeting of week 6 or class17 for the 17th day of class.  What happens if there is a holiday on the monday of week 6?

2.  What would be useful if you switch from a MWF to TuTh schedule (in which case, week6.d3 is an...error?).  What seems natural here?

Implementation questions:

1. I think the big question is what lives in the publication file and what lives in docinfo.  It could be split to set the calendar of events in docinfo and the calendar settings in publication.

2. Does it make sense to reuse components or to re-implement a component-like system?

3. Related to both of these: assembly has an early version resolution pass.  If the calendar of dates is in docinfo, we cannot allow that to have a component itself (we cannot resolve components in order to learn how to resolve components).  

What else is worth thinking about right now? 

[Rob Beezer]

OK, DR;, but I will soon. ;-)

I've been thinking my assistant would do a nice job internationalizing dates. 7
days of teh week, 12 names of months. I think we already have some date
formats, like 2026-08-02 v. Sunday, August 2.

But I was not really sure what the point would have been, so had not yet
bothered. Maybe bilingual course calendars for the French Canadians? Could
this augment what I DR;?

Rob

> --
> 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/
> f93d3a23-0ed9-4101-8782-5c4806182916n%40googlegroups.com <https://
> groups.google.com/d/msgid/pretext-dev/
> f93d3a23-0ed9-4101-8782-5c4806182916n%40googlegroups.com?
> utm_medium=email&utm_source=footer>.

[Oscar Levin]

Yes, we would want localizations for calendar words.  But that's very doable, as you say.

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/MTAwMDAyYUFnc2UxLU8.1785719066%40pnsh.

[Joseph DiMuro]

Course calendars are the bane of my existence. ;-)

Holidays can be annoying. Some (like Good Friday) jump around the calendar from year to year. So I think I would want the calendar attributes to include a holiday attribute:

start="2026-08-24" end="2026-12-11" meets="MTWF" holidays="2026-09-07,2026-11-25,2026-11-27"

With that in place, I would prefer your idea to refer to class dates as class17 for the 17th day of class. It might require some careful counting, but it would mean that the class dates could more easily slide around those moving holidays.

I like your "exam1-date+2d" idea. I hope it would be not just for release components, but also something that could be displayed in the text, like <p>The answers to the exam study guide will be posted on <date at="exam1-date+-5d"/></p>. It might also be good to allow something like "exam1-date+2c", to refer to the date two class sessions later (skipping holidays if any).

Going from MWF to TuTh: that's a total overhaul of a class. I think the instructor will be doing a ton of work regardless of what PreTeXt can do, so I wouldn't worry about accommodating that one.

One final thought: I know PreTeXt-Plus lets you write in the style of either PreTeXt, LaTeX, or Markdown. Does it let you use Markdown-style pipe tables? If not, that might be a good thing to add if possible; some people might like writing their course calendars that way. I'm doing something similar myself right now: putting my course calendar into an emacs org-mode table, and then using a keyboard macro to translate it to a PreTeXt table. Moving things around in an org-mode table is so satisfying. :-)

[Rob Beezer]

(Got my threads confused - now in the right place.)

As promised.

I taught linear algebra so many times, and became very familiar with the
textbook I used, so I would recycle course calendars.

It got to were I had enogh that if MLK Day was on Jan 17, I could find an old
calendar that required minimal effort to adapt. Unless it was a leap year.

Fall v. Spring - we had different numbers of total days.

We switched from MTuThF to MTuWF at one point. I agree with Joseph, maybe you
just need to start over - especially if go from three-days-a-week to
two-days-a-week.

Holidays - radically different Fall v. Spring ("Fall Break" for two days +
Thanksgiving v. "Spring Break" week).

Implementation. Version support is almost trivial code and has a wide variety
of applications. But even I get confused sometimes using it in novel ways. I
think things like #release should be their own deal. Maybe we do a pass in
"-assembly" *right after* we do versions and maybe we have smiliar code. that'd
be fine.

> big question is what lives in the publication file and what lives in docinfo

Funny you should ask. We now have:

Section 49.2: Choosing a Home for Configuration
https://pretextbook.org/doc/guide/html/developer-configuration-homes.html#developer-configuration-homes

I think that says the source has

<section release="exam5+3d>
<title>Solutions to Exam 5, Eigenvalues</title>
lah...blah..\lambda=2...blah

and the publisher file has

@start="2026-09-04"

Author's words, \lambda=2, are unchanged, but only invisible/visible as
influenced by the publisher file start value (and a system clock).

Maybe what is really new - the document produced - with no edits at all - will
be different on one day versus another day. But it should always reflect the
author's words in the way they meant them *relative* to other days (via a time
delta, not absolute time?). Or something like that.

task warrior is a CLI to-do list mangager, with flexible date specifications -
might be food for thought:

"Specifying Dates and Frequencies"

at https://linux.die.net/man/1/task

pcal is a CLI/text-file calendar tool

Less obvious where to look, see around line 227 for instance:

https://github.com/mmayer/pcal/blob/master/examples/pcal-cfg.txt

Rob