sile-typesetter / sile / 6713098919

--

-- Enumerations and bullet lists for SILE

-- Donated to the SILE typesetter - 2021-2022, Didier Willis

-- This a trimmed-down version of the feature-richer but more experimental

-- "enumitem" package (https://github.com/Omikhleia/omikhleia-sile-packages).

-- License: MIT

--

-- NOTE: Though not described explicitly in the documentation, the package supports

-- two nesting techniques:

-- The "simple" or compact one:

--    \begin{itemize}

--       \item{L1.1}

--       \begin{itemize}

--          \item{L2.1}

--       \end{itemize}

--    \end{itemize}

-- The "alternative" one, which consists in having the nested elements in an item:

--    \begin{itemize}

--       \item{L1.1

--         \begin{itemize}

--            \item{L2.1}

--         \end{itemize}}

--    \end{itemize}

-- The latter might be less readable, but is of course more powerful, as other

-- contents can be added to the item, as in:

--    \begin{itemize}

--       \item{L1.1

--         \begin{itemize}

--            \item{L2.1}

--         \end{itemize}%

--         This is still in L1.1}

--    \end{itemize}

-- But personally, for simple lists, I prefer the first "more readable" one.

-- Lists from Mardown, obviously, due to their structure, would need the

-- second technique.

--

  },

  }

}

local trimLeft = function (str)

end

local trimRight = function (str)

end

local trim = function (str)

end

local enforceListType = function (cmd)

  end

end

  end

        value = counter,

      )

    else

    end

  end)

  local stepback

    -- The positioning is quite tentative... LaTeX would right justify the

    -- number (at least for roman numerals), i.e.

    --   i. Text

    --  ii. Text

    -- iii. Text.

    -- Other Office software do not do that...

  else

    -- Center bullets in the indentation space

  end

  -- reinsert the mark with modified length

  -- using \rebox caused an issue sometimes, not sure why, with the bullets

  -- appearing twice in output... but we can avoid it:

  -- reboxing an hbox was dumb anyway. We just need to fix its width before

  -- reinserting it in the text flow.

end

  -- depth

  -- styling

  -- options may override the default styling

      -- for before/after, don't mix default style and options

    end

  else

  end

  -- indent

  -- processing

  end

          -- Enrich the node with internal properties

            style = enumStyle,

            counter = counter,

            indent = listIndent,

          }

        else

        end

        else

        end

        -- All text nodes are ignored in structure tags, but just warn

        -- if there do not just consist in spaces.

      else

      end

    end

  end)

  else

    then

    end

  end

end

end

    parameter = "lists.current.enumerate.depth",

    type = "integer",

    default = 0,

  })

    parameter = "lists.current.itemize.depth",

    type = "integer",

    default = 0,

  })

    parameter = "lists.enumerate.leftmargin",

    type = "measurement",

    default = SILE.measurement("2em"),

  })

    parameter = "lists.enumerate.labelindent",

    type = "measurement",

    default = SILE.measurement("0.5em"),

  })

    parameter = "lists.itemize.leftmargin",

    type = "measurement",

    default = SILE.measurement("1.5em"),

  })

    parameter = "lists.parskip",

    type = "vglue",

    default = SILE.nodefactory.vglue("0pt plus 1pt"),

  })

end

  end)

  end)

    end

  end)

end

