9304060604

Committed 30 May 2024 02:07PM UTC coverage: 74.124% (-0.6%) from 74.707%

Build # 9304060604

Build Type

push

github

Committed by

alerque

Commit Message

style: Reformat Lua with stylua

Run Details

8104 of 11995 new or added lines in 184 files covered. (67.56%)

15 existing lines in 11 files now uncovered.

12444 of 16788 relevant lines covered (74.12%)

7175.1 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

90.63

/packages/lists/init.lua

local base = require("packages.base")

local package = pl.class(base)
package._name = "lists"

--
-- 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 styles = {
   enumerate = {
      { display = "arabic", after = "." },
      { display = "roman", after = "." },
      { display = "alpha", after = ")" },
      { display = "arabic", after = ")" },
      { display = "roman", after = ")" },
      { display = "alpha", after = "." },
   },
   itemize = {
      { bullet = "•" }, -- black bullet
      { bullet = "◦" }, -- circle bullet
      { bullet = "–" }, -- en-dash
      { bullet = "•" }, -- black bullet
      { bullet = "◦" }, -- circle bullet
      { bullet = "–" }, -- en-dash
   },
}

local trimLeft = function (str)
   return str:gsub("^%s*", "")
end

local trimRight = function (str)
   return str:gsub("%s*$", "")
end

local trim = function (str)
   return trimRight(trimLeft(str))
end

local enforceListType = function (cmd)
   if cmd ~= "enumerate" and cmd ~= "itemize" then
      SU.error("Only 'enumerate', 'itemize' or 'item' are accepted in lists, found '" .. cmd .. "'")
   end
end

function package:doItem (options, content)
   local enumStyle = content._lists_.style
   local counter = content._lists_.counter
   local indent = content._lists_.indent

   if not SILE.typesetter:vmode() then
      SILE.call("par")
   end

   local mark = SILE.typesetter:makeHbox(function ()
      if enumStyle.display then
         if enumStyle.before then
            SILE.typesetter:typeset(enumStyle.before)
         end
         SILE.typesetter:typeset(self.class.packages.counters:formatCounter({
            value = counter,
            display = enumStyle.display,
         }))
         if enumStyle.after then
            SILE.typesetter:typeset(enumStyle.after)
         end
      else
         local bullet = options.bullet or enumStyle.bullet
         SILE.typesetter:typeset(bullet)
      end
   end)

   local stepback
   if enumStyle.display then
      -- 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...
      local labelIndent = SILE.settings:get("lists.enumerate.labelindent"):absolute()
      stepback = indent - labelIndent
   else
      -- Center bullets in the indentation space
      stepback = indent / 2 + mark.width / 2
   end

   SILE.call("kern", { width = -stepback })
   -- 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.
   mark.width = SILE.length(stepback)
   SILE.typesetter:pushHbox(mark)
   SILE.process(content)
end

function package.doNestedList (_, listType, options, content)
   -- depth
   local depth = SILE.settings:get("lists.current." .. listType .. ".depth") + 1

   -- styling
   local enumStyle = styles[listType][depth]
   if not enumStyle then
      SU.error("List nesting is too deep")
   end
   -- options may override the default styling
   enumStyle = pl.tablex.copy(enumStyle) -- shallow copy for possible overrides
   if enumStyle.display then
      if options.before or options.after then
         -- for before/after, don't mix default style and options
         enumStyle.before = options.before or ""
         enumStyle.after = options.after or ""
      end
      if options.display then
         enumStyle.display = options.display
      end
   else
      enumStyle.bullet = options.bullet or enumStyle.bullet
   end

   -- indent
   local baseIndent = (depth == 1) and SILE.settings:get("document.parindent").width:absolute()
      or SILE.measurement("0pt")
   local listIndent = SILE.settings:get("lists." .. listType .. ".leftmargin"):absolute()

   -- processing
   if not SILE.typesetter:vmode() then
      SILE.call("par")
   end
   SILE.settings:temporarily(function ()
      SILE.settings:set("lists.current." .. listType .. ".depth", depth)
      SILE.settings:set("current.parindent", SILE.nodefactory.glue())
      SILE.settings:set("document.parindent", SILE.nodefactory.glue())
      SILE.settings:set("document.parskip", SILE.settings:get("lists.parskip"))
      local lskip = SILE.settings:get("document.lskip") or SILE.nodefactory.glue()
      SILE.settings:set("document.lskip", SILE.nodefactory.glue(lskip.width + (baseIndent + listIndent)))

      local counter = options.start and (SU.cast("integer", options.start) - 1) or 0
      for i = 1, #content do
         if type(content[i]) == "table" then
            if content[i].command == "item" then
               counter = counter + 1
               -- Enrich the node with internal properties
               content[i]._lists_ = {
                  style = enumStyle,
                  counter = counter,
                  indent = listIndent,
               }
            else
               enforceListType(content[i].command)
            end
            SILE.process({ content[i] })
            if not SILE.typesetter:vmode() then
               SILE.call("par")
            else
               SILE.typesetter:leaveHmode()
            end
         elseif type(content[i]) == "string" then
            -- All text nodes are ignored in structure tags, but just warn
            -- if there do not just consist in spaces.
            local text = trim(content[i])
            if text ~= "" then
               SU.warn("Ignored standalone text (" .. text .. ")")
            end
         else
            SU.error("List structure error")
         end
      end
   end)

   if not SILE.typesetter:vmode() then
      SILE.call("par")
   else
      SILE.typesetter:leaveHmode()
      if
         not (
            (SILE.settings:get("lists.current.itemize.depth") + SILE.settings:get("lists.current.enumerate.depth")) > 0
         )
      then
         local g = SILE.settings:get("document.parskip").height:absolute()
            - SILE.settings:get("lists.parskip").height:absolute()
         SILE.typesetter:pushVglue(g)
      end
   end
