Skip to content

Commit fd22fd5

Browse files
OmikhleiaDidier Willis
Omikhleia
authored and
Didier Willis
committedJan 25, 2025
docs(manual): Reorganize most of the old class-related SIL content into Djot
1 parent 5dd33cd commit fd22fd5

File tree

10 files changed

+568
-716
lines changed

10 files changed

+568
-716
lines changed
 

‎examples/manual-biblio.dj ‎examples/manual-appendices/biblio.dj

File renamed without changes.

‎examples/manual-appendices/resume-class.dj

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# A naive _curriculum vitae_ class
2+
3+
The *resilient.resume* class provides a minimalist (read, naive) way to make a modern-looking _résumé_ (CV) with SILE.
4+
It's a side project of the _re·sil·ient_ collection, born as an experiment to see how the styling paradigm of the collection behaves in a different context.
5+
It might have some rough edges, but it's a good starting point which could be improved upon.[^resume-improvements]
6+
7+
- Fonts
8+
9+
- You should select, early in your document, the main font to be used.
10+
This class ideally works best with a font family that has: a thin style, an italic style, a light-weight (300) bold italic, a bold (600) regular. Lato, for instance, is such a font.
11+
- Dingbat symbols rely on the Symbola font. You can change it by redefining the `resume-dingbats` style.
12+
13+
- Colors should not be abused in a CV, so this class proposes only three different colors.
14+
15+
- Two tints of gray for your first and last name, job title and headline.
16+
17+
- A nice tint of blue (#4080bf) for various sectioning and display elements. You can change it by redefining the `resume-color` style.[^resume-names]
18+
19+
- Page layout
20+
21+
- The first page does not have a header, but on subsequent pages the header repeats your full name.
22+
The rationale is that your name shall be visible on each page, as the HR people get hundreds of CVs and
23+
can easily get lost in them.
24+
- The footer is shown side-by-side with the page folio, and contains your contact information. As for
25+
the header, the rationale is that your contacts should be repeated. You wouldn’t want not to be
26+
contacted just because the HR people lost the initial page, right?
27+
- The folio includes the number of pages in your CV. As said, they
28+
get to see hundreds of CV. Be nice ensuring they have no ordering issue when handling a printed
29+
copy to managers, and do not miss any page.
30+
31+
32+
The commands are pretty simple and straightforward in this first version, so you can refer
33+
to the sample CV included in our example repository.
34+
35+
:::
36+
[![](examples/resume-sample.pdf){width="48%" page=1}]{custom-style="ShadowFramed"}
37+
[![](examples/resume-sample.pdf){width="48%" page=2}]{custom-style="ShadowFramed"}
38+
:::
39+
^ A sample CV for a famous detective.
40+
41+
42+
[^resume-improvements]: This author has not checked extensively how other CV tools work.
43+
Maybe there is soome JSON or YAML formats commonly used, and it could be interesting to support them, and extend the class with more capabilities.
44+
Readers are encouraged to contribute to the effort.
45+
46+
[^resume-names]: Likewise, your first and last names correspond to the `resume-firstname` and `resume-lastname` styles respectively.

‎examples/manual-classes/classes.dj

+204
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# The resilient book class
2+
3+
The design of the `resilient.book` class was started as an attempt at gradually tuning the default book class from SILE to this author’s needs and taste.
4+
It eventually evolved into a full redesign on different grounds.
5+
This very document uses it, so you can see it in real action.
6+
7+
## Class options
8+
9+
In addition to the class options provided by SILE, the class also supports the following options:
10+
11+
: layout
12+
13+
Specifies the default (global) page layout. See part [](#page-layout).
14+
15+
: offset
16+
17+
Specifies the binding offset. See part [](#page-layout).
18+
19+
: headers
20+
21+
Specifies how running headers are used:
22+
23+
- `none`: No running headers.
24+
- `technical` (default): Chapter and section titles go in the even and odd running headers, respectively.
25+
- `novel`: Chapter titles go in the odd running headers, and the title of the book, if set, goes in the even running headers.[^book-title]
26+
27+
: resolution
28+
29+
Specifies the global resolution in DPI (dots per inch).
30+
Some add-on packages may use it in order to compute the size of generated images, etc.
31+
32+
33+
34+
[^book-title]: The low-level command to set the book title is `\autodoc:command{\book-title{<text>}}`{=sile}
35+
36+
## Standard sectioning commands
37+
38+
The class supports the following sectioning commands, from the highest division level to the lowest: `\autodoc:command{\part}`, `\autodoc:command{\chapter}`, `\autodoc:command{\section}`, `\autodoc:command{\subsection}`, `\autodoc:command{\subsubsection}`.
39+
40+
All sectioning commands obey styles (relying on the **resilient.styles** and **resilient.sectioning** packages), which notably imply that they have a lot of customization possibilities.
41+
In the following pages, the described behaviors apply to the default configuration and styling, out-of-the-box.
42+
43+
All the sections accepts the `\autodoc:parameter{numbering=false}`{=sile} option, if you want them unnumbered, and the `\autodoc:parameter{toc=false}`{=sile} option, if you do not want them to appear in the table of contents.
44+
When they do, they correspond to “level 0” (parts) up to “level 4” (subsubsections).
45+
46+
Remember a good advice—“Writers that think they need more than five levels should instead consider restructuring their document in a manner that does not require this level of nested sectioning. Increased section granularity can actually begin to detract from document clarity.”
47+
48+
| Style | Description |
49+
|:-------------------------------------------------|:-------------|
50+
| `sectioning-base` | (Paragraph style inherited by all sectioning commands.) |
51+
| `sectioning-⟨section type⟩` | (Sectioning) style applied to that sectioning command. |
52+
^ Styles used for sectioning commands.
53+
54+
By default, parts disable page numbering and running headers on their page.
55+
Chapters have page numbering enabled on their first page and make sure no header shown is shown on that page.
56+
Both start on an odd page[^odd-page], and the previous even page, if inserted blank, is shown without page number and header.
57+
Parts and chapters reset the footnote counter.
58+
Depending on the `headers` class option (see above), chapter and section titles go in running headers, unless customized otherwise.
59+
60+
[^odd-page]: Again, as almost everything depending on styles, this can be customized.
61+
62+
Notably, the class also defines a few commands currenty used as hooks in some of the above sectioning styles.
63+
64+
| Command | Description |
65+
|:-------------------------------------------------|:-------------|
66+
| `\sectioning:part:hook` | Clears all page headers, disable the folios globally, resets the footnote counter and the chapter counter. |
67+
| `\sectioning:chapter:hook` | Clears the header on the current page, re-enables folios, resets the footnote counter and adds the chapter title to the even running headers (see further below). |
68+
| `\sectioning:section:hook` | Adds the section title to the odd running headers (see further below), with its counter preprended to it. |
69+
^ Predefined command hooks used by sectioning commands.
70+
71+
## Captioned environments
72+
73+
The class provides three environnments, `\autodoc:environment{figure}`{=sile}, `\autodoc:environment{table}`{=sile}, and `\autodoc:environment{listing}`{=sile}, for captioned figures, tables, and listings, respectively.
74+
They can contain arbitrary contents and a `\autodoc:command[check=false]{\caption{<text>}}`{=sile} element.
75+
The latter, when present, is extracted and displayed below the contents.
76+
By default, the figure and table environments show their contents centered, with a numbered caption.
77+
The listing environment does not center its content, but otherwise behaves the same.
78+
Each of them has its own distinct counter.
79+
The figure environment is (normally) intended to be used around an illustration.
80+
81+
| Style | Description |
82+
|:-------------------------------------------------|:-------------|
83+
| `figure` | Style applied to the figure content (not including the caption). |
84+
| `figure-caption` | (Sectioning) style applied to the figure caption. |
85+
^ Styles used for figures.
86+
87+
The table environment is (normally) intended to be used around… tables, you would have guessed it.
88+
89+
| Style | Description |
90+
|:-------------------------------------------------|:-------------|
91+
| `table` | Style applied to the table content (not including the caption). |
92+
| `table-caption` | (Sectioning) style applied to the table caption. |
93+
^ Styles used for tables.
94+
95+
The listing environment is (normally) intended to be used around blocks of code, or similar.
96+
Note that the commmand does not switch to verbatim mode, it is up to you to do so if needed.
97+
98+
| Style | Description |
99+
|:-------------------------------------------------|:-------------|
100+
| `listing` | Style applied to the listing content (not including the caption). |
101+
| `listing-caption` | (Sectioning) style applied to the listing caption. |
102+
^ Styles used for listings.
103+
104+
The caption styles are actually sectioning styles, and the captions are inserted into the table of contents at level 5, 6 and 7 respectively.
105+
It implies that one has the possibility to have them shown in the TOC, if passing a sufficient `\autodoc:parameter{depth}`{=sile} value to the `\autodoc:command{\tableofcontents}`{=sile} command.
106+
While some authors may appreciate that, other, most likely, prefer having them in separate lists.
107+
The following convenience commands are provided to that effect.
108+
109+
| Command | Description |
110+
|:-------------------------------------------------|:-------------|
111+
| `\autodoc:command{\listoffigures}`{=sile} | Outputs the list of figures. |
112+
| `\autodoc:command{\listoftables}`{=sile} | Outputs the list of tables. |
113+
| `\autodoc:command{\listoflistings}`{=sile} | Outputs the list of listings. |
114+
^ Commands for lists of figures and tables.
115+
116+
But basically, they are just simple calls to `\autodoc:command{\tableofcontents}`{=sile} with the appropriate options to start at the corresponding TOC level and display only that level.
117+
The only noteworthy advantage is that they check the styles in order to find out which level is concerned, so they may apply even if TOC levels are customized differently.
118+
119+
As a final but important note, despite their name, the figure and table environments are not “floating” objects in the sense that this concept has in LaTeX.
120+
In other terms, they are always inserted where declared in the page, without attempt to possibly move their material to some other position or a later page.
121+
122+
## Headers & Footers
123+
124+
Page numbers (folios) and running headers are by default flushed left or right depending on the page they are on, rather than centered.
125+
This is defined via paragraph styles, so it can actually be customized at convenience.
126+
The default styles also include an inheritance to a common “base” style (suitable for selecting the font size, etc.).
127+
Nothing mandates it, but if you want to redefine these styles, we recommend keeping an appropriate style hierarchy, rather than stacking all definitions in a single style.
128+
Well-thought, it can simplify the task for other later customizations.
129+
130+
| Style | Description |
131+
|:-------------------------------------------------|:-------------|
132+
| `folio-base` | (Style inherited by the other folio styles.) |
133+
| `header-base` | (Style inherited by the other header styles.) |
134+
| `folio-even` | (Paragraph) style applied to the folio on even pages. |
135+
| `folio-odd` | (Paragraph) style applied to the folio on odd pages. |
136+
| `header-even` | (Paragraph) style applied to the header on even pages. |
137+
| `header-odd` | (Paragraph) style applied to the header on odd pages. |
138+
^ Styles used for folios and headers.
139+
140+
The class also defines two commands for manipulating the page headers.
141+
142+
| Command | Description |
143+
|:-------------------------------------------------|:-------------|
144+
| `\autodoc:command{\even-running-header{<content>}}`{=sile} | Registers the content to be used in even running headers. |
145+
| `\autodoc:command{\odd-running-header{<content>}}`{=sile} | Registers the content to be used in odd running headers. |
146+
| `\autodoc:command{\even-tracked-header{<content>}}`{=sile} | Registers the content to be used in even running headers, tracked. |
147+
| `\autodoc:command{\odd-tracked-header{<content>}}`{=sile} | Registers the content to be used in odd running headers, tracked. |
148+
^ Commands for manipulating page headers.
149+
150+
The “tracked” variants ensure the content is tracked per page (using “info nodes”), which is usually what you want for section headers.
151+
The other versions do not introduce info nodes, are intended to be used with direct content (such as a document title) or content already tracked elsewhere.
152+
153+
Page headers rely on the functionality provided by the **resilient.headers** package,
154+
so the `\autodoc:command{\noheaders}`{=sile}, `\autodoc:command{\noheaderthispage}`{=sile} and `\autodoc:command{\headers}`{=sile} commands are available, as well as `\autodoc:command{\header:rule}`{=sile}.
155+
156+
## Block-indented quotes
157+
158+
The class provides the `\autodoc:environment{blockquote}`{=sile} environment to typeset simple block-indented paragraphs.
159+
Indented quotes can be nested.
160+
161+
The environment relies on the same-named style for its styling and on the `\autodoc:setting{book.blockquote.margin}`{=sile} setting for its indentation (defaults to 2em).
162+
163+
The environment also accepts a `\autodoc:parameter{variant}`{=sile} option, to switch to an alternate style, assumed to be named `blockquote-⟨variant⟩`.
164+
165+
## Additional book divisions
166+
167+
The class supports the standard `\autodoc:command{\frontmatter}`{=sile}, `\autodoc:command{\mainmatter}`{=sile} and `\autodoc:command{\backmatter}`{=sile} commands to switch between the different higher-level divisions of the document.
168+
Obviously, these commands can only occur once in the document, and in the order given above.
169+
They start a new page, and influence the style of folios.
170+
171+
| Style | Description |
172+
|:-------------------------------------------------|:-------------|
173+
| `folio-frontmatter` | Numbering style applied to folios in the front matter. |
174+
| `folio-mainmatter` | Numbering style applied to folios in the main matter. |
175+
| `folio-backmatter` | Numbering style applied to folios in the back matter. |
176+
^ Styles used for folios in different document divisions.
177+
178+
Books not using these divisions assume “main” matter by default.
179+
In the “front” and “back” matter divisions, parts and chapters are never numbered.
180+
Note that this is not a configurable style decision, but the very definition of these divisions.
181+
In the main matter, they are numbered by default, although this can be changed either on the sectioning command itself, or globally with adequate styles.
182+
183+
The class also supports the `\autodoc:command{\appendix}`{=sile} command, which can only be invoke once, either in the main matter or in the back matter.
184+
After that, the chapter counter is reset and chapters now use appendix sectioning styles.
185+
By default, these styles derive from the chapter styles, with the numbering changed to uppercase letters, and the prefix text to “Appendix”.
186+
Note that appendices are numbered even in the back matter, by default, according to common practice.
187+
Again, this can be changed on the sectioning command itself, or globally with adequate styles.
188+
189+
## Other features
190+
191+
The footnotes are based on the **resilient.footnotes** package and therefore have the extra features proposed in this implementation, notably the `\autodoc:command{\footnote:rule}`{=sile} command and the possibility to specify an explicit `\autodoc:parameter{mark}`{=sile} on footnote calls.
192+
193+
The table of contents relies on the **resilient.tableofcontents** package. One can therefore change many styling and appearance aspects to create a custom table of contents.
194+
195+
Cross-references are supported via the **labelrefs** package, henceforth the `\autodoc:command{\label}`{=sile}, `\autodoc:command{\ref}`{=sile} and `\autodoc:command{\pageref}`{=sile} commands are available.
196+
197+
A few layout-related commands are also provided.
198+
199+
The `\autodoc:command{\layout[layout=<layout spec>]}`{=sile} command inserts a page break if needed, and changes the page layout from that point.
200+
An optional `\autodoc:parameter{offset=<dimen>}`{=sile} may be specified to also alter the binding offset.
201+
By default, the global offset (that is, as possibly defined via the corresponding class option) is used.
202+
203+
Mostly intended for documentation, the `\autodoc:command{\showlayout[layout=<layout spec>, papersize=<paper spec>]}`{=sile} command outputs an image representing the selected page layout and paper size.
204+
Optional parameters are `\autodoc:parameter{offset=<dimen>}`{=sile} for the binding offset (0, that is no offset, by default), `\autodoc:parameter{ratio=<number>}`{=sile} for the image down-scaling (dividing the paper size by the specified amount, 6.5 by default), and `\autodoc:parameter{rough=<boolean>}`{=sile} (false by default).

0 commit comments

Comments
 (0)
Failed to load comments.