Announce math release

[alerque]

Bringing native math support, the next SILE release is likely to get a little more publicity than usual. As such it might be nice to prepare for it just a little more than usual.

1. [x] An introductory paragraph for release announcement on the blog that tells a little bit about the approach for folks that have been sticking to TeX just for the math.
2. [x] An new example or two to put up as an image showcasing something it can do.

@OlivierNicole Are either of these (or anything else that you suggest should go into the release) be something you can help with?

[OlivierNicole]

I can try to write an showcase example with some smart-looking math in it.

As for the approach, I think that what the package documentation says summarizes the overall philosophy. Maybe one could also say why it is a good idea to write documents in a description language such as XML and write processing routines in an actual programming language such as Lua, rather than having it all done by a Turing-complete lexer, as is TeX's way. But that pertains to SILE in its entirety, not just math.

[OlivierNicole]

I also think we should try to avoid giving people very high expectations. What the math package can do is ridiculous compared to TeX math capabilities. Even simple things like setting font color inside math, or putting ordinary text inside a big equation, are not implemented yet. I personally see it as a starting point, that might motivate some people to put in the work of implementing missing features.

[ctrlcctrlv]

(This is a reply to https://github.com/sile-typesetter/sile/pull/1103#issuecomment-916420904.)

I agree with @OlivierNicole.

Part of the difficulty is that SILE has already self-selected users who don't need math support because it doesn't have any. It is very unlikely that I will ever be using math.lua, for example. That's the main positive thing about the next release: it will expand SILE's audience to more TeX users.

[alerque]

@Omikhleia A couple of your contributions are going to land in the same release as the math debut. How would you like to be credited? I typically use full names in the SILE website release announcement and link GitHub user IDs in the Release itself. Given you don't seem to use your full name on GitHub I thought I'd ask what you prefer. (and is this your book?)

[Omikhleia]

@Omikhleia A couple of your contributions are going to land in the same release as the math debut. How would you like to be credited? I typically use full names in the SILE website release announcement and link GitHub user IDs in the Release itself. Given you don't seem to use your full name on GitHub I thought I'd ask what you prefer.

@alerque For anything SILE-related, feel free to use my real name (Didier Willis, didier.willis@gmail.com). I should clean the mess that my GitHub repo, is one day, splitting personal projects from collaborative ones ^^ (and there are things where I prefer my name not to appear to visibly, but SILE is not amongst them.

(and is this your book?)

The hastily choice of fonts and the general typography of this first volume leaves much to be desired and I hope the subsequent volumes show an improvement ;). It's a (non-profit) collective work. Out of 4 volumes we made (https://sites.google.com/site/dragonbrumeux/), I have been editor, author, co-author at different levels. But I did the typesetting for all of them, yes.

[akavel]

I'm super excited for this! 😍 Please do provide some examples showcasing what's currently possible, and please do try to clearly explain what are the limitations / what's currently impossible. ❤️ As an optional extra, some "hook/inspiration points" with some suggestions how to maybe try approaching adding more/missing features could be also super cool; my personal belief is, that once the initial breakthrough work is now done, it will hopefully open doors for people to slowly start incrementally filling in & contributing their "pet peeves" of what they need that is still missing. 🤞

[simoncozens]

Are we really going to introduce math support in a patch version bump? :-)

[akavel]

(unrelated comment deleted, I accidentally posted in wrong thread)

[alerque]

Are we really going to introduce math support in a patch version bump? :-)

It's not a patch version. A patch version bump would be v0.11.1.1. If we're strictly following semver as long as we are in the zero-dot phase everything is basically moved down one level. If you want to start following more normal semver patterns we need to get into the v1+ range.

Currently (and for the last 3 major release cycles) v0.X releases denote breaking changes. Adding a feature (math) is not a breaking change.

[alerque]

I'd be happy enough to switch over into 1.x territory so semver made more sense. Perhaps with the change to document classes being penlight instead of stdlib (which is a painful break) would be a reasonable point to do that. But @simoncozens you are the one that set the pace of v1 being "typeset a full Bible text reasonably with the usual Bible publishing trimmings from just input sources with no hackery" (my paraphrase) as the goal post for v1 and I've been trying to respect that. We're still not there yet, but if we want to redefine the parameters and follow regular semver with a promise of backwards compatibility in each major release, we can do that. At the rate I see the needed fixes progressing that would probably put typesetting a raw Bible source to a decent book form at v3 or something like that.