end

function package:_init ()
   base._init(self)
   self:loadPackage("counters")
end

function package.declareSettings (_)
   SILE.settings:declare({
      parameter = "lists.current.enumerate.depth",
      type = "integer",
      default = 0,
      help = "Current enumerate depth (nesting) - internal",
   })

   SILE.settings:declare({
      parameter = "lists.current.itemize.depth",
      type = "integer",
      default = 0,
      help = "Current itemize depth (nesting) - internal",
   })

   SILE.settings:declare({
      parameter = "lists.enumerate.leftmargin",
      type = "measurement",
      default = SILE.measurement("2em"),
      help = "Left margin (indentation) for enumerations",
   })

   SILE.settings:declare({
      parameter = "lists.enumerate.labelindent",
      type = "measurement",
      default = SILE.measurement("0.5em"),
      help = "Label indentation for enumerations",
   })

   SILE.settings:declare({
      parameter = "lists.itemize.leftmargin",
      type = "measurement",
      default = SILE.measurement("1.5em"),
      help = "Left margin (indentation) for bullet lists (itemize)",
   })

   SILE.settings:declare({
      parameter = "lists.parskip",
      type = "vglue",
      default = SILE.nodefactory.vglue("0pt plus 1pt"),
      help = "Leading between paragraphs and items in a list",
   })
end

function package:registerCommands ()
   self:registerCommand("enumerate", function (options, content)
      self:doNestedList("enumerate", options, content)
   end)

   self:registerCommand("itemize", function (options, content)
      self:doNestedList("itemize", options, content)
   end)

   self:registerCommand("item", function (options, content)
      if not content._lists_ then
         SU.error("The item command shall not be called outside a list")
      end
      self:doItem(options, content)
   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}
]]

return package

