Is there any way to set the font size and style for image or table captions?

[no-vici]

Hi again Omikhleia,

I wanted to set the font size and style for image captions, so I had to dig into commands.lua of the markdown package and changed the settings in there.

self:registerCommand("markdown:fallback:captioned-figure", function (_, content)
    if type(content) ~= "table" then
      SU.error("Expected a table AST content in captioned figure environment")
    end
    local caption = extractFromTree(content, "caption")

    SILE.call("smallskip")
    SILE.call("center", {}, function ()
      SILE.process(content)
      if caption then
        SILE.call("novbreak") -- This is magic for fixing the image floating off the main body problem.
        SILE.call("font", {
          size = SILE.settings:get("font.size") * 0.75,
          style = "italic"
        }, caption)
      end
    end)
    SILE.call("smallskip")
  end, "A fallback command for Markdown to insert a captioned table")

Would it be any easier way to change the settings from within the document source code in the future?

Cheers.

[Omikhleia]

That's a good question - and I'm going to leave it "Unanswered" here, just providing some ideas and my current line of reasoning.

• Hacking the code in classes or packages (as you did above) obviously works, but it's kind of a hack and cannot be a long-term solution. (Especially when those commands are kind of internal, and the hard-coded tuning is buried, as here, in the functional logic...)
• Adding either public "customizable hooks" or "settings" is a possibly way...
  • Such a stategy is used in several existing classes and packages (which often have some xxxfont commands - for instance, SILE's default book class has a book:chapterfont hook).
  • It's also the approach many LaTeX packages have...
  • Provided there's such a hook for all places that would need it (i.e. every place where there would have been be some "hard-coded" decision. The font size, right there, indeed. But why not also the amount of skips after and before the environment? Here I went for "small skips", but why actually? And why would one always want a centered environment?
  • Here, it could work as follows: instead of converting from command line, write a small SIL document wrapper that sets the hooks at your convenience, and include the markdown file(s) from within it...
  • I do not like this solution much...
    • The number of hooks would become insane.
    • It's an escape, after all, to full-fledged commands that could do anything beyond they initial purpose. It may have some interest (and power), but this goes far beyond the issue of styling and can also have a lot of unintended side effects. There's a huge "separation of concerns" issue...

So something else is needed. But before going on with the reasoning, let me clarify a point:

• The above "fallback" methods (here, markdown:fallback:captioned-figure) are just here because I tried hard to make this Mardown package standalone and independent from my own classes...
  • SILE's default book class, for instance, is very limited, and - to be honest - rather wrong for anything "real". It's good and useful, though, as an "example" of how to design a (book or other) class with SILE. But it also makes a lot of wrong decisions. It's probably beyond "repair" (or it would loose it's simplicity), IMHO.
  • But it's not as if there were plenty of alternatives... I am only aware of my own attempt (the "resilient.sile" collection).

