Small batch of documentation remarks

[Omikhleia]

A bunch of things I noted at various times and didn't report yet. The first items are mostly documentation-related, the final ones are more on the boundary of bugs/refactors.

Notes "in passing" on a few package documentation

chordmode package

• Setting chormode.lineheight is undocumented.
  • Its effect (with an absolute default "4mm") is dubious at best. (I haven't checked it, but the rationale for a fixed height not based on font size or baseline skip would have to be explained...)

color-fonts package

• Documentation mentions the COLR table, the code also references CPAL: maybe worth mentioning for informed readers? It's pretty technical in both cases, though.

converters package

• converters:check is not documented. (At quick glance, it does perform a file conversion, but all the user will get is (maybe) warnings: not sure why there ought to be such a command exposed to SILE-language level.)

inputfilter package

• Documentation mentions class:loadPackage(). Confusing: it doesn't seem necessary (in many other cases of packages using it, the package is just loaded with SILE.require) i.e. doesn't seem this package HAS to be class-loaded (as opposed, say, to footonotes etc. where the class SHALL use some of the provided methods). -- Removing the checkbox here, this was written at the time the new class/package API wasn't fully the same as of now (May 2023), and it does seem decent enough

features package

• "As mentioned in Chapter 3": Can't we make package documentations independent from the SILE manual and self-explanatory?

footnotes package

• Refers to the "book" class, not generic enough (other classes could use it as well, doesn't need to be a book).
• See also below.

lorem package

• Has an undocumented "counter" boolean option (which might not work well from SIL documents - it's not cast to a boolean...)

twoside package

• Documentation should ideally be self-consistent and shouldn't refer to a "chapter 4",
• Documentation shouldn't ideally refer to the book class as we know it (the use case for twoside is more general that this very class)
• "It has no user-serviceable parts." = Wrong currently, what about \open-double-page? But see further below though This was fixed earlier when new commands were added.

xmltricks

• "In chapter 9, we’re going to use SILE to typeset existing XML documents."... (But this package is maybe ill-named anyway, it doesn't have to be XML-related). -- Removing the checkbox here, this package is quite bad and needs to be more globally re-discussed anyway

Other important notes

• Wrong details about outputInsertions --> Fixed during Refactor typesetter, removed last usage of Lua stdlib #1392

  • Manual (c10-classdesign.sil) mentions outputInsertions() having to be called at the end of each page.
  • Initial comment in "footnotes" package also mentions it.
  • The footnotes package just re-exports that of the insertions package...
  • ... Which is not actually exported at all by the latter :) (and so obviously, such a function is never to be found in our classes' endPage)

• Regarding \open-double-page in the twoside package N.B. Removing the checkbox here, other commands where added later and the design decision is still bad IMHO but anyway, it's not blocking...

  • IMHO, it doesn't belong here. The "twoside" package ought to be focused on handling right and left masters correctly (and it already has more serious issues to deal with, Refactor twoside package #683)
  • At "best", it should be moved to the "book" class. Rationale: The way to do such things properly is actually a class-design decision, and a generic all-purpose command doesn't address it correctly. Some books do not honor the old rule of opening chapters on odd pages. Most books do, but do not repeat the running header of the previous chapter on the blank left page thus inserted (and there are good reasons for that...). Some books don't even have a folio on such page. Or they do for chapters, but not for parts, etc. So there's some sort of separation of concerns. Rather let the class provide its own implementation(s) of the expected sectioning-related logic.

Other minor things

• "There is no shortcut for boldface, because boldface isn’t good typographic practice and so we don’t want to make it easy for you to make bad books." (regarding \font). Erm, but:
  • Contradicted by the fact of having \strong (via the plain class, IIRC). That command is incidentally discussed in Does SILE (intend to) support nesting \em? #1048
  • Named font (width and) weight are mentioned in Select fonts by width #285
  • Whatever, it is quite untrue that "boldface isn’t good typographic practice". As for underlining etc. it depends on the use case. It's pretty bad in novel-type books to abuse heavy weight, but there are Humanities where you cannot avoid it.

[alerque]

• shouldn't refer to a "chapter 4",

This is one reason I'd like to see your crossrefs package brought up to 1st-party/core status. Any self respecting book class needs to be able to cross reference things without updating references manually.

[Omikhleia]

• shouldn't refer to a "chapter 4",

This is one reason I'd like to see your crossrefs package brought up to 1st-party/core status. Any self respecting book class needs to be able to cross reference things without updating references manually.

Slightly different topic here, though. Package documentations should not refer to manual chapters, as we might want to include them in other docs. They should be self-contained, but several package docs refer to the manual.

[alerque]

Hmm, good point on aiming for the package docs to be self contained in case we adopt them to a context other than the manual.

[Omikhleia]

Hmm, good point on aiming for the package docs to be self contained in case we adopt them to a context other than the manual.

There might even be a time where we'd want to split the manual and the packages, or reorganize them, etc. (I was tempted to do so at one point, rather than a not-so-alphabetical list)... So yeah, packages should very probably be independent from assuming the manual says something about them.

[Omikhleia]

N.B. Added a remark on the lorem package to the list in the issue description.

[Omikhleia]

Description updated + I am ticking checkboxes as I address items in #1794