1	local base = require("packages.base")	3✔
2
3	local package = pl.class(base)	3✔
4	package._name = "lists"	3✔
5
6	--
7	-- Enumerations and bullet lists for SILE
8	-- Donated to the SILE typesetter - 2021-2022, Didier Willis
9	-- This a trimmed-down version of the feature-richer but more experimental
10	-- "enumitem" package (https://github.com/Omikhleia/omikhleia-sile-packages).
11	-- License: MIT
12	--
13	-- NOTE: Though not described explicitly in the documentation, the package supports
14	-- two nesting techniques:
15	-- The "simple" or compact one:
16	-- \begin{itemize}
17	-- \item{L1.1}
18	-- \begin{itemize}
19	-- \item{L2.1}
20	-- \end{itemize}
21	-- \end{itemize}
22	-- The "alternative" one, which consists in having the nested elements in an item:
23	-- \begin{itemize}
24	-- \item{L1.1
25	-- \begin{itemize}
26	-- \item{L2.1}
27	-- \end{itemize}}
28	-- \end{itemize}
29	-- The latter might be less readable, but is of course more powerful, as other
30	-- contents can be added to the item, as in:
31	-- \begin{itemize}
32	-- \item{L1.1
33	-- \begin{itemize}
34	-- \item{L2.1}
35	-- \end{itemize}%
36	-- This is still in L1.1}
37	-- \end{itemize}
38	-- But personally, for simple lists, I prefer the first "more readable" one.
39	-- Lists from Mardown, obviously, due to their structure, would need the
40	-- second technique.
41	--
42
43	local styles = {	3✔
44	enumerate = {	3✔
45	{ display = "arabic", after = "." },	3✔
46	{ display = "roman", after = "." },	3✔
47	{ display = "alpha", after = ")" },	3✔
48	{ display = "arabic", after = ")" },	3✔
49	{ display = "roman", after = ")" },	3✔
50	{ display = "alpha", after = "." },	3✔
51	},	3✔
52	itemize = {	3✔
53	{ bullet = "•" }, -- black bullet	3✔
54	{ bullet = "◦" }, -- circle bullet	3✔
55	{ bullet = "–" }, -- en-dash	3✔
56	{ bullet = "•" }, -- black bullet	3✔
57	{ bullet = "◦" }, -- circle bullet	3✔
58	{ bullet = "–" }, -- en-dash	3✔
59	},	3✔
60	}
61
62	local trimLeft = function (str)
63	return str:gsub("^%s*", "")	52✔
64	end
65
66	local trimRight = function (str)
67	return str:gsub("%s*$", "")	52✔
68	end
69
70	local trim = function (str)
71	return trimRight(trimLeft(str))	104✔
72	end
73
74	local enforceListType = function (cmd)
75	if cmd ~= "enumerate" and cmd ~= "itemize" then	14✔
NEW 76	SU.error("Only 'enumerate', 'itemize' or 'item' are accepted in lists, found '" .. cmd .. "'")	×
77	end
78	end
79
80	function package:doItem (options, content)	3✔
81	local enumStyle = content._lists_.style	28✔
82	local counter = content._lists_.counter	28✔
83	local indent = content._lists_.indent	28✔
84
85	if not SILE.typesetter:vmode() then	56✔
NEW 86	SILE.call("par")	×
87	end
88
89	local mark = SILE.typesetter:makeHbox(function ()	56✔
90	if enumStyle.display then	28✔
91	if enumStyle.before then	10✔
NEW 92	SILE.typesetter:typeset(enumStyle.before)	×
93	end
94	SILE.typesetter:typeset(self.class.packages.counters:formatCounter({	30✔
95	value = counter,	10✔
96	display = enumStyle.display,	10✔
97	}))
98	if enumStyle.after then	10✔
99	SILE.typesetter:typeset(enumStyle.after)	10✔
100	end
101	else
102	local bullet = options.bullet or enumStyle.bullet	18✔
103	SILE.typesetter:typeset(bullet)	18✔
104	end
105	end)
106
107	local stepback
108	if enumStyle.display then	28✔
109	-- The positioning is quite tentative... LaTeX would right justify the
110	-- number (at least for roman numerals), i.e.
111	-- i. Text
112	-- ii. Text
113	-- iii. Text.
114	-- Other Office software do not do that...
115	local labelIndent = SILE.settings:get("lists.enumerate.labelindent"):absolute()	20✔
116	stepback = indent - labelIndent	20✔
117	else
118	-- Center bullets in the indentation space
119	stepback = indent / 2 + mark.width / 2	54✔
120	end
121
122	SILE.call("kern", { width = -stepback })	56✔
123	-- reinsert the mark with modified length
124	-- using \rebox caused an issue sometimes, not sure why, with the bullets
125	-- appearing twice in output... but we can avoid it:
126	-- reboxing an hbox was dumb anyway. We just need to fix its width before
127	-- reinserting it in the text flow.
128	mark.width = SILE.length(stepback)	56✔
129	SILE.typesetter:pushHbox(mark)	28✔
130	SILE.process(content)	28✔
131	end
132
133	function package.doNestedList (_, listType, options, content)	3✔
134	-- depth
135	local depth = SILE.settings:get("lists.current." .. listType .. ".depth") + 1	48✔
136
137	-- styling
138	local enumStyle = styles[listType][depth]	24✔
139	if not enumStyle then	24✔
NEW 140	SU.error("List nesting is too deep")	×
141	end
142	-- options may override the default styling
143	enumStyle = pl.tablex.copy(enumStyle) -- shallow copy for possible overrides	48✔
144	if enumStyle.display then	24✔
145	if options.before or options.after then	10✔
146	-- for before/after, don't mix default style and options
NEW 147	enumStyle.before = options.before or ""	×
NEW 148	enumStyle.after = options.after or ""	×
149	end
150	if options.display then	10✔
NEW 151	enumStyle.display = options.display	×
152	end
153	else
154	enumStyle.bullet = options.bullet or enumStyle.bullet	14✔
155	end
156
157	-- indent
158	local baseIndent = (depth == 1) and SILE.settings:get("document.parindent").width:absolute()	34✔
159	or SILE.measurement("0pt")	24✔
160	local listIndent = SILE.settings:get("lists." .. listType .. ".leftmargin"):absolute()	48✔
161
162	-- processing
163	if not SILE.typesetter:vmode() then	48✔
164	SILE.call("par")	7✔
165	end
166	SILE.settings:temporarily(function ()	48✔
167	SILE.settings:set("lists.current." .. listType .. ".depth", depth)	24✔
168	SILE.settings:set("current.parindent", SILE.nodefactory.glue())	48✔
169	SILE.settings:set("document.parindent", SILE.nodefactory.glue())	48✔
170	SILE.settings:set("document.parskip", SILE.settings:get("lists.parskip"))	48✔
171	local lskip = SILE.settings:get("document.lskip") or SILE.nodefactory.glue()	48✔
172	SILE.settings:set("document.lskip", SILE.nodefactory.glue(lskip.width + (baseIndent + listIndent)))	96✔
173
174	local counter = options.start and (SU.cast("integer", options.start) - 1) or 0	24✔
175	for i = 1, #content do	118✔
176	if type(content[i]) == "table" then	94✔
177	if content[i].command == "item" then	42✔
178	counter = counter + 1	28✔
179	-- Enrich the node with internal properties
180	content[i]._lists_ = {	28✔
181	style = enumStyle,	28✔
182	counter = counter,	28✔
183	indent = listIndent,	28✔
184	}	28✔
185	else
186	enforceListType(content[i].command)	14✔
187	end
188	SILE.process({ content[i] })	42✔
189	if not SILE.typesetter:vmode() then	84✔
190	SILE.call("par")	52✔
191	else
192	SILE.typesetter:leaveHmode()	16✔
193	end
194	elseif type(content[i]) == "string" then	52✔
195	-- All text nodes are ignored in structure tags, but just warn
196	-- if there do not just consist in spaces.
197	local text = trim(content[i])	52✔
198	if text ~= "" then	52✔
NEW 199	SU.warn("Ignored standalone text (" .. text .. ")")	×
200	end
201	else
NEW 202	SU.error("List structure error")	×
203	end
204	end
205	end)
206
207	if not SILE.typesetter:vmode() then	48✔
208	SILE.call("par")	×
209	else
210	SILE.typesetter:leaveHmode()	24✔
211	if
NEW 212	not (	×
213	(SILE.settings:get("lists.current.itemize.depth") + SILE.settings:get("lists.current.enumerate.depth")) > 0	72✔
214	)
215	then
216	local g = SILE.settings:get("document.parskip").height:absolute()	12✔
217	- SILE.settings:get("lists.parskip").height:absolute()	18✔
218	SILE.typesetter:pushVglue(g)	6✔
219	end
220	end
221	end
222
223	function package:_init ()	3✔
224	base._init(self)	3✔
225	self:loadPackage("counters")	3✔
226	end
227
228	function package.declareSettings (_)	3✔
229	SILE.settings:declare({	3✔
230	parameter = "lists.current.enumerate.depth",
231	type = "integer",
232	default = 0,
233	help = "Current enumerate depth (nesting) - internal",
234	})
235
236	SILE.settings:declare({	3✔
237	parameter = "lists.current.itemize.depth",
238	type = "integer",
239	default = 0,
240	help = "Current itemize depth (nesting) - internal",
241	})
242
243	SILE.settings:declare({	6✔
244	parameter = "lists.enumerate.leftmargin",
245	type = "measurement",
246	default = SILE.measurement("2em"),	6✔
247	help = "Left margin (indentation) for enumerations",
248	})
249
250	SILE.settings:declare({	6✔
251	parameter = "lists.enumerate.labelindent",
252	type = "measurement",
253	default = SILE.measurement("0.5em"),	6✔
254	help = "Label indentation for enumerations",
255	})
256
257	SILE.settings:declare({	6✔
258	parameter = "lists.itemize.leftmargin",
259	type = "measurement",
260	default = SILE.measurement("1.5em"),	6✔
261	help = "Left margin (indentation) for bullet lists (itemize)",
262	})
263
264	SILE.settings:declare({	6✔
265	parameter = "lists.parskip",
266	type = "vglue",
267	default = SILE.nodefactory.vglue("0pt plus 1pt"),	6✔
268	help = "Leading between paragraphs and items in a list",
269	})
270	end
271
272	function package:registerCommands ()	3✔
273	self:registerCommand("enumerate", function (options, content)	6✔
274	self:doNestedList("enumerate", options, content)	10✔
275	end)
276
277	self:registerCommand("itemize", function (options, content)	6✔
278	self:doNestedList("itemize", options, content)	14✔
279	end)
280
281	self:registerCommand("item", function (options, content)	6✔
282	if not content._lists_ then	28✔
NEW 283	SU.error("The item command shall not be called outside a list")	×
284	end
285	self:doItem(options, content)	28✔
286	end)
287	end
288
289	package.documentation = [[
290	\begin{document}
291	\font:add-fallback[family=Symbola]% HACK Gentium Plus (SILE default font) lacks the circle bullet :(
292	The \autodoc:package{lists} package provides enumerated and itemized (also known as \em{bulleted lists}) which can be nested together.
293
294	\smallskip
295	\noindent
296	\em{Itemized lists}
297	\novbreak
298
299	\indent
300	The \autodoc:environment{itemize} environment initiates a itemized list.
301	Each item, unsurprisingly, is wrapped in an \autodoc:command{\item} command.
302
303	The environment, as a structure or data model, can only contain \code{item} elements or other lists.
304	Any other element causes an error to be reported, and any text content is ignored with a warning.
305
306	\begin{itemize}
307	\item{Lorem}
308	\begin{itemize}
309	\item{Ipsum}
310	\begin{itemize}
311	\item{Dolor}
312	\end{itemize}
313	\end{itemize}
314	\end{itemize}
315
316	The current implementation supports up to six indentation levels.
317
318	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.
319	Note that if your document has a paragraph indent enabled at this point, it is also added to the first list level.
320
321	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.
322	You can also force a specific bullet character to be used on a specific item with \autodoc:command{\item[bullet=<character>]}.
323
324	\smallskip
325	\noindent
326	\em{Enumerated lists}
327	\novbreak
328
329	\indent
330	The \autodoc:environment{enumerate} environment initiates an enumeration.
331	Each item shall, again, be wrapped in an \autodoc:command{\item} command.
332	This environment too is regarded as a structure, so the same rules as above apply.
333
334	The enumeration starts at one, unless you specify the \autodoc:parameter{start=<integer>} option (a numeric value, regardless of the display format).
335
336	\begin{enumerate}
337	\item{Lorem}
338	\begin{enumerate}
339	\item{Ipsum}
340	\begin{enumerate}
341	\item{Dolor}
342	\end{enumerate}
343	\end{enumerate}
344	\end{enumerate}
345
346	The current implementation supports up to six indentation levels.
347
348	On each level, the indentation is defined by the \autodoc:setting{lists.enumerate.leftmargin} setting (defaults to \code{2em}).
349	Note, again, that if your document has a paragraph indent enabled at this point, it is also added to the first list level.
350
351	% And… ah, at least something less repetitive than a raw list of features.
352	% \em{Quite obviously}, we cannot center the label.
353	% Roman numbers, folks, if any reason is required.
354
355	The \autodoc:setting{lists.enumerate.labelindent} setting specifies the distance between the label and the previous indentation level (defaults to \code{0.5em}).
356	Tune these settings at your convenience depending on your styles.
357	If there is a more general solution to this subtle issue, we accept patches.%
358	\footnote{TeX typesets the enumeration label ragged left. Most word processing software do not.}
359
360	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.
361
362	\smallskip
363	\noindent
364	\em{Nesting}
365	\novbreak
366
367	\indent
368	Both environments can be nested.
369	The way they do is best illustrated by an example.
370
371	\begin{enumerate}
372	\item{Lorem}
373	\begin{enumerate}
374	\item{Ipsum}
375	\begin{itemize}
376	\item{Dolor}
377	\begin{enumerate}
378	\item{Sit amet}
379	\begin{itemize}
380	\item{Consectetur}
381	\end{itemize}
382	\end{enumerate}
383	\end{itemize}
384	\end{enumerate}
385	\end{enumerate}
386
387	\smallskip
388	\noindent
389	\em{Vertical spaces}
390	\novbreak
391
392	\indent
393	The package tries to ensure a paragraph is enforced before and after a list.
394	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.
395	Between list items, however, the paragraph skip is switched to the value of the \autodoc:setting{lists.parskip} setting.
396
397	\smallskip
398	\noindent
399	\em{Other considerations}
400	\novbreak
401
402	\indent
403	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.
404	Please be a good typographer. Also, these lists have not yet been tried in right-to-left or vertical writing direction.
405
406	\font:remove-fallback
407	\end{document}
408	]]	3✔
409
410	return package	3✔

sile-typesetter / sile / 9304060604

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous