From 80df8aeb6a52ecd32ed0ea89f39b547fb697b228 Mon Sep 17 00:00:00 2001
From: Andrew Paseltiner <apaseltiner@gmail.com>
Date: Sun, 23 Jun 2024 12:59:12 -0400
Subject: [PATCH] Add build-loi command for updating an LoI file from <figure>s

Text from the <figcaption>, if any, is preferred over that from the
 <img>'s alt attribute, though this can be controlled on a per-ID basis.
If the resulting text is empty, default_link_text is used.
---
 se/commands/build_loi.py                      |  50 +++++++
 se/completions/bash/se                        |   6 +-
 se/completions/fish/se.fish                   |   6 +-
 se/completions/zsh/_se                        |   7 +
 se/se_epub.py                                 |  39 ++++++
 .../test-1/golden/src/epub/content.opf        | 125 ++++++++++++++++++
 .../golden/src/epub/text/chapter-1.xhtml      |  51 +++++++
 .../golden/src/epub/text/chapter-2.xhtml      |  14 ++
 .../golden/src/epub/text/chapter-3.xhtml      |  14 ++
 .../test-1/golden/src/epub/text/loi.xhtml     |  56 ++++++++
 .../test-1/golden/src/epub/toc.xhtml          |  24 ++++
 .../build-loi/test-1/in/src/epub/content.opf  | 125 ++++++++++++++++++
 .../test-1/in/src/epub/text/chapter-1.xhtml   |  51 +++++++
 .../test-1/in/src/epub/text/chapter-2.xhtml   |  14 ++
 .../test-1/in/src/epub/text/chapter-3.xhtml   |  14 ++
 .../test-1/in/src/epub/text/loi.xhtml         |  17 +++
 .../build-loi/test-1/in/src/epub/toc.xhtml    |  24 ++++
 .../help/test-1/golden/help-test-1-out.txt    |   1 +
 .../help/test-2/golden/help-test-2-out.txt    |   6 +-
 tests/test_draft_commands.py                  |   4 +-
 20 files changed, 641 insertions(+), 7 deletions(-)
 create mode 100644 se/commands/build_loi.py
 create mode 100644 tests/draft_commands/build-loi/test-1/golden/src/epub/content.opf
 create mode 100644 tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-1.xhtml
 create mode 100644 tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-2.xhtml
 create mode 100644 tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-3.xhtml
 create mode 100644 tests/draft_commands/build-loi/test-1/golden/src/epub/text/loi.xhtml
 create mode 100644 tests/draft_commands/build-loi/test-1/golden/src/epub/toc.xhtml
 create mode 100644 tests/draft_commands/build-loi/test-1/in/src/epub/content.opf
 create mode 100644 tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-1.xhtml
 create mode 100644 tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-2.xhtml
 create mode 100644 tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-3.xhtml
 create mode 100644 tests/draft_commands/build-loi/test-1/in/src/epub/text/loi.xhtml
 create mode 100644 tests/draft_commands/build-loi/test-1/in/src/epub/toc.xhtml

diff --git a/se/commands/build_loi.py b/se/commands/build_loi.py
new file mode 100644
index 00000000..4fe92e51
--- /dev/null
+++ b/se/commands/build_loi.py
@@ -0,0 +1,50 @@
+"""
+This module implements the `se build-loi` command.
+"""
+
+import argparse
+
+import se
+import se.easy_xml
+from se.se_epub import SeEpub
+
+def build_loi(plain_output: bool) -> int:
+	"""
+	Entry point for `se build-loi`
+	"""
+
+	parser = argparse.ArgumentParser(description="Update the LoI file based on all <figure> elements that contain an <img>.")
+	parser.add_argument("-s", "--stdout", action="store_true", help="print to stdout intead of writing to the LoI file")
+	parser.add_argument("directories", metavar="DIRECTORY", nargs="+", help="a Standard Ebooks source directory")
+	args = parser.parse_args()
+
+	if args.stdout and len(args.directories) > 1:
+		se.print_error("Multiple directories are only allowed without the [bash]--stdout[/] option.", plain_output=plain_output)
+		return se.InvalidArgumentsException.code
+
+	for directory in args.directories:
+		try:
+			se_epub = SeEpub(directory)
+		except se.SeException as ex:
+			se.print_error(ex)
+			return ex.code
+
+		try:
+			loi_dom = se_epub.get_dom(se_epub.loi_path)
+			se_epub.generate_loi(loi_dom)
+			xhtml = se.formatting.format_xhtml(loi_dom.to_string())
+
+			if args.stdout:
+				print(xhtml)
+			else:
+				with open(se_epub.loi_path, "w", encoding="utf-8") as file:
+					file.write(xhtml)
+
+		except se.SeException as ex:
+			se.print_error(ex)
+			return ex.code
+		except FileNotFoundError:
+			se.print_error(f"Couldn’t open file: [path][link=file://{se_epub.loi_path}]{se_epub.loi_path}[/][/].", plain_output=plain_output)
+			return se.InvalidSeEbookException.code
+
+	return 0
diff --git a/se/completions/bash/se b/se/completions/bash/se
index 728df688..5255f810 100644
--- a/se/completions/bash/se
+++ b/se/completions/bash/se
@@ -2,7 +2,7 @@ _se(){
 	COMPREPLY=()
 	local cur="${COMP_WORDS[COMP_CWORD]}"
 	local prev="${COMP_WORDS[COMP_CWORD-1]}"
-	local commands="--help --plain --version british2american build build-ids build-images build-manifest build-spine build-title build-toc clean compare-versions create-draft css-select dec2roman extract-ebook find-mismatched-dashes find-mismatched-diacritics find-unusual-characters help hyphenate interactive-replace lint make-url-safe modernize-spelling prepare-release recompose-epub renumber-endnotes roman2dec semanticate shift-endnotes shift-illustrations split-file titlecase typogrify unicode-names version word-count xpath"
+	local commands="--help --plain --version british2american build build-ids build-images build-loi build-manifest build-spine build-title build-toc clean compare-versions create-draft css-select dec2roman extract-ebook find-mismatched-dashes find-mismatched-diacritics find-unusual-characters help hyphenate interactive-replace lint make-url-safe modernize-spelling prepare-release recompose-epub renumber-endnotes roman2dec semanticate shift-endnotes shift-illustrations split-file titlecase typogrify unicode-names version word-count xpath"
 	if [[ $COMP_CWORD -gt 1 ]]; then
 		case "${COMP_WORDS[1]}" in
 			british2american)