package.documentation = [[

\begin{document}

\font:add-fallback[family=Symbola]% HACK Gentium Plus (SILE default font) lacks the circle bullet :(

The \autodoc:package{lists} package provides enumerated and itemized (also known as \em{bulleted lists}) which can be nested together.

\smallskip

\noindent

\em{Itemized lists}

\novbreak

\indent

The \autodoc:environment{itemize} environment initiates a itemized list.

Each item, unsurprisingly, is wrapped in an \autodoc:command{\item} command.

The environment, as a structure or data model, can only contain \code{item} elements or other lists.

Any other element causes an error to be reported, and any text content is ignored with a warning.

\begin{itemize}

    \item{Lorem}

    \begin{itemize}

        \item{Ipsum}

        \begin{itemize}

            \item{Dolor}

        \end{itemize}

    \end{itemize}

\end{itemize}

The current implementation supports up to six indentation levels.

On each level, the indentation is defined by the \autodoc:setting{lists.itemize.leftmargin} setting (defaults to \code{1.5em}) and the bullet is centered in that margin.

Note that if your document has a paragraph indent enabled at this point, it is also added to the first list level.

The package has a default bullet style for each level, but you can explicitly select a bullet symbol of your choice to be used by specifying the options \autodoc:parameter{bullet=<character>} on the \autodoc:environment{itemize} environment.

You can also force a specific bullet character to be used on a specific item with \autodoc:command{\item[bullet=<character>]}.

\smallskip

\noindent

\em{Enumerated lists}

\novbreak

\indent

The \autodoc:environment{enumerate} environment initiates an enumeration.

Each item shall, again, be wrapped in an \autodoc:command{\item} command.

This environment too is regarded as a structure, so the same rules as above apply.

The enumeration starts at one, unless you specify the \autodoc:parameter{start=<integer>} option (a numeric value, regardless of the display format).

\begin{enumerate}

    \item{Lorem}

    \begin{enumerate}

        \item{Ipsum}

        \begin{enumerate}

            \item{Dolor}

        \end{enumerate}

    \end{enumerate}

\end{enumerate}

The current implementation supports up to six indentation levels.

On each level, the indentation is defined by the \autodoc:setting{lists.enumerate.leftmargin} setting (defaults to \code{2em}).

Note, again, that if your document has a paragraph indent enabled at this point, it is also added to the first list level.

% And… ah, at least something less repetitive than a raw list of features.

% \em{Quite obviously}, we cannot center the label.

% Roman numbers, folks, if any reason is required.

The \autodoc:setting{lists.enumerate.labelindent} setting specifies the distance between the label and the previous indentation level (defaults to \code{0.5em}).

Tune these settings at your convenience depending on your styles.

If there is a more general solution to this subtle issue, we accept patches.%

\footnote{TeX typesets the enumeration label ragged left. Most word processing software do not.}

The package has a default number style for each level, but you can explicitly select the display type (format) of the values (as \code{arabic}, \code{roman}, or \code{alpha}), and the text prepended or appended to them, by specifying the options \autodoc:parameter{display=<display>}, \autodoc:parameter{before=<string>}, and \autodoc:parameter{after=<string>} to the \autodoc:environment{enumerate} environment.

\smallskip

\noindent

\em{Nesting}

\novbreak

\indent

Both environments can be nested.

The way they do is best illustrated by an example.

\begin{enumerate}

    \item{Lorem}

    \begin{enumerate}

        \item{Ipsum}

        \begin{itemize}

            \item{Dolor}

            \begin{enumerate}

                \item{Sit amet}

                \begin{itemize}

                    \item{Consectetur}

                \end{itemize}

            \end{enumerate}

        \end{itemize}

    \end{enumerate}

\end{enumerate}

\smallskip

\noindent

\em{Vertical spaces}

\novbreak

\indent

The package tries to ensure a paragraph is enforced before and after a list.

In most cases, this implies paragraph skips to be inserted, with the usual \autodoc:setting{document.parskip} glue, whatever value it has at these points in the surrounding context of your document.

Between list items, however, the paragraph skip is switched to the value of the \autodoc:setting{lists.parskip} setting.

\smallskip

\noindent

\em{Other considerations}

\novbreak

\indent

Do not expect these fragile lists to work in any way in centered or ragged-right environments, or with fancy line-breaking features such as hanged or shaped paragraphs.

Please be a good typographer. Also, these lists have not yet been tried in right-to-left or vertical writing direction.

\font:remove-fallback

\end{document}