iTranslated by AI
Creating Beautiful Lists with satysfi-enumitem v3.0
Introduction
In the SATySFi advent calendar 2019, I wrote the following article:
Two years have passed since then, and the version of the enumitem package has reached v3.0.1, with its usage changing significantly. In this article, I would like to create many wonderful lists using the reborn enumitem package.
What is the Enumitem Package?
The Enumitem package is a package for implementing lists in the SATySFi typesetting system.
While there is a standard itemize package for formatting lists, the enumitem package was developed to provide lists with a higher degree of flexibility.
Installation
Using Satyrographos makes the installation process smooth.
opam install satysfi-enumitem
satyrographos install
Please confirm that enumitem package v3.0.1 is installed.
Changes from v2.x.y
Compared to previous versions, enumitem v3.0.1 has the following features:
- Page breaks are now possible within items in any list.
- By using block-based notation (described later), complex lists such as items consisting of multiple paragraphs can now be handled naturally.
Documentation
There is still much more content that could not be covered in this article. Please refer to the documentation for details.
Basic Usage
Importing the Package
If you install using Satyrographos, you can use the enumitem package commands by adding the following line to the header section of your SATySFi document.
@require: enumitem/enumitem
When using the enumitem package, it is recommended to add the following to the preamble[1].
open EnumitemAlias
+listing and +enumerate
The standard +listing command, which is also provided in the standard itemize package, is supported by default.
+p{
There are three types of people in the world.
}
+listing{
* Those who can count
* Those who cannot count
}

Simple unnumbered list
The +enumerate command is also available. This one supports nesting by default.
+enumerate{
* Top page
* The SATySFibook Web Edition 1st Edition
* Wiki
** Installation
** Compiling demo documents
% (omitted)
}

Simple numbered list
Changing Labels
In SATySFi v3.0.1, +genlisting has been deprecated, and you can now specify labels using the optional argument of +listing instead.
+listing?:(white-bullet){
* Huh?
* They've properly turned into white bullets!
}

A list with labels changed to white bullets
Similarly, the +enumerate command allows you to specify labels through an optional argument.
+enumerate?:(paren-roman){
* Huh?
* They've properly turned into Roman numerals!
}

A list with labels changed to Roman numerals
The labels provided by default are as follows:
| Label Name | Effect |
|---|---|
raw-arabic |
Arabic numerals |
dot-arabic |
Arabic numerals + period |
paren-arabic |
Arabic numerals + parentheses |
bracket-arabic |
Arabic numerals + brackets |
raw-roman |
Roman numerals (lowercase) |
dot-roman |
Roman numerals (lowercase) + period |
paren-roman |
Roman numerals (lowercase) + parentheses |
bracket-roman |
Roman numerals (lowercase) + brackets |
raw-Roman |
Roman numerals (uppercase) |
dot-Roman |
Roman numerals (uppercase) + period |
paren-Roman |
Roman numerals (uppercase) + parentheses |
bracket-Roman |
Roman numerals (uppercase) + brackets |
raw-alph |
Alphabets (lowercase) |
dot-alph |
Alphabets (lowercase) + period |
paren-alph |
Alphabets (lowercase) + parentheses |
bracket-alph |
Alphabets (lowercase) + brackets |
raw-Alph |
Alphabets (uppercase) |
dot-Alph |
Alphabets (uppercase) + period |
paren-Alph |
Alphabets (uppercase) + parentheses |
bracket-Alph |
Alphabets (uppercase) + brackets |
dot-arabic-rec |
Arabic numerals (with hierarchical structure) |
bullet |
Black bullet |
white-bullet |
White bullet |
listing-default-label |
Varies by nesting depth (unnumbered) |
enumerate-default-label |
Varies by nesting depth (numbered) |
Custom Style Lists
Using the text-label function, you can use arbitrary inline text as a label.
+listing?:(text-label {\cjk{☃}\ }){
* Top page
* The SATySFibook Web Edition 1st Edition
* Wiki
** Installation
** Compiling demo documents
% (omitted)
}