@@ -27,6 +27,10 @@ _se(){
 				COMPREPLY+=($(compgen -W "-h --help -v --verbose" -- "${cur}"))
 				COMPREPLY+=($(compgen -d -X ".*" -- "${cur}"))
 				;;
+			build-loi)
+				COMPREPLY+=($(compgen -W "-h --help -s --stdout" -- "${cur}"))
+				COMPREPLY+=($(compgen -d -X ".*" -- "${cur}"))
+				;;
 			build-manifest)
 				COMPREPLY+=($(compgen -W "-h --help -s --stdout" -- "${cur}"))
 				COMPREPLY+=($(compgen -d -X ".*" -- "${cur}"))
diff --git a/se/completions/fish/se.fish b/se/completions/fish/se.fish
index b0c2a11e..34b805c8 100644
--- a/se/completions/fish/se.fish
+++ b/se/completions/fish/se.fish
@@ -1,6 +1,6 @@
 function __fish_se_no_subcommand --description "Test if se has yet to be given the subcommand"
 	for i in (commandline -opc)
-		if contains -- $i british2american build build-ids build-images build-manifest build-spine build-title build-toc clean compare-versions create-draft css-select dec2roman extract-ebook find-mismatched-dashes find-mismatched-diacritics find-unusual-characters help hyphenate interactive-replace lint make-url-safe modernize-spelling prepare-release recompose-epub renumber-endnotes roman2dec semanticate shift-endnotes shift-illustrations split-file titlecase typogrify unicode-names version word-count xpath
+		if contains -- $i british2american build build-ids build-images build-loi build-manifest build-spine build-title build-toc clean compare-versions create-draft css-select dec2roman extract-ebook find-mismatched-dashes find-mismatched-diacritics find-unusual-characters help hyphenate interactive-replace lint make-url-safe modernize-spelling prepare-release recompose-epub renumber-endnotes roman2dec semanticate shift-endnotes shift-illustrations split-file titlecase typogrify unicode-names version word-count xpath
 			return 1
 		end
 	end
@@ -114,6 +114,10 @@ complete -c se -A -n "__fish_seen_subcommand_from prepare-release" -s r -l no-re
 complete -c se -A -n "__fish_seen_subcommand_from prepare-release" -s w -l no-word-count -d "don’t calculate word count"
 complete -c se -A -n "__fish_seen_subcommand_from prepare-release" -s v -l verbose -d "increase output verbosity"
 
+complete -c se -n "__fish_se_no_subcommand" -a build-loi -d "Update the LoI file based on all <figure> elements that contain an <img>."
+complete -c se -A -n "__fish_seen_subcommand_from build-loi" -s h -l help -x -d "show this help message and exit"
+complete -c se -A -n "__fish_seen_subcommand_from build-loi" -s s -l stdout -d "print to stdout intead of writing to the LoI file"
+
 complete -c se -n "__fish_se_no_subcommand" -a build-manifest -d "Generate the <manifest> element for the given Standard Ebooks source directory and write it to the ebook’s metadata file."
 complete -c se -A -n "__fish_seen_subcommand_from build-manifest" -s h -l help -x -d "show this help message and exit"
 complete -c se -A -n "__fish_seen_subcommand_from build-manifest" -s s -l stdout -d "print to stdout instead of writing to the metadata file"
diff --git a/se/completions/zsh/_se b/se/completions/zsh/_se
index 59f9533c..c855dd4e 100644
--- a/se/completions/zsh/_se
+++ b/se/completions/zsh/_se
@@ -16,6 +16,7 @@ case $state in
 			"build[Build an ebook from a Standard Ebook source directory.]" \
 			"build-ids[Change ID attributes for non-sectioning content to their expected values across the entire ebook. IDs must be globally unique and correctly referenced, and the ebook spine must be complete.]" \
 			"build-images[Build ebook cover and titlepage images in a Standard Ebook source directory.]" \
+			"build-loi[Update the LoI file based on all <figure> elements that contain an <img>.]" \
 			"build-manifest[Generate the <manifest> element for the given Standard Ebooks source directory and write it to the ebook’s metadata file.]" \
 			"build-spine[Generate the <spine> element for the given Standard Ebooks source directory and write it to the ebook’s metadata file.]" \
 			"build-title[Generate the title of an XHTML file based on its headings and update the file’s <title> element.]" \
@@ -83,6 +84,12 @@ case $state in
 					{-v,--verbose}'[increase output verbosity]' \
 					'*: :_directories'
 				;;
+			build-loi)
+				_arguments -s \
+					{-h,--help}'[show a help message and exit]' \
+					{-s,--stdout}'[print to stdout intead of writing to the LoI file]' \
+					'*: :_directories'
+				;;
 			build-manifest)
 				_arguments -s \
 					{-h,--help}'[show a help message and exit]' \
diff --git a/se/se_epub.py b/se/se_epub.py
index 06857dce..9f8a001e 100644
--- a/se/se_epub.py
+++ b/se/se_epub.py
@@ -913,6 +913,45 @@ def shift_illustrations(self, target_illustration_number: int, step: int = 1) ->
 			with open(file_path, "w", encoding="utf-8") as file:
 				file.write(dom.to_string())
 
