Add Localization Support

[arunvickram]

I wanted to see how this package could be extended for easy localization. What I did for right now is I just created a bunch of hacks for digit mapping to test and see whether it works. If you look at this, this, and this, what I've done is I've basically added an extra option to the \begin{document} declaration called language, and that basically determines how the section numbers/digits are localized.

But I'm trying to wrap my head around how I can make it easier to localize further. Any thoughts?

[Omikhleia]

I think that what you are possibly hinting at relates to having language-dependent styling. In your case (second file modified), it's for applying it to numbering (digits), but there are other things where the styles could have to depend on language.

For instance,

• In French, footnote call references are usually preceded by a thin space
  • That is
    • English would do this: Some sentence.² “Some quote.”² (i.e. footnote calls after punctuations, no space before the raised number)
    • French would do this: Une phrase¤². « Une citation¤² ». (i.e. footnote call before punctuations, but thin space before the raised number, here represented as a ¤ symbol for showing where it should be).
  • For a simpler example of language-dependent styles: in French usually, paragraphs are always indented, even after section titles.

Moreover, styles can be overridden -- I am not satisfied yet with the current API, but my idea was to have defaults in Lua (where you made a modification) and a way for providing user-overrides (e.g. currently with \style:define pseudo-commands, but I am even less sure the API is sound there).

So rather than imposing it to the class, my current line of thinking is rather than this should be some kind of on-demand styling, triggering a variation of the styles (at least those where this is needed)

For reference, see also https://github.com/Omikhleia/markdown.sile/discussions/34#discussioncomment-4246305 (a discussion on styling Markdown, but it relates to the resilient.book class eventually). Pushing the idea further in the direction drafted there, I think one possibility is to extract style definition wholly from class and packages in some easier format (e.g. raw Lua tables, or in SIL syntax, XML or even YAML/JSON), and let end-users run with their "customized" version.

[Omikhleia]

(Huh, that was a the long answer) For now, a simpler way with the current (unsatisfying to my eyes) SIL-style API would be not to modify the class but just re-define the styles you need in your document. E.g. (untested)

\begin[class=resilient.book]{document}
\style:redefine[name=sectioning-chapter, as=_original-chapter, inherit=true]{
  \sectioning[display=Gonm]
}% and likewise for all styles needing it
% That is, just redefining them to inherit from the original styles, but overriding some of their properties
...
\end{document}

[arunvickram]

I think that what you are possibly hinting at relates to having language-dependent styling. In your case (second file modified), it's for applying it to numbering (digits), but there are other things where the styles could have to depend on language.

For instance,

* In French, footnote call references are _usually_ preceded by a thin space

  * That is

    * English would do this:  Some sentence.² “Some quote.”² (i.e. footnote calls after punctuations, no space before the raised number)
    * French would do this: Une phrase¤². « Une citation¤² ». (i.e. footnote call before punctuations, but thin space before the raised number, here represented as a ¤ symbol for showing where it should be).

* For a simpler example of language-dependent styles: in French usually, paragraphs are always indented, even after section titles.

Moreover, styles can be overridden -- I am not satisfied yet with the current API, but my idea was to have defaults in Lua (where you made a modification) and a way for providing user-overrides (e.g. currently with \style:define pseudo-commands, but I am even less sure the API is sound there).

So rather than imposing it to the class, my current line of thinking is rather than this should be some kind of on-demand styling, triggering a variation of the styles (at least those where this is needed)

For reference, see also Omikhleia/markdown.sile#34 (comment) (a discussion on styling Markdown, but it relates to the resilient.book class eventually). Pushing the idea further in the direction drafted there, I think one possibility is to extract style definition wholly from class and packages in some easier format (e.g. raw Lua tables, or in SIL syntax, XML or even YAML/JSON), and let end-users run with their "customized" version.

This makes sense, I'm gonna play around with some of these options (in particular the SIL syntax or YAML). I also noticed that we could also leverage fluent-lua to define language based configurations for things like Table of Contents, Chapter, which I think would be necessary to accommodate languages that aren't necessarily like English. I just wanted to get your thoughts on that as well.

[Omikhleia]

I just wanted to get your thoughts on that as well.

• On tables of contents: I do not think the \tableofcontents command (or friends such as the \fancytableofcontents from my fancytoc package) shall have a title. The user should provide it (as an explicit unnumbered chapter, or anything he/she wants there, e.g. some text and pictures possibly). In real books, remembering old days with LaTeX, I used to keep changing whatever the default title was. Why "Table of Contents"? Could be "Contents", "Summary", "Topics" etc. -- Or even nothing at all, after all the readers know how to recognize a ToC when they see one).

• On "Chapter", "Appendix", etc. my current implementation pre-dates the introduction of fluent in SILE. I have not made my mind yet about it.

  • When I proposed adding all usual "terms" from LaTeX/Babel, only a subset was included, so basically the current default i18n files in SILE do not have "part", "appendix", "glossary", etc.
  • It's not a secret that I am not fond of what it does and how it does it. I might change my mind when I revisit and rework the "resilient" styling paradigm (though that rework is still lagging behind schedule).

[arunvickram]

It's not a secret that I am not fond of what it does and how it does it. I might change my mind when I revisit and rework the "resilient" styling paradigm (though that rework is still lagging behind schedule).

Are you not fond of your current implementation or fluent-lua's implementation? Also, I'd like to help either reworking the "resilient" styling paradigm or at least going with my own implementation of this. What's a good place to start?

[Omikhleia]

Are you not fond of your current implementation or fluent-lua's implementation.

That comment applied to fluent-lua as currently implemented and used in SILE core distribution.

(But I am not that fond either of my SIL commands for styles (\style:define etc.) and their use at random places in a document. See below)

Also, I'd like to help either reworking the "resilient" styling paradigm or at least going with my own implementation of this. What's a good place to start?

You might read the documentation of the resilient.styles and resilient.sectioning packages - from their sources, or including them back in the manual (I commented them out for now) ; or in an older PDF from the SILE 0.12 version of these packages (EDIT: p. 40, §1.2.1 and 1.2.2) ; it might be (very) slightly outdated, but at least you have there the key concepts: what I had in mind and how it started.

I globally like the styling paradigm. I used it a lot in my first published book made with SILE, and I am using it too my (work-in-progress) next book project. What I don't like very much is the SIL-syntax for declaring/updating styles.

[arunvickram]

What exactly don't you like about fluent-lua?

Also I'll play around with this and see where I go with this. If I come across anything I'll let you know. How exactly do I change the title for the "Table of Contents"? Also how exactly would I change display of the page number (for example, how would i do the digit mapping for page numbers?)

[Omikhleia]

What exactly don't you like about fluent-lua?

I don't think it solves any problem that cannot be solved in a better way.

How exactly do I change the title for the "Table of Contents"?

The resilient classes use their own table of contents implementation, which doesn't have such a title (as opposed to SILE's core distribution implementation). So there's nothing to change here, you add whatever you want in your document (as I tried to explain above, but perhaps I am misunderstanding the question?)

Also how exactly would I change display of the page number (for example, how would i do the digit mapping for page numbers?)

Er. If not mistaken, I understand you are might be quite new to SILE, and I might be losing you with the specifics of the resilient classes, the styling paradigm, etc.

So let's start with the basics - pure plain SILE, nothing fancy:

\begin{document}
\set-counter[id=folio, display=roman]% switch folio numbering to roman numbers

Lorem ipsum

\end{document}

With styles, one wouldn't have to call that command, but instead would declare something appropriate in the corresponding style specification. The envisioned way will be made clearer when I tackle working on #12. (TBH, folio numbering will not be the most exciting part, I'm afraid :smile_cat: )

[arunvickram]