A list with ☃ labels
Using index-label, you can change the label according to the list index.
let label-toi =
let labelf idx =
let it-idx = idx |> arabic |> embed-string in
{\textbf{Problem #it-idx;.}\ }
in
index-label labelf
It is getting a bit complex, but we are creating the label by passing labelf (a function of type int -> inline-text) as an argument to the index-label function. We are having labelf decide the inline text to be used as a label when given an index of type int.
+enumerate?:(label-toi){
* How do you put an elephant into a refrigerator?
* Then, how do you put a giraffe into a refrigerator?
* The King of the Jungle, the lion, called a meeting. Who was absent?
* Oh no! Two explorers are trying to cross a crocodile-infested swamp!
}

A list with "Problem" labels
Methods for providing even more complex labels are also available. Since today is Christmas Eve, let's make the snowman list even more wonderful by making full use of SATySFi's graphics features. When running this, please @require the color and gr packages.
let label-8-xmas =
let labelf ctx idx =
let xmas-color = match idx mod 3 with
| 0 -> Color.rgb 0.1 0.5 0.2
| 1 -> Color.rgb 0.7 0.2 0.2
| _ -> Color.black
in
let fsize = get-font-size ctx in
let ib-8 =
let ctx-xmas = ctx |> set-text-color xmas-color in
read-inline ctx-xmas {\cjk{☃}}
in
let (wid-8, ht-8, dp-8) = get-natural-metrics ib-8 in
let ib-label =
inline-graphics wid-8 ht-8 dp-8 (fun (x, y) -> [
draw-text (x, y) ib-8
|> Gr.rotate-graphics (x +' wid-8 *' 0.5, y +' ht-8 *' 0.5)
(30. *. (float (1 - idx)))
])
in
ib-label ++ (inline-skip 10pt)
in
EnumitemFormat.new-ordered labelf
By specifying the label as +enumerate?:(label-8-xmas){ ... } as before, you can obtain a list like the one below.

A list with Christmas-themed labels
Block-based Notation
SATySFi provides a dedicated syntax for lists. This is the method using * or ** as bullets to describe list elements, which has appeared several times in the examples so far.
+enumerate{
* Top page
* The SATySFibook Web Edition 1st Edition
* Wiki
** Installation
** Compiling demo documents
}
While this notation is convenient for briefly describing simple lists, it is not suitable for writing complex ones. For example:
- Putting multiple paragraphs within a single item.
- Specifying labels and item text as pairs, like in a definition list.
It is difficult to achieve these with a natural syntax using only the syntactic sugar approach.
Therefore, in enumitem v3.0.1, we have made it possible to write lists using a new block-based notation. Using this block-based notation, a list exactly equivalent to the one above can be written as follows:
+itemize(enumerate-default-label){
+item{Top page}<>
+item{The SATySFibook Web Edition 1st Edition}<>
+item{Wiki}<
+item{Installation}<>
+item{Compiling demo documents}<>
>
}
In the block-based notation, hierarchical structures are represented by nesting +item, and the entire list range is specified by wrapping it in +itemize. Although the notation is somewhat redundant because it doesn't use specialized list syntax, block-based notation has advantages that compensate for it:
- Since arbitrary block text can be placed inside the child elements of
+item, items consisting of multiple paragraphs can be achieved naturally. - Because each item is independent, the appearance of labels can be determined on an item-by-item basis.
- By summarizing complex block text into custom commands, users can freely extend the list notation.
The +item command takes an optional argument to change its own label. By changing the label style for each item, you can do something like this:
let-block +genin it = '< +item?:(text-label{Servant: "}){#it;"}<> >
let-block +rouba it = '< +item?:(text-label{Old Woman: "}){#it;"}<> >
+itemize(nofmt)<
+genin{What were you doing? Speak. If you don't, take this.}
+genin{
I am not an official from the Kebiishi Department.
I am just a traveler who happened to pass under this gate just now.
So I have no intention of tying you up or doing anything to you.
I just want you to tell me what you were doing on top of this gate at this hour.
}
+rouba{
I was plucking this hair, plucking this hair, to make a wig.
}
>

Example of a list where the label type is specified for each item
Using block-based notation, you can also describe definition lists. The +description and +ditem commands for definition lists are defined by default.
+description<
+ditem{\emph{Term 1}}{Here goes the description for Term 1.}<>
+ditem{\emph{Term 2}}{
Here goes the description for Term 2. The description for Term 2 is a bit long.
The description for Term 2 is a bit long. The description for Term 2 is a bit long. The description for Term 2 is a bit long.
}<>
+ditem{\emph{Longer Term 3}}{
Here goes the description for Term 3. The description for Term 3 is a bit long.
The description for Term 3 is a bit long. The description for Term 3 is a bit long. The description for Term 3 is a bit long.
}<
+pn{
Descriptions spanning multiple paragraphs can also be included.
}
>
>

Example of a definition list
The +description and +ditem commands themselves do not change the typeface or color of the term names. This is because whether term names should be emphasized, and if so, what style should be used, varies depending on the document. Therefore, in the example above, terms are emphasized using the \emph command. If that is tedious, it is best to define a command that fits your preference.
% For a definition list consisting of a single paragraph, this one line is sufficient
let-block +dd dt dd = '< +ditem{\emph{#dt;}}{#dd;}<> >
% A definition list consisting of multiple paragraphs can be defined as follows, for example
let-block +dds dt ddlst =
match ddlst with
| [] -> '< +ditem{\emph{#dt;}}{}<> >
| dd :: rest ->
let paragraphs =
rest |> List.fold-left (fun bt assoc -> '<#bt;+pn{#assoc;}>) '<>
in
'< +ditem{\emph{#dt;}}{#dd;}<#paragraphs;> >
+description<
+dd{Term 1}{Here goes the description for Term 1.}
+dd{Term 2}{
Here goes the description for Term 2. The description for Term 2 is a bit long.
The description for Term 2 is a bit long. The description for Term 2 is a bit long. The description for Term 2 is a bit long.
}
+dds{Longer Term 3}{
| Here goes the description for Term 3. The description for Term 3 is a bit long.
The description for Term 3 is a bit long. The description for Term 3 is a bit long. The description for Term 3 is a bit long.
| Descriptions spanning multiple paragraphs can also be included.
|}
>
The list structure itself has become programmable.
Conclusion
enumitem was the first SATySFi package I ever created. Back then, I hadn't accumulated much know-how about package creation, so there were many parts where I thought, "Maybe I should have designed it this way," after I had already made it. Now that the package is at v3.0.1, I feel I can provide features that I am personally quite satisfied with.
Please give it a try!
-
raw-arabic,listing-default-label, and other functions can be used without a prefix. ↩︎
Discussion