[CHANGE] Visibility of the "commentary" element

[Rob Beezer]

The "commentary" element is useful and is not changing. How you control its
visibility *is* changing, and it is...complicated. So if you use the
"commentary" element, please read carefully.

We envisioned this element as something you might use to provide annotations
inside a textbook, to help create an "Instructor's Version". So it is not
visible out-of-the-box and you make it visible with a string parameter (named
"commentary"). It now makes much more sense to create an "Instructors Version"
with our version support, which out-of-the-box includes all content.

So switching default behavior from invisible to visible seems impossible to do
gracefully. Sorry. Worse, we do not want authors and publishers to suddenly
get "instructor only" content in their output without lots of warnings.

Short version: put your "commentary" into a "component" (I named the one for the
sample article "instructor"). Then use a publisher file to include (or not)
this component. If you hide the component, it will go away early in the build
process. If you make the component visible, you *still need to set the string
parameter to "yes"*. No code is being removed now, or for another year.

Plan:

Now: you will get a warning about component-less "commentary". It'll go away
once you change your source.

2024-03-13, or later: string parameter will be *removed* and use will create a
warning (or a fatal error?). And, as protection, component-less "commentary"
will create a fatal error.

Sometime in the future: fatal errors will be softened, and perhaps evetually
removed.

Please post questions or concerns on pretext-support or pretext-dev as
appropriate. Sorry this one is so messy.

Rob

Section 28.2: Versions
https://pretextbook.org/doc/guide/html/publisher-versions.html

[Rob Beezer]

If you use the "commentary" element, read on, otherwise it is safe to skip this.

Short version:

The "commentary" element is now a very simple container, whose only purpose is
to carry a @component attribute. This had been forecast to some extent a year
ago, and is basically the removal of a few features (such as a "commentary"
allowing a "title", and opportunities for LaTeX styling).


Long version:

* The string parameter, also named commentary, is now deprecated. That is how
this started a year ago. You will get warnings.

* As forecast, every "commentary" *must* have a @component attribute,
suggesting use with version support. Schema now reflects this change.

* We very much do not like fatal errors. You should usually get some output,
perhaps with defaults you did not expect. But not a quit. Since "commentary"
might include material you might not want an audience to see, a "commentary"
with @component is now a fatal error. There has been a year-long period
suggesting moving your source in this direction.


Future Plans:

As I worked this up, I could not find a use for "commentary" that could not be
easily replaced by a straight-up use of version support. So I will forecast a
complete removal of "commentary" in another years' time.

I am sure "commentary" can easily produce bugs in place where the code "looks up
the tree". And to really get it right in the schema would mean an even more
pervasive insertion as an option in many, many patterns.

[Rob Beezer]

If your source does not have a #commentary element, you can ignore this.

Short version: the #commentary element is now deprecated, since version support
provides all the same features in a much more robust way. Get rid of your
#commentary element and transition to using @component attributes.

Section 27.2: Versions
https://pretextbook.org/doc/guide/html/publisher-versions.html

Long version:

* We've been on a long quest to get rid of this, since it includes/excludes
content and we did not want to surprise any authors.

* There has been a series of warning messages (and posts here). We have lately
suggested using versions on a #commentary as a transitional step.

* #commentary is gone from the schema.

* A #commentary without a @component will be a fatal error. This was suppose
to be the case a year ago, but the implemention (and testing) was flawed.

* A #commentary with a @component will generate a deprecation message, but will
continue to function just as it always had. The latest set of changes do not
change output in any way, so this is a no-rush change.

* You can get a series of semi-confusing error messages. Too bad! ;-) Its
enough to try to do this gracefully in a series of announced steps. Just get
rid of your #commentary and all will be well. ;-)

Rob