sile-typesetter / sile / 9324025270

--

-- 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

         end

         }))

         end

      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

   end

   -- options may override the default styling

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

      end

      end

   else

   end

   -- indent

   -- processing

   end

               -- Enrich the node with internal properties

            else

            end

            else

            end

         -- Whitespace left around comment nodes is fine too

            -- ignore whitespace leaking in from in front of indented comments

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

            -- if there do not just consist in spaces.

            end

         else

         end

      end

   end)

   else

      if

         )

      then

      end

   end

end

end

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

      type = "integer",

      default = 0,

      help = "Current enumerate depth (nesting) - internal",

   })

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

      type = "integer",

      default = 0,

      help = "Current itemize depth (nesting) - internal",

   })

      parameter = "lists.enumerate.leftmargin",

      type = "measurement",

      help = "Left margin (indentation) for enumerations",

   })

      parameter = "lists.enumerate.labelindent",

      type = "measurement",

      help = "Label indentation for enumerations",

   })

      parameter = "lists.itemize.leftmargin",

      type = "measurement",

      help = "Left margin (indentation) for bullet lists (itemize)",

   })

      parameter = "lists.parskip",

      type = "vglue",

      help = "Leading between paragraphs and items in a list",

   })

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}