[simoncozens]

No, it's fine. I didn't remember that semver was down-a-level at the v0 phase.

[alerque]

The "down a level" scheme isn't official semver, officially it's just a wild west. The semver spec says:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Even now –whether we call it v0 or not– I am not comfortable with just changing anything at any time. I use SILE in production in too many different ways for too many different projects for it to be just randomly changing without careful planning. Warning messages before deprecations help a lot (easy to test build and see if a project will or won't be affected by the next release), shims help, and knowing from the version scheme when to hold off is important.

The other hand the "down a level" scheme is more or less followed by hundreds of projects out there and feels fairly familiar. Known deliberate breaking changes vs. ongoing development releases are clearly two different levels. We've been sticking to it for the last 20 releases or so, I don't really see the point in changing.

For grins, zero0ver is pretty popular too. Right now that's us.

[OlivierNicole]

Here is a possible showcase PDF: showcase.pdf

Obtained with the code:

\begin[class=plain]{document}
\script[src=packages/math]

\font[family=Libertinus Serif, size=12]

\set[parameter=math.font.family, value=Libertinus Math]
\set[parameter=math.font.size, value=12]

\define[command=bold]{\font[weight=800]{\process}}
\define[command=bold]{\font[weight=800]{\process}}
\define[command=theorem]{\bold{Theorem}\enspace}

\theorem For all \math{
  \def{dsi}{\mi[mathvariant=double-struck]{#1}}
  \def{NN}{\dsi{N}}
  n \in \NN}:

\begin[mode=display]{math}
  \sum_{i=0}^n i = \frac{n(n+1)}{2}
\end{math}

\theorem For all \math{n \in \NN}:

\begin[mode=display]{math}
  \sum_{i=0}^n i^2 = \frac{n(n+1)(2n+1)}{6}
\end{math}

\bold{Theorem} (Divergence theorem)\enspace For any volume \math{V} and
continuously differentiable vector field \math{
  \def{vec}{\mi[mathvariant=bold]{#1}}
  \vec{F}
}:

\begin[mode=display]{math}
  \iiint_V \vec{\nabla} \cdot \vec{F} \mspace[width=1pt] \mo{d}\mi{V}
  =
  \oiint_{\partial V} \vec{F} \cdot \mo{d}\vec{S}
\end{math}
where \math{\partial V} is the border of \math{V}.
\bigskip

\bold{Definition} (Fibonacci sequence)\enspace Let \math{u_n} be the sequence
defined by:
\begin[mode=display]{math}
  \{
  \table[columnalign=left center left]{
    u_0 &=& 1 \\
    u_1 &=& 1 \\
    u_{n+2} &=& u_{n+1} + u_n,\mspace[width=3pt] \forall n \in \NN \\
  }
\end{math}

\theorem For all \math{n \in \NN}:
\begin[mode=display]{math}
  u_n = \frac{\phi^n - \psi^n}{\phi - \psi}
\end{math}
where \math{\phi} and \math{\psi} are the roots of \math{x^2 - x - 1}.

\end{document}

Open to comments and suggestions, of course.

[alerque]

Fantastic @OlivierNicole! I've made a few tweaks (smaller paper, bigger font, etc.) and added it to the announcement PR #21.

[alerque]

Just a follow-up on the versioning discussion. Math is going to land in v0.12.0 after all, but the culprit is not math. The major (down a level from semver) version bump is to accommodate a breaking change I've scheduled for the next release. See https://github.com/sile-typesetter/sile/pull/1216

[alerque]

On the subject of credits:

• @OlivierNicole you are not showing up in contributor graphs at all because the email address from your commits doesn't seem to be listed in your GitHub profile.

• @cmfwyp and @suhr, it seems like your nicks are deliberately anonymous which is totally fine, but if you do have a name you want mentioned in the release notes feel free to drop it here. Either way we appreciate the corrections in relation to the MathML spec and Nix issues respectively.

[OlivierNicole]

Fixed.

[alerque]

Nice. This will be the first release cycle in a while where I'm not the top contributor. I like it.