iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
⛄️

Creating Beautiful Lists with satysfi-enumitem v3.0

に公開

Introduction

In the SATySFi advent calendar 2019, I wrote the following article:

https://qiita.com/monaqa/items/8bd74248c1cfbc62bd64

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.

https://github.com/monaqa/satysfi-enumitem

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.

https://github.com/monaqa/satysfi-enumitem/blob/master/doc/enumitem.pdf

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.

(header)
@require: enumitem/enumitem

When using the enumitem package, it is recommended to add the following to the preamble[1].

(preamble)
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.

(preamble)
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.

(preamble)
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:

(preamble)
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.

(preamble)
% 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!

脚注
  1. raw-arabic, listing-default-label, and other functions can be used without a prefix. ↩︎

Discussion