So we are back to the brainstorming table, but with a little additional assumption: As far as concerned, I wouldn't involve much efforts into the "fallback" methods for other classes than my "resilient" ones... That's a small price to pay ("Use my base classes, and styling will be fully customizable eventually). This is also, obviously, because I have been concerned with the styling paradigm there ;) While in infancy (I don't like the current API and there are still bugs or bogus things, as of yet in Nov. 2022), the styling feature has served me well in a real book (its "fireproof"). You might think to it in terms of "CSS-like idea, but simpler", with styles being defined in a consistent way (via a "style specification")

This doesn't tell us, though, how it could be used here in the context of Markdown processing.

• One way would be to use some declarative part in the Markdown file, e.g. using a YAML metadata block (= as Pandoc can do). That would address your "(can it be done) within the document source code" nicely.

  • The first problem then is that YAML metadata blocks are not supported currently in the underlying Markdown-parsing library used by this package. We might want them eventually, anyway, but it's not just right here at the moment...
  • While it may work from a "single standalone" Markdown file perspective, I have concerns when one builds a document including several Markdown files (e.g. separate book chapters), which ordering may change, etc. - The global picture is hard to see.

• One way would be to use some top level templates (= as Pandoc can also do). There's some support for that in the underlying Markdown-parsing library, but I haven't looked at it yet. Still, it could be a way to avoid the need of a SIL-wrapper document as mentioned above... And compared to the previous solution, it offers a nice separation of concerns.

• One third way would be to re-think the whole thing on different grounds. Ok, no matter the input is Mardown, SILE, or even a mix of both. What if we had a command line flag (for instance) to dump all used styles after having processed a document, and if re-processing it, read it initially.

  • It's a bit like using (possibly another) document for importing styles
  • The style file can be tweaked at convenience, and can be shared (and even archived/commited etc. along with the source file.)
  • The general idea thus goes beyond this very package, and would need to be a feature of the resilient class collection...
  • Styles in my "resilient" collection are, intrinsically, just Lua tables. It looks quite close to JSON if just dumped, so the format "as-is" would even be quite acceptable.
  • I am not sure yet this is a good answer, but it's certainly one I'd want to toy with and experiment... The question though would be when, as I run too many horses currently, so to speak.

[no-vici]

Thank you so much indeed for your long and enthusiastic response.

I've been learning SILE for just a few days and finally managed to make a decent outcome (just for fun but still much appreciate your hard word ;)) using our markdown package, which came into rescue for what I wanted to do with other tools. You are absolutely right, now the users have two worlds in there hands: SILE and Markdown.

I was not satisfied with messing around with the underlying layers and fully aware of the consequences, as you pointed out that approach isn't a long term solution.

I could not agree more with you about the intention of keeping the markdown package own its own and focusing on what it does best, converting markdown into something that can be processed by SILE. Styles and settings should be the jobs of document classes.

I have tried your resilient.book class and seen much differences from the standard book class. This new variance offers more features that new users like me can learn a lot from.

I will dig dipper into your book class and markdown package to see if I could come up with anything for styling the figure caption imported from markdown sources.

Cheers.

[Omikhleia]

@no-vici I have finally moved forward on the "resilient.sile" classes to implement the third point I was alluding to in my previous answer.

That is, loading styles from a separate file (in YAML for readility), as part of (in-progress) PR there: Omikhleia/resilient.sile#13

There's a bit of work and tests required to complete the implementation, but at least the basic system is now nearly there. Perhaps you'll find the (in-progress too) documentation in PDF worth checking: Resilient Manual WIP -- The good stuff is in "Part II" (in that draft version).

To summarize: When using the resilient.book class, every style can be customized in a "style file".
For instance the case you were mentioning --- The size of a figure caption -- one just has to edit the style file (which is generated on the first run, if absent) and tweak the corresponding style:

figure-caption:
  style:
    font:
      size: "0.95em" # <-------------- Here!
    (... rest of style details skipped ...)

But actually, there's a lot more configuration possible. Since everything (almost) is "styled", say you want the caption label ("Figure N.") to be in red color, and actually be rather labelled "Illustration N."

There's a style for it too, by default:

figure-caption-main-number:
  inherit: "figure-caption-base-number"
  style:
    font:
      features: "+smcp"
    numbering:
      after:
        kern: "iwsp"
        text: "."
      before:
        text: "Figure "

Which could be tuned to

figure-caption-main-number:
  inherit: "figure-caption-base-number"
  style:
    color: "red" # <--- Added!
    font:
      features: "+smcp"
    numbering:
      after:
        kern: "iwsp"
        text: "."
      before:
        text: "Illustration " # <--- Changed!

One can tweak nearly everything, without having to dabble into the code, from skips to spacing, text labels, etc.

And there's also a similar style for table captions, obviously.

I do think it will address nicely customization aspects (provided one uses the resilient classes). I am quite convinced this is the way to go, with external style files which I also commit to Git along my Markdown or SILE sources, to keep my preferred styling for a given project. Yet, I wanted to share it here -- Comments are welcome.

N.B. For Markdown processed directly from the CLI, of course, one would have to force the class, i.e.

sile -c resilient.book -u inputters.markdown somefile.md

[Omikhleia]

If you use a SIL wrapper as above, for layouts you can also do:
\begin[papersize=a4, class=resilient.book, layout=ateliers demiluxe]{document}

(And likewise, all class options can be overridden from the CLI anyway. Even papersize, etc.)

[no-vici]

If you use a SIL wrapper as above, for layouts you can also do: \begin[papersize=a4, class=resilient.book, layout=ateliers demiluxe]{document}

I've tried the suggested layout and this happens:

[Omikhleia]

What's wrong with it? The footnote being too close to the text? (If so, that might be a SILE issue with overfull pages)

EDIT: If that's the case, try running SILE with -d frames and it might show the frames are overlapping indeed. As in the following example:

I think there's already a SILE issue about this, not sure it's easy to address though...

EDIT2: sile-typesetter/sile#214 ^^

[no-vici]

What's wrong with it? The footnote being too close to the text? (If so, that might be a SILE issue with overfull pages)

The main content frame overlaps the footnote's frame and I see a lot complain about overfull page.

I think there's already a SILE issue about this, not sure it's easy to address though...

I see, it only happens if the footnote falls on the last line of the page. Does this mean that we should wait for a solution though? Any dirty and quick hack? ;)

[Omikhleia]

Any dirty and quick hack? ;)

Unfortunately, I didn't find any. I had around 6 of those in the first book I made with SILE, over the course of 360+ pages... I just addressed them by manually changing the input slightly (e.g. rephrasing a sentence, adding a skip or a manual page break, etc.). I could do that as the text was mine, but it was annoying :(

I have the issue too in my on-going project, and I can't alter the text there, it has to be what it is... I started at looking how SILE computes the footnote space and does the page breaking, but it's not the easiest thing to read and debug...

[no-vici]

The style package is a very beautiful concept and approach, I think that the best way forward and it makes the settings for styles closer to the users' end. Hopefully, the documentation will be updated in the next version of the SILE book.

Thanks again for all the hard-word invested in there.