+	def generate_loi(self, loi_dom: se.easy_xml.EasyXmlTree) -> None:
+		"""
+		Updates the given LoI DOM based on all <figure> elements that contain an
+		<img>. Text from the <figcaption>, if any, is preferred over that from
+		the <img>'s alt attribute.
+		"""
+
+		ols = loi_dom.xpath("/html/body/nav/ol")
+		if len(ols) != 1:
+			raise se.InvalidSeEbookException(f"LoI contains unexpected number of [html]<ol/>[/]: [path][link=file://{self.loi_path}]{self.loi_path}[/][/].")
+
+		etree.strip_elements(ols[0].lxml_element, "li")
+
+		for file_path in self.spine_file_paths:
+			dom = self.get_dom(file_path)
+
+			for figure in dom.xpath("/html/body//figure[@id and img]"):
+				figure_id = figure.get_attr("id")
+
+				text = (figure.xpath("./img")[0].get_attr("alt") or "").strip()
+
+				figcaption = figure.xpath("./figcaption")
+				if figcaption:
+					figcaption_text = figcaption[0].inner_text()
+					# The alt text is probably more useful to the reader in this case.
+					if figcaption_text and not regex.search(r"^[Ff]igure\s+\d+$", figcaption_text):
+						text = figcaption_text
+
+				a = se.easy_xml.EasyXmlElement("<a/>")
+				a.set_text(text or f"Unable to auto-generate LoI text for #{figure_id}.")
+				a.set_attr("href", f"{file_path.name}#{figure_id}")
+
+				p = se.easy_xml.EasyXmlElement("<p/>")
+				p.append(a)
+
+				li = se.easy_xml.EasyXmlElement("<li/>")
+				li.append(p)
+				ols[0].append(li)
+
 	def set_release_timestamp(self) -> None:
 		"""
 		If this ebook has not yet been released, set the first release timestamp in the metadata file.
diff --git a/tests/draft_commands/build-loi/test-1/golden/src/epub/content.opf b/tests/draft_commands/build-loi/test-1/golden/src/epub/content.opf
new file mode 100644
index 00000000..65934188
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/golden/src/epub/content.opf
@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="utf-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" dir="ltr" prefix="se: https://standardebooks.org/vocab/1.0" unique-identifier="uid" version="3.0" xml:lang="en-US">
+	<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+		<dc:identifier id="uid">url:https://standardebooks.org/ebooks/samuel-pepys/the-diary</dc:identifier>
+		<dc:date>2019-08-21T18:40:45Z</dc:date>
+		<meta property="dcterms:modified">2019-08-21T18:40:45Z</meta>
+		<dc:rights>The source text and artwork in this ebook are believed to be in the United States public domain; that is, they are believed to be free of copyright restrictions in the United States. They may still be copyrighted in other countries, so users located outside of the United States must check their local laws before using this ebook. The creators of, and contributors to, this ebook dedicate their contributions to the worldwide public domain via the terms in the [CC0 1.0 Universal Public Domain Dedication](https://creativecommons.org/publicdomain/zero/1.0/).</dc:rights>
+		<dc:publisher id="publisher">Standard Ebooks</dc:publisher>
+		<meta property="file-as" refines="#publisher">Standard Ebooks</meta>
+		<meta property="se:url.homepage" refines="#publisher">https://standardebooks.org</meta>
+		<meta property="role" refines="#publisher" scheme="marc:relators">bkd</meta>
+		<meta property="role" refines="#publisher" scheme="marc:relators">mdc</meta>
+		<meta property="role" refines="#publisher" scheme="marc:relators">pbl</meta>
+		<dc:contributor id="type-designer">The League of Moveable Type</dc:contributor>
+		<meta property="file-as" refines="#type-designer">League of Moveable Type, The</meta>
+		<meta property="se:url.homepage" refines="#type-designer">https://www.theleagueofmoveabletype.com</meta>
+		<meta property="role" refines="#type-designer" scheme="marc:relators">tyd</meta>
+		<link href="http://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-aa" rel="dcterms:conformsTo"/>
+		<meta property="a11y:certifiedBy">Standard Ebooks</meta>
+		<meta property="schema:accessMode">textual</meta>
+		<meta property="schema:accessModeSufficient">textual</meta>
+		<meta property="schema:accessibilityFeature">readingOrder</meta>
+		<meta property="schema:accessibilityFeature">structuralNavigation</meta>
+		<meta property="schema:accessibilityFeature">tableOfContents</meta>
+		<meta property="schema:accessibilityHazard">none</meta>
+		<meta property="schema:accessibilitySummary">This publication conforms to WCAG 2.2 Level AA.</meta>
+		<link href="onix.xml" media-type="application/xml" properties="onix" rel="record"/>
+		<dc:title id="title">The Diary</dc:title>
+		<meta property="file-as" refines="#title">Diary, The</meta>
+		<dc:subject id="subject-1">Pepys, Samuel, 1633-1703 -- Diaries</dc:subject>
+		<dc:subject id="subject-2">Cabinet officers -- Great Britain -- Diaries</dc:subject>
+		<dc:subject id="subject-3">Diarists -- Great Britain -- Diaries</dc:subject>
+		<dc:subject id="subject-4">Great Britain -- Social life and customs -- 17th century -- Sources</dc:subject>
+		<dc:subject id="subject-5">Great Britain -- History -- Charles II, 1660-1685 -- Sources</dc:subject>
+		<meta property="authority" refines="#subject-1">LCSH</meta>
+		<meta property="term" refines="#subject-1">Unknown</meta>
+		<meta property="authority" refines="#subject-2">LCSH</meta>
+		<meta property="term" refines="#subject-2">sh2008100004</meta>
+		<meta property="authority" refines="#subject-3">LCSH</meta>
+		<meta property="term" refines="#subject-3">Unknown</meta>
+		<meta property="authority" refines="#subject-4">LCSH</meta>
+		<meta property="term" refines="#subject-4">sh2007100274</meta>
+		<meta property="authority" refines="#subject-5">LCSH</meta>
+		<meta property="term" refines="#subject-5">sh2008115250</meta>
+		<meta property="se:subject">Autobiography</meta>
+		<meta property="se:subject">Nonfiction</meta>
+		<dc:description id="description">The diary of a man living in London in the 17th century.</dc:description>
+		<meta id="long-description" property="se:long-description" refines="#description">
+			&lt;p&gt;Pepys’ &lt;i&gt;Diary&lt;/i&gt; is an incredibly frank decade-long snapshot of the life of an up and coming naval administrator in mid-17th century London. In it he describes everything from battles against the Dutch and the intrigues of court, down to the plays he saw, his marital infidelities, and the quality of the meat provided for his supper. His observations have proved invaluable in establishing an accurate record of the daily life of the people of London of that period.&lt;/p&gt;
+			&lt;p&gt;Pepys eventually stopped writing his diary due to progressively worse eyesight, a condition he feared. He did consider employing an amanuensis to transcribe future entries for him, but worried that the content he wanted written would be too personal. Luckily for Pepys, his eyesight difficulties never progressed to blindness and he was able to go on to become both a Member of Parliament and the President of the Royal Society.&lt;/p&gt;
+			&lt;p&gt;After Pepys’ death he left his large library of books and manuscripts first to his nephew, which was then passed on to Magdalene College, Cambridge, where it survives to this day. The diary, originally written in a shorthand, was included in this trove and was eventually deciphered in the early 19th century, and published by Lord Baybrooke in 1825. This early release censored large amounts of the text, and it was only in the 1970s that an uncensored version was published. Presented here is the 1893 edition, which restores the majority of the originally censored content but omits “a few passages which cannot possibly be printed.” The rich collection of endnotes serve to further illustrate the lives of the people Pepys meets and the state of England’s internal politics and international relations at the time.&lt;/p&gt;
+		</meta>
+		<dc:language>en-GB</dc:language>
+		<dc:source>https://www.gutenberg.org/ebooks/4200</dc:source>
+		<dc:source>https://archive.org/details/diaryofsamuelpep01pepy</dc:source>
+		<meta property="se:production-notes">
+			• Volumes 9 and 10 (appendix and Pepysiana) of the original series have been omitted from the production due to time constraints.
+			• Each diary entry has a time element to start. The datetime attribute is ISO8601 compliant (Gregorian), but the actual dates Pepys uses are Julian, so they don’t appear to match. This is correct.
+			• This date is copied into the `entry-x` id attribute for each diary entry. Unfortunately, this causes linting to fail with leading 0 errors, so we remove those for the id.
+		</meta>
+		<meta property="se:word-count">1209949</meta>
+		<meta property="se:reading-ease.flesch">70.57</meta>
+		<meta property="se:url.encyclopedia.wikipedia">https://en.wikipedia.org/wiki/Samuel_Pepys#The_diary</meta>
+		<meta property="se:url.vcs.github">https://github.com/standardebooks/samuel-pepys_the-diary</meta>
+		<dc:creator id="author">Samuel Pepys</dc:creator>
+		<meta property="file-as" refines="#author">Pepys, Samuel</meta>
+		<meta property="se:url.encyclopedia.wikipedia" refines="#author">https://en.wikipedia.org/wiki/Samuel_Pepys</meta>
+		<meta property="se:url.authority.nacoaf" refines="#author">http://id.loc.gov/authorities/names/n79018796</meta>
+		<meta property="role" refines="#author" scheme="marc:relators">aut</meta>
+		<dc:contributor id="artist">John Hayls</dc:contributor>
+		<meta property="file-as" refines="#artist">Hayls, John</meta>
+		<meta property="se:url.encyclopedia.wikipedia" refines="#artist">https://en.wikipedia.org/wiki/John_Hayls</meta>
+		<meta property="se:url.authority.nacoaf" refines="#artist">http://id.loc.gov/authorities/names/nr94041870</meta>
+		<meta property="role" refines="#artist" scheme="marc:relators">art</meta>
+		<dc:contributor id="editor-1">Henry B. Wheatley</dc:contributor>
+		<meta property="file-as" refines="#editor-1">Wheatley, Henry B.</meta>
+		<meta property="se:name.person.full-name" refines="#editor-1">Henry Benjamin Wheatley</meta>
+		<meta property="se:url.encyclopedia.wikipedia" refines="#editor-1">https://en.wikipedia.org/wiki/Henry_B._Wheatley</meta>
+		<meta property="se:url.authority.nacoaf" refines="#editor-1">http://id.loc.gov/authorities/names/n87860971</meta>
+		<meta property="role" refines="#editor-1" scheme="marc:relators">aft</meta>
+		<meta property="role" refines="#editor-1" scheme="marc:relators">ann</meta>
+		<meta property="role" refines="#editor-1" scheme="marc:relators">aui</meta>
+		<meta property="role" refines="#editor-1" scheme="marc:relators">edt</meta>
+		<meta property="role" refines="#editor-1" scheme="marc:relators">trc</meta>
+		<dc:contributor id="annotator-1">Richard Griffin</dc:contributor>
+		<meta property="display-seq" refines="#annotator-1">0</meta>
+		<meta property="file-as" refines="#annotator-1">Griffin, Richard</meta>
+		<meta property="se:url.encyclopedia.wikipedia" refines="#annotator-1">https://en.wikipedia.org/wiki/Richard_Griffin,_3rd_Baron_Braybrooke</meta>
+		<meta property="se:url.authority.nacoaf" refines="#annotator-1">http://id.loc.gov/authorities/names/n50014973</meta>
+		<meta property="role" refines="#annotator-1" scheme="marc:relators">ann</meta>
+		<meta property="role" refines="#annotator-1" scheme="marc:relators">cns</meta>
+		<meta property="role" refines="#annotator-1" scheme="marc:relators">ill</meta>
+		<dc:contributor id="transcriber-1">David Widger</dc:contributor>
+		<meta property="file-as" refines="#transcriber-1">Widger, David</meta>
+		<meta property="se:url.authority.nacoaf" refines="#transcriber-1">http://id.loc.gov/authorities/names/no2011017869</meta>
+		<meta property="role" refines="#transcriber-1" scheme="marc:relators">trc</meta>
+		<dc:contributor id="producer-1">Robin Whittleton</dc:contributor>
+		<meta property="file-as" refines="#producer-1">Whittleton, Robin</meta>
+		<meta property="se:url.homepage" refines="#producer-1">https://www.robinwhittleton.com</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">bkp</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">blw</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">cov</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">mrk</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">pfr</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">trc</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">tyg</meta>
+		<dc:contributor id="producer-2">David Grigg</dc:contributor>
+		<meta property="file-as" refines="#producer-2">Grigg, David</meta>
+		<meta property="se:url.homepage" refines="#producer-2">https://rightword.com.au/david.php</meta>
+		<meta property="role" refines="#producer-2" scheme="marc:relators">pfr</meta>
+	</metadata>
+	<manifest>
+		<item href="text/chapter-1.xhtml" id="chapter-1.xhtml" media-type="application/xhtml+xml"/>
+		<item href="text/chapter-2.xhtml" id="chapter-2.xhtml" media-type="application/xhtml+xml"/>
+		<item href="text/chapter-3.xhtml" id="chapter-3.xhtml" media-type="application/xhtml+xml"/>
+		<item href="text/loi.xhtml" id="loi.xhtml" media-type="application/xhtml+xml"/>
+		<item href="toc.xhtml" id="toc.xhtml" media-type="application/xhtml+xml" properties="nav"/>
+	</manifest>
+	<spine>
+		<itemref idref="chapter-1.xhtml"/>
+		<itemref idref="chapter-2.xhtml"/>
+		<itemref idref="chapter-3.xhtml"/>
+		<itemref idref="loi.xhtml"/>
+	</spine>
+</package>
diff --git a/tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-1.xhtml b/tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-1.xhtml
new file mode 100644
index 00000000..ab8cbd0a
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-1.xhtml
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/" xml:lang="en-GB">
+	<head>
+		<title>I</title>
+		<link href="../css/core.css" rel="stylesheet" type="text/css"/>
+		<link href="../css/local.css" rel="stylesheet" type="text/css"/>
+	</head>
+	<body epub:type="bodymatter z3998:fiction">
+		<section id="chapter-1" epub:type="chapter">
+			<h2 epub:type="ordinal z3998:roman">I</h2>
+
+			<!-- no ID -->
+			<figure><img/></figure>
+			<!-- no img -->
+			<figure id="f-1"/>
+
+			<!-- these should be included in the LoI; we use deliberately unsorted IDs to ensure that document order is preserved -->
+
+			<!-- various situations in which placeholder text should be used -->
+			<figure id="f-3">
+				<img/>
+			</figure>
+			<figure id="f-2">
+				<img alt=""/>
+			</figure>
+			<figure id="f-4">
+				<img/>
+				<figcaption/>
+			</figure>
+
+			<figure id="f-5">
+				<img alt=" Text comes from trimmed alt. "/>
+			</figure>
+
+			<figure id="f-6">
+				<img/>
+				<figcaption> Text comes from <b>figcaption</b> inner_text. </figcaption>
+			</figure>
+
+			<figure id="f-7">
+				<img alt="f-7-alt"/>
+				<figcaption>Figcaption is preferred over alt.</figcaption>
+			</figure>
+
+			<figure id="f-8">
+				<img alt="Alt is preferred over Figure N figcaption."/>
+				<figcaption> <b> Figure 8 </b> </figcaption>
+			</figure>
+		</section>
+	</body>
+</html>
diff --git a/tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-2.xhtml b/tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-2.xhtml
new file mode 100644
index 00000000..1a38cf14
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-2.xhtml
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/" xml:lang="en-GB">
+	<head>
+		<title>II</title>
+		<link href="../css/core.css" rel="stylesheet" type="text/css"/>
+		<link href="../css/local.css" rel="stylesheet" type="text/css"/>
+	</head>
+	<body epub:type="bodymatter z3998:fiction">
+		<section id="chapter-2" epub:type="chapter">
+			<h2 epub:type="ordinal z3998:roman">II</h2>
+			<p>Here is a figure: <figure id="f-0"><img/></figure></p>
+		</section>
+	</body>
+</html>
diff --git a/tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-3.xhtml b/tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-3.xhtml
new file mode 100644
index 00000000..d320972b
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/golden/src/epub/text/chapter-3.xhtml
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/" xml:lang="en-GB">
+	<head>
+		<title>III</title>
+		<link href="../css/core.css" rel="stylesheet" type="text/css"/>
+		<link href="../css/local.css" rel="stylesheet" type="text/css"/>
+	</head>
+	<body epub:type="bodymatter z3998:fiction">
+		<section id="chapter-3" epub:type="chapter">
+			<h2 epub:type="ordinal z3998:roman">III</h2>
+			<!-- ensure that files with no figures are properly handled -->
+		</section>
+	</body>
+</html>
diff --git a/tests/draft_commands/build-loi/test-1/golden/src/epub/text/loi.xhtml b/tests/draft_commands/build-loi/test-1/golden/src/epub/text/loi.xhtml
new file mode 100644
index 00000000..1c7a95d1
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/golden/src/epub/text/loi.xhtml
@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-US">
+	<head>
+		<title>List of Illustrations</title>
+		<link href="../css/core.css" rel="stylesheet" type="text/css"/>
+		<link href="../css/se.css" rel="stylesheet" type="text/css"/>
+	</head>
+	<body epub:type="backmatter">
+		<nav id="loi" epub:type="loi">
+			<h2 epub:type="title">List of Illustrations</h2>
+			<p>Existing text is retained.</p>
+			<ol>
+				<li>
+					<p>
+						<a href="chapter-1.xhtml#f-3">Unable to auto-generate LoI text for #f-3.</a>
+					</p>
+				</li>
+				<li>
+					<p>
+						<a href="chapter-1.xhtml#f-2">Unable to auto-generate LoI text for #f-2.</a>
+					</p>
+				</li>
+				<li>
+					<p>
+						<a href="chapter-1.xhtml#f-4">Unable to auto-generate LoI text for #f-4.</a>
+					</p>
+				</li>
+				<li>
+					<p>
+						<a href="chapter-1.xhtml#f-5">Text comes from trimmed alt.</a>
+					</p>
+				</li>
+				<li>
+					<p>
+						<a href="chapter-1.xhtml#f-6">Text comes from figcaption inner_text.</a>
+					</p>
+				</li>
+				<li>
+					<p>
+						<a href="chapter-1.xhtml#f-7">Figcaption is preferred over alt.</a>
+					</p>
+				</li>
+				<li>
+					<p>
+						<a href="chapter-1.xhtml#f-8">Alt is preferred over Figure N figcaption.</a>
+					</p>
+				</li>
+				<li>
+					<p>
+						<a href="chapter-2.xhtml#f-0">Unable to auto-generate LoI text for #f-0.</a>
+					</p>
+				</li>
+			</ol>
+		</nav>
+	</body>
+</html>
diff --git a/tests/draft_commands/build-loi/test-1/golden/src/epub/toc.xhtml b/tests/draft_commands/build-loi/test-1/golden/src/epub/toc.xhtml
new file mode 100644
index 00000000..7f47198a
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/golden/src/epub/toc.xhtml
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-US">
+	<head>
+		<title>Table of Contents</title>
+	</head>
+	<body epub:type="frontmatter">
+		<nav epub:type="toc">
+			<h2 epub:type="title">Table of Contents</h2>
+			<ol>
+				<li>
+					<a href="text/chapter-1.xhtml" epub:type="z3998:roman">I</a>
+				</li>
+			</ol>
+		</nav>
+		<nav epub:type="landmarks">
+			<h2 epub:type="title">Landmarks</h2>
+			<ol>
+				<li>
+					<a href="text/chapter-1.xhtml" epub:type="bodymatter z3998:fiction">Great Expectations</a>
+				</li>
+			</ol>
+		</nav>
+	</body>
+</html>
diff --git a/tests/draft_commands/build-loi/test-1/in/src/epub/content.opf b/tests/draft_commands/build-loi/test-1/in/src/epub/content.opf
new file mode 100644
index 00000000..65934188
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/in/src/epub/content.opf
@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="utf-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" dir="ltr" prefix="se: https://standardebooks.org/vocab/1.0" unique-identifier="uid" version="3.0" xml:lang="en-US">
+	<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+		<dc:identifier id="uid">url:https://standardebooks.org/ebooks/samuel-pepys/the-diary</dc:identifier>
+		<dc:date>2019-08-21T18:40:45Z</dc:date>
+		<meta property="dcterms:modified">2019-08-21T18:40:45Z</meta>
+		<dc:rights>The source text and artwork in this ebook are believed to be in the United States public domain; that is, they are believed to be free of copyright restrictions in the United States. They may still be copyrighted in other countries, so users located outside of the United States must check their local laws before using this ebook. The creators of, and contributors to, this ebook dedicate their contributions to the worldwide public domain via the terms in the [CC0 1.0 Universal Public Domain Dedication](https://creativecommons.org/publicdomain/zero/1.0/).</dc:rights>
+		<dc:publisher id="publisher">Standard Ebooks</dc:publisher>
+		<meta property="file-as" refines="#publisher">Standard Ebooks</meta>
+		<meta property="se:url.homepage" refines="#publisher">https://standardebooks.org</meta>
+		<meta property="role" refines="#publisher" scheme="marc:relators">bkd</meta>
+		<meta property="role" refines="#publisher" scheme="marc:relators">mdc</meta>
+		<meta property="role" refines="#publisher" scheme="marc:relators">pbl</meta>
+		<dc:contributor id="type-designer">The League of Moveable Type</dc:contributor>
+		<meta property="file-as" refines="#type-designer">League of Moveable Type, The</meta>
+		<meta property="se:url.homepage" refines="#type-designer">https://www.theleagueofmoveabletype.com</meta>
+		<meta property="role" refines="#type-designer" scheme="marc:relators">tyd</meta>
+		<link href="http://www.idpf.org/epub/a11y/accessibility-20170105.html#wcag-aa" rel="dcterms:conformsTo"/>
+		<meta property="a11y:certifiedBy">Standard Ebooks</meta>
+		<meta property="schema:accessMode">textual</meta>
+		<meta property="schema:accessModeSufficient">textual</meta>
+		<meta property="schema:accessibilityFeature">readingOrder</meta>
+		<meta property="schema:accessibilityFeature">structuralNavigation</meta>
+		<meta property="schema:accessibilityFeature">tableOfContents</meta>
+		<meta property="schema:accessibilityHazard">none</meta>
+		<meta property="schema:accessibilitySummary">This publication conforms to WCAG 2.2 Level AA.</meta>
+		<link href="onix.xml" media-type="application/xml" properties="onix" rel="record"/>
+		<dc:title id="title">The Diary</dc:title>
+		<meta property="file-as" refines="#title">Diary, The</meta>
+		<dc:subject id="subject-1">Pepys, Samuel, 1633-1703 -- Diaries</dc:subject>
+		<dc:subject id="subject-2">Cabinet officers -- Great Britain -- Diaries</dc:subject>
+		<dc:subject id="subject-3">Diarists -- Great Britain -- Diaries</dc:subject>
+		<dc:subject id="subject-4">Great Britain -- Social life and customs -- 17th century -- Sources</dc:subject>
+		<dc:subject id="subject-5">Great Britain -- History -- Charles II, 1660-1685 -- Sources</dc:subject>
+		<meta property="authority" refines="#subject-1">LCSH</meta>
+		<meta property="term" refines="#subject-1">Unknown</meta>
+		<meta property="authority" refines="#subject-2">LCSH</meta>
+		<meta property="term" refines="#subject-2">sh2008100004</meta>
+		<meta property="authority" refines="#subject-3">LCSH</meta>
+		<meta property="term" refines="#subject-3">Unknown</meta>
+		<meta property="authority" refines="#subject-4">LCSH</meta>
+		<meta property="term" refines="#subject-4">sh2007100274</meta>
+		<meta property="authority" refines="#subject-5">LCSH</meta>
+		<meta property="term" refines="#subject-5">sh2008115250</meta>
+		<meta property="se:subject">Autobiography</meta>
+		<meta property="se:subject">Nonfiction</meta>
+		<dc:description id="description">The diary of a man living in London in the 17th century.</dc:description>
+		<meta id="long-description" property="se:long-description" refines="#description">
+			&lt;p&gt;Pepys’ &lt;i&gt;Diary&lt;/i&gt; is an incredibly frank decade-long snapshot of the life of an up and coming naval administrator in mid-17th century London. In it he describes everything from battles against the Dutch and the intrigues of court, down to the plays he saw, his marital infidelities, and the quality of the meat provided for his supper. His observations have proved invaluable in establishing an accurate record of the daily life of the people of London of that period.&lt;/p&gt;
+			&lt;p&gt;Pepys eventually stopped writing his diary due to progressively worse eyesight, a condition he feared. He did consider employing an amanuensis to transcribe future entries for him, but worried that the content he wanted written would be too personal. Luckily for Pepys, his eyesight difficulties never progressed to blindness and he was able to go on to become both a Member of Parliament and the President of the Royal Society.&lt;/p&gt;
+			&lt;p&gt;After Pepys’ death he left his large library of books and manuscripts first to his nephew, which was then passed on to Magdalene College, Cambridge, where it survives to this day. The diary, originally written in a shorthand, was included in this trove and was eventually deciphered in the early 19th century, and published by Lord Baybrooke in 1825. This early release censored large amounts of the text, and it was only in the 1970s that an uncensored version was published. Presented here is the 1893 edition, which restores the majority of the originally censored content but omits “a few passages which cannot possibly be printed.” The rich collection of endnotes serve to further illustrate the lives of the people Pepys meets and the state of England’s internal politics and international relations at the time.&lt;/p&gt;
+		</meta>
+		<dc:language>en-GB</dc:language>
+		<dc:source>https://www.gutenberg.org/ebooks/4200</dc:source>
+		<dc:source>https://archive.org/details/diaryofsamuelpep01pepy</dc:source>
+		<meta property="se:production-notes">
+			• Volumes 9 and 10 (appendix and Pepysiana) of the original series have been omitted from the production due to time constraints.
+			• Each diary entry has a time element to start. The datetime attribute is ISO8601 compliant (Gregorian), but the actual dates Pepys uses are Julian, so they don’t appear to match. This is correct.
+			• This date is copied into the `entry-x` id attribute for each diary entry. Unfortunately, this causes linting to fail with leading 0 errors, so we remove those for the id.
+		</meta>
+		<meta property="se:word-count">1209949</meta>
+		<meta property="se:reading-ease.flesch">70.57</meta>
+		<meta property="se:url.encyclopedia.wikipedia">https://en.wikipedia.org/wiki/Samuel_Pepys#The_diary</meta>
+		<meta property="se:url.vcs.github">https://github.com/standardebooks/samuel-pepys_the-diary</meta>
+		<dc:creator id="author">Samuel Pepys</dc:creator>
+		<meta property="file-as" refines="#author">Pepys, Samuel</meta>
+		<meta property="se:url.encyclopedia.wikipedia" refines="#author">https://en.wikipedia.org/wiki/Samuel_Pepys</meta>
+		<meta property="se:url.authority.nacoaf" refines="#author">http://id.loc.gov/authorities/names/n79018796</meta>
+		<meta property="role" refines="#author" scheme="marc:relators">aut</meta>
+		<dc:contributor id="artist">John Hayls</dc:contributor>
+		<meta property="file-as" refines="#artist">Hayls, John</meta>
+		<meta property="se:url.encyclopedia.wikipedia" refines="#artist">https://en.wikipedia.org/wiki/John_Hayls</meta>
+		<meta property="se:url.authority.nacoaf" refines="#artist">http://id.loc.gov/authorities/names/nr94041870</meta>
+		<meta property="role" refines="#artist" scheme="marc:relators">art</meta>
+		<dc:contributor id="editor-1">Henry B. Wheatley</dc:contributor>
+		<meta property="file-as" refines="#editor-1">Wheatley, Henry B.</meta>
+		<meta property="se:name.person.full-name" refines="#editor-1">Henry Benjamin Wheatley</meta>
+		<meta property="se:url.encyclopedia.wikipedia" refines="#editor-1">https://en.wikipedia.org/wiki/Henry_B._Wheatley</meta>
+		<meta property="se:url.authority.nacoaf" refines="#editor-1">http://id.loc.gov/authorities/names/n87860971</meta>
+		<meta property="role" refines="#editor-1" scheme="marc:relators">aft</meta>
+		<meta property="role" refines="#editor-1" scheme="marc:relators">ann</meta>
+		<meta property="role" refines="#editor-1" scheme="marc:relators">aui</meta>
+		<meta property="role" refines="#editor-1" scheme="marc:relators">edt</meta>
+		<meta property="role" refines="#editor-1" scheme="marc:relators">trc</meta>
+		<dc:contributor id="annotator-1">Richard Griffin</dc:contributor>
+		<meta property="display-seq" refines="#annotator-1">0</meta>
+		<meta property="file-as" refines="#annotator-1">Griffin, Richard</meta>
+		<meta property="se:url.encyclopedia.wikipedia" refines="#annotator-1">https://en.wikipedia.org/wiki/Richard_Griffin,_3rd_Baron_Braybrooke</meta>
+		<meta property="se:url.authority.nacoaf" refines="#annotator-1">http://id.loc.gov/authorities/names/n50014973</meta>
+		<meta property="role" refines="#annotator-1" scheme="marc:relators">ann</meta>
+		<meta property="role" refines="#annotator-1" scheme="marc:relators">cns</meta>
+		<meta property="role" refines="#annotator-1" scheme="marc:relators">ill</meta>
+		<dc:contributor id="transcriber-1">David Widger</dc:contributor>
+		<meta property="file-as" refines="#transcriber-1">Widger, David</meta>
+		<meta property="se:url.authority.nacoaf" refines="#transcriber-1">http://id.loc.gov/authorities/names/no2011017869</meta>
+		<meta property="role" refines="#transcriber-1" scheme="marc:relators">trc</meta>
+		<dc:contributor id="producer-1">Robin Whittleton</dc:contributor>
+		<meta property="file-as" refines="#producer-1">Whittleton, Robin</meta>
+		<meta property="se:url.homepage" refines="#producer-1">https://www.robinwhittleton.com</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">bkp</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">blw</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">cov</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">mrk</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">pfr</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">trc</meta>
+		<meta property="role" refines="#producer-1" scheme="marc:relators">tyg</meta>
+		<dc:contributor id="producer-2">David Grigg</dc:contributor>
+		<meta property="file-as" refines="#producer-2">Grigg, David</meta>
+		<meta property="se:url.homepage" refines="#producer-2">https://rightword.com.au/david.php</meta>
+		<meta property="role" refines="#producer-2" scheme="marc:relators">pfr</meta>
+	</metadata>
+	<manifest>
+		<item href="text/chapter-1.xhtml" id="chapter-1.xhtml" media-type="application/xhtml+xml"/>
+		<item href="text/chapter-2.xhtml" id="chapter-2.xhtml" media-type="application/xhtml+xml"/>
+		<item href="text/chapter-3.xhtml" id="chapter-3.xhtml" media-type="application/xhtml+xml"/>
+		<item href="text/loi.xhtml" id="loi.xhtml" media-type="application/xhtml+xml"/>
+		<item href="toc.xhtml" id="toc.xhtml" media-type="application/xhtml+xml" properties="nav"/>
+	</manifest>
+	<spine>
+		<itemref idref="chapter-1.xhtml"/>
+		<itemref idref="chapter-2.xhtml"/>
+		<itemref idref="chapter-3.xhtml"/>
+		<itemref idref="loi.xhtml"/>
+	</spine>
+</package>
diff --git a/tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-1.xhtml b/tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-1.xhtml
new file mode 100644
index 00000000..ab8cbd0a
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-1.xhtml
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/" xml:lang="en-GB">
+	<head>
+		<title>I</title>
+		<link href="../css/core.css" rel="stylesheet" type="text/css"/>
+		<link href="../css/local.css" rel="stylesheet" type="text/css"/>
+	</head>
+	<body epub:type="bodymatter z3998:fiction">
+		<section id="chapter-1" epub:type="chapter">
+			<h2 epub:type="ordinal z3998:roman">I</h2>
+
+			<!-- no ID -->
+			<figure><img/></figure>
+			<!-- no img -->
+			<figure id="f-1"/>
+
+			<!-- these should be included in the LoI; we use deliberately unsorted IDs to ensure that document order is preserved -->
+
+			<!-- various situations in which placeholder text should be used -->
+			<figure id="f-3">
+				<img/>
+			</figure>
+			<figure id="f-2">
+				<img alt=""/>
+			</figure>
+			<figure id="f-4">
+				<img/>
+				<figcaption/>
+			</figure>
+
+			<figure id="f-5">
+				<img alt=" Text comes from trimmed alt. "/>
+			</figure>
+
+			<figure id="f-6">
+				<img/>
+				<figcaption> Text comes from <b>figcaption</b> inner_text. </figcaption>
+			</figure>
+
+			<figure id="f-7">
+				<img alt="f-7-alt"/>
+				<figcaption>Figcaption is preferred over alt.</figcaption>
+			</figure>
+
+			<figure id="f-8">
+				<img alt="Alt is preferred over Figure N figcaption."/>
+				<figcaption> <b> Figure 8 </b> </figcaption>
+			</figure>
+		</section>
+	</body>
+</html>
diff --git a/tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-2.xhtml b/tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-2.xhtml
new file mode 100644
index 00000000..1a38cf14
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-2.xhtml
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/" xml:lang="en-GB">
+	<head>
+		<title>II</title>
+		<link href="../css/core.css" rel="stylesheet" type="text/css"/>
+		<link href="../css/local.css" rel="stylesheet" type="text/css"/>
+	</head>
+	<body epub:type="bodymatter z3998:fiction">
+		<section id="chapter-2" epub:type="chapter">
+			<h2 epub:type="ordinal z3998:roman">II</h2>
+			<p>Here is a figure: <figure id="f-0"><img/></figure></p>
+		</section>
+	</body>
+</html>
diff --git a/tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-3.xhtml b/tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-3.xhtml
new file mode 100644
index 00000000..d320972b
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/in/src/epub/text/chapter-3.xhtml
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/" xml:lang="en-GB">
+	<head>
+		<title>III</title>
+		<link href="../css/core.css" rel="stylesheet" type="text/css"/>
+		<link href="../css/local.css" rel="stylesheet" type="text/css"/>
+	</head>
+	<body epub:type="bodymatter z3998:fiction">
+		<section id="chapter-3" epub:type="chapter">
+			<h2 epub:type="ordinal z3998:roman">III</h2>
+			<!-- ensure that files with no figures are properly handled -->
+		</section>
+	</body>
+</html>
diff --git a/tests/draft_commands/build-loi/test-1/in/src/epub/text/loi.xhtml b/tests/draft_commands/build-loi/test-1/in/src/epub/text/loi.xhtml
new file mode 100644
index 00000000..a9eff8b5
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/in/src/epub/text/loi.xhtml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-US">
+	<head>
+		<title>List of Illustrations</title>
+		<link href="../css/core.css" rel="stylesheet" type="text/css"/>
+		<link href="../css/se.css" rel="stylesheet" type="text/css"/>
+	</head>
+	<body epub:type="backmatter">
+		<nav id="loi" epub:type="loi">
+			<h2 epub:type="title">List of Illustrations</h2>
+			<p>Existing text is retained.</p>
+			<ol>
+				<li><p>Existing entry is removed.</p></li>
+			</ol>
+		</nav>
+	</body>
+</html>
diff --git a/tests/draft_commands/build-loi/test-1/in/src/epub/toc.xhtml b/tests/draft_commands/build-loi/test-1/in/src/epub/toc.xhtml
new file mode 100644
index 00000000..7f47198a
--- /dev/null
+++ b/tests/draft_commands/build-loi/test-1/in/src/epub/toc.xhtml
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="utf-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-US">
+	<head>
+		<title>Table of Contents</title>
+	</head>
+	<body epub:type="frontmatter">
+		<nav epub:type="toc">
+			<h2 epub:type="title">Table of Contents</h2>
+			<ol>
+				<li>
+					<a href="text/chapter-1.xhtml" epub:type="z3998:roman">I</a>
+				</li>
+			</ol>
+		</nav>
+		<nav epub:type="landmarks">
+			<h2 epub:type="title">Landmarks</h2>
+			<ol>
+				<li>
+					<a href="text/chapter-1.xhtml" epub:type="bodymatter z3998:fiction">Great Expectations</a>
+				</li>
+			</ol>
+		</nav>
+	</body>
+</html>
diff --git a/tests/stdout_commands/help/test-1/golden/help-test-1-out.txt b/tests/stdout_commands/help/test-1/golden/help-test-1-out.txt
index 99d4b879..bdda74c9 100644
--- a/tests/stdout_commands/help/test-1/golden/help-test-1-out.txt
+++ b/tests/stdout_commands/help/test-1/golden/help-test-1-out.txt
@@ -3,6 +3,7 @@ british2american
 build
 build-ids
 build-images
+build-loi
 build-manifest
 build-spine
 build-title
diff --git a/tests/stdout_commands/help/test-2/golden/help-test-2-out.txt b/tests/stdout_commands/help/test-2/golden/help-test-2-out.txt
index c6db58a5..cd8ca109 100644
--- a/tests/stdout_commands/help/test-2/golden/help-test-2-out.txt
+++ b/tests/stdout_commands/help/test-2/golden/help-test-2-out.txt
@@ -4,9 +4,9 @@ The entry point for the Standard Ebooks toolset.
 
 positional arguments:
   COMMAND        one of: british2american build build-ids build-images build-
-                 manifest build-spine build-title build-toc clean compare-
-                 versions create-draft css-select dec2roman extract-ebook
-                 find-mismatched-dashes find-mismatched-diacritics find-
+                 loi build-manifest build-spine build-title build-toc clean
+                 compare-versions create-draft css-select dec2roman extract-
+                 ebook find-mismatched-dashes find-mismatched-diacritics find-
                  unusual-characters help hyphenate interactive-replace lint
                  make-url-safe modernize-spelling prepare-release recompose-
                  epub renumber-endnotes roman2dec semanticate shift-endnotes
diff --git a/tests/test_draft_commands.py b/tests/test_draft_commands.py
index 1d06ba0b..16b23828 100644
--- a/tests/test_draft_commands.py
+++ b/tests/test_draft_commands.py
@@ -1,8 +1,8 @@
 """
 Tests for commands that transform epub text files and only need a draft ebook to run.
 This includes:
-	british2american, build-title, clean, hyphenate, modernize-spelling,
-	semanticate, typogrify
+	british2american, build-loi, build-title, clean, hyphenate,
+	modernize-spelling, semanticate, typogrify
 """
 
 import os