I don't think it solves any problem that cannot be solved in a better way.

Interesting, could you give me an example as to how it would be solved in a better way

The resilient classes use their own table of contents implementation, which doesn't have such a title (as opposed to SILE's core distribution implementation). So there's nothing to change here, you add whatever you want in your document (as I tried to explain above, but perhaps I am misunderstanding the question?)

You're right, that's exactly what I was getting at: how would you go about doing that using resilient classes?

Er. If not mistaken, I understand you are might be quite new to SILE, and I might be losing you with the specifics of the resilient classes, the styling paradigm, etc.

You're right, I'm relatively new to SILE (I've read much of the documentation and I'm getting a better feel for how SILE works), but I'm familiar with how to change the folio counters, which I've gotten working. I was more asking along the lines of how that would work using resilient styles for consistency purposes, but I figured you might be getting around to working on that as well.

[Omikhleia]

was more asking along the lines of how that would work using resilient styles for consistency purposes,

In my "in-progess" resilient v2 styling attempt, I have a "style definition file" beside my master document (so if my master document is, say, toto.sil, then I have a file toto.rsty, which I can edit and tune separately). Regarding folio (page numbers) styling, here is my (current) setup:

folio-even:
  # called by classes.resilient.book
  inherit: "folio-base"
  style:
    paragraph:
      align: "left"

folio-odd: 
  # called by classes.resilient.book
  inherit: "folio-base"
  style: 
    paragraph: 
      align: "right"

folio-base:
  style:
    font:
      size: "0.9em"
      features: "+onum"
    numbering:
      display: "arabic"

This is experimental might fall short when I introduce frontmatter / mainmatter / backmatter distinctions, but I am not yet there.

[arunvickram]

Is this loaded into your class through lyaml?

[Omikhleia]

@arunvickram

Is this loaded into your class through lyaml?

For now, I've tried to avoid lyaml as it has a C dependency. I don't expect style files to be that huge for performances to really matter here, and the styles only need a fairly decent subset of YAML, so I have consider rather using tinyyaml (it might not be as robust and general, but it's a plain-Lua implementation). Time will tell if this is really sufficient, at least it allows quickly testing the features without introducing more complex dependencies than needed.

I have just reached the point where most of the system works, in #13 -- Perhaps you might be interesting in reviewing it? It's a large PR, so maybe you'll find the (in progress) documentation in PDF more readable: Resilient Manual WIP -- The interesting stuff is in "Part II" (in that version).

I'm interested in your feedback, on both the implementation (if you want) and the general explanation (if you find the doc clear enough, or what could be improved, etc.). Feel free to comment![^1]

[^1]: There will still be some work needed to complete that task (mostly refactors / code cleanup, and also some changes to the epigraph package to make it more style-aware than it is currently), but I'll also work on the page layout system, so at least this PR may possibly wait a bit before merging.

[arunvickram]

I'll have a look at it and provide my feedback on it when I get a chance to. I've been flooded with work so it might take me a little while.

[no-vici]

How exactly do I change the title for the "Table of Contents"?

This was my dirty and quick hack:

\ftl{tableofcontents-title = Nội Dung}
\tableofcontents

The outcome looks quite decent.

[Omikhleia]

Recap before closing this issue. I am going to proceed merging #13 this week-end or the next, so as to proceed to other features depending on it, in order to reach the expected release milestone

After it's done:

• In Resilient, \tableofcontents does not generate title (by design).
• In Resilient, styles in YAML cover both pure styling (font styles, indents, etc.) and prefixed/suffixed texts (such as "Chapter N"). So fluent / ftl are useless in that scheme and won't be used. Everything is done via a separate style file, so that projects can tune their own styles distinctively at convenience (and keep their styling file, archive it alongside the content, etc.).
• In Resilient, number styles also cover the possibility to use other numbering system, etc.

Feedback on the system will still be welcome, obviously, but in dedicated issues once it's made available.