[Next Project] Hume, Treatise of Human Nature

[Bennett Helm]

For my next project, I'd like to do Hume's Treatise of Human Nature.

Here are original page scans for the Selby-Bigge edition (1896), which is pretty much the standard edition for the Treatise.

Here is the Project Gutenberg page.

Assuming I get the go-ahead to do this, I have one question to start with concerning how to break this into files.

Hume divides his text into "Books", "Parts", and "Sections". There really is no text to any "book" or "part" except what is contained in the "sections" (though each book, part, and section has a name). Part numbering restarts with each book, and section numbering restarts with each part. 

So far what I've done is to split the text into these files (ordering them as they appear in the text):

• advertisement.xhtml
• introduction.xhtml
• book-1.xhtml
• part-1-1.xhtml
• part-1-2.xhtml
• part-1-3.xhtml
• part-1-4.xhtml
• book-2.xhtml
• part-2-1.xhtml
• part-2-2.xhtml
• part-2-3.xhtml
• book-3.xhtml
• part-3-1.xhtml
• part-3-2.xhtml
• part-3-3.xhtml

These "Parts" average about 55 pages (11 parts in total over 620 pages); the longest is over 100 pages, and the shortest is about 20. By contrast, there are 90 sections in total.

So is this an appropriate way to divide up the work? Or should I divide it further into sections, resulting in files like "section-2-4-1.xhtml" for Book II, Part IV, Section 1? The reason I didn't split any further is that, whereas each Book and Part has a title, none of them has any text except for what is contained in the Sections. So "book-*.xhtml" is essentially a stub, containing just the title. It seemed silly to have a bunch of "part-*-*.xhtml" files that also contain just titles. ... And having a part with about 100 pages didn't seem outlandish.

Bennett

[Vince]

What you’re describing (each section in a file) is the standard way we structure three-level books. It’s no sillier for a part to be just the part # and title than it is for the book file to be just the book # and title; that’s just the way the book is structured. See, e.g. War and Peace (whose top-level has only a #, no title), Les Misérables, etc.

[Bennett Helm]

Ok, so I've split it up into books, parts, and sections. One further question about this: what is the appropriate "epub:type" for each of these? Here's what I have:

Book --> epub:type="volume"

Part --> epub:type="part"

Section --> epub:type="chapter"

Does that sound right? (I see War and Peace does it differently, mapping Book onto "division". But as I read the spec, this is wrong: a division is "a substructure of a part", rather than a superstructure.)

I'm still waiting on the official go-ahead before I do more.

Bennett

[Alex Cabal]

Can you send a link to your repo, so we can assign a manager and
reviewer who will answer these questions?

On 7/2/26 7:40 AM, Bennett Helm wrote:
> Ok, so I've split it up into books, parts, and sections. One further
> question about this: what is the appropriate "epub:type" for each of
> these? Here's what I have:
>
> Book --> epub:type="volume"
> Part --> epub:type="part"
> Section --> epub:type="chapter"
>

> Does that sound right? (I see /War and Peace/ does it differently,
> mapping Book onto "division". But as I read the spec <https://
> www.w3.org/TR/epub-ssv-11/#sec-divisions>, this is wrong: a division is

> "a substructure of a part", rather than a superstructure.)
>
> I'm still waiting on the official go-ahead before I do more.
>
> Bennett
>
> On Wednesday, July 1, 2026 at 7:39:42 PM UTC-4 Vince wrote:
>
> What you’re describing (each section in a file) is the standard way
> we structure three-level books. It’s no sillier for a part to be
> just the part # and title than it is for the book file to be just
> the book # and title; that’s just the way the book is structured.

> See, e.g. /War and Peace/ (whose top-level has only a #, no
> title), /Les Misérables/, etc.

>
>
>> On Jul 1, 2026, at 3:33 PM, Bennett Helm <bennet...@gmail.com> wrote:
>>

>> For my next project, I'd like to do Hume's /Treatise of Human Nature/.
>>
>> Here are original page scans <https://archive.org/details/0213-bk/

>> > for the Selby-Bigge edition (1896), which is pretty much the

>> standard edition for the /Treatise/.
>>
>> Here is the Project Gutenberg page <https://www.gutenberg.org/
>> ebooks/4705>.

>>
>> Assuming I get the go-ahead to do this, I have one question to
>> start with concerning how to break this into files.
>>
>> Hume divides his text into "Books", "Parts", and "Sections". There
>> really is no text to any "book" or "part" except what is contained
>> in the "sections" (though each book, part, and section has a
>> name). Part numbering restarts with each book, and section
>> numbering restarts with each part.
>>
>> So far what I've done is to split the text into these files
>> (ordering them as they appear in the text):
>>

>> * advertisement.xhtml
>> * introduction.xhtml
>> * book-1.xhtml
>> * part-1-1.xhtml
>> * part-1-2.xhtml
>> * part-1-3.xhtml
>> * part-1-4.xhtml
>> * book-2.xhtml
>> * part-2-1.xhtml
>> * part-2-2.xhtml
>> * part-2-3.xhtml
>> * book-3.xhtml
>> * part-3-1.xhtml
>> * part-3-2.xhtml
>> * part-3-3.xhtml

>>
>> These "Parts" average about 55 pages (11 parts in total over 620
>> pages); the longest is over 100 pages, and the shortest is about
>> 20. By contrast, there are 90 sections in total.
>>
>> So is this an appropriate way to divide up the work? Or should I
>> divide it further into sections, resulting in files like
>> "section-2-4-1.xhtml" for Book II, Part IV, Section 1? The reason
>> I didn't split any further is that, whereas each Book and Part has
>> a title, none of them has any text except for what is contained in
>> the Sections. So "book-*.xhtml" is essentially a stub, containing
>> just the title. It seemed silly to have a bunch of "part-*-

>> *.xhtml" files that /also/ contain just titles. ... And having a

>> part with about 100 pages didn't seem outlandish.
>

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com
> <mailto:standardebook...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/
> standardebooks/a3ecc052-f9a7-4898-a931-f7108ffe7c7fn%40googlegroups.com
> <https://groups.google.com/d/msgid/standardebooks/a3ecc052-f9a7-4898-
> a931-f7108ffe7c7fn%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Bennett Helm]

Here it is: https://github.com/bwhelm/Hume_Treatise-of-Human-Nature/

Bennett

[Alex Cabal]

OK, Emma will manage with Lukas reviewing.

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com
> <mailto:standardebook...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/5e917caa-f0c2-4780-b8d5-b4608a1cf8ecn%40googlegroups.com
> <https://groups.google.com/d/msgid/standardebooks/5e917caa-f0c2-4780-
> b8d5-b4608a1cf8ecn%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Emma Sweeney]

Use epub:type="division" for the book files.

Emma

[Bennett Helm]

Ok -- done. Thanks!

[Bennett Helm]

I've gotten through Step 20 of the step-by-step guide. (Pushed to github.) Now on to linting, and I have a question.

This book is divided into Books, Parts, and Sections, each numbered and with a descriptive name. Thus, in the above ToC under "6. A Treatise of Human Nature", Hume has: "Book I: Of the Understanding", "Part I: Of Ideas ...", and "Section I: Of the Origin ...".  Consequently, I've included these in each file as follows (for book-1.xhtml):

<section id="book-1" epub:type="division">
<hgroup>
<h2>
<span epub:type="se:label">Book</span>
<span epub:type="z3998:roman">I</span>
</h2>
<p epub:type="title">Of the Understanding</p>
</hgroup>
</section>

Running `se build-toc .` creates the ToC like this:

1. Titlepage
2. Imprint
3. Epigraph
4. Advertisement
5. Introduction
6. A Treatise of Human Nature
   1. Of the Understanding
      1. Of Ideas, Their Origin, Composition, Connection, Abstraction, Etc
         1. Of the Origin of Our Ideas
         2. Division of the Subject

[Etc.]

But running `se lint .` throws errors: "Heading not found in the ToC" because `se lint` is expecting the "Book I" to be a part of the title, but `se build-toc` doesn't include it. What's the remedy here? (What am I doing wrong?)

Bennett

[Emma Sweeney]

The title formatting isn't quite correct. You're missing `z3998:ordinal` for the roman numerals. See SEMoS 7.2.10.6 for an example.

Also, the page scans have the section titles spelled out.

Emma

[Bennett Helm]

Thanks -- I missed that. And I've spelled out "Section" now.

One more question. The PG transcription sometimes identified italics or small-caps by using all-caps text. But there are many, many (hundreds, likely over 1,000) of italics and all-caps that they missed. Should I try to catch all of these when proofreading?

Bennett

[Emma Sweeney]

Sure, you can restore formatting during the proofreading step. It just depends on whether it's easier for you to check the formatting and text separately or at the same time.

Emma

[Bennett Helm]

Artwork: I'd like to use Jean Siméon Chardin, "Soap Bubbles" (1733/34?) <https://www.nga.gov/artworks/994-soap-bubbles>. The National Gallery identifies it as CC0. (I'm attaching a crop at 1400x2100.)

Will that work?

Bennett

[Emma Sweeney]

Looks good! I've added it to the art DB.

Emma

[Bennett Helm]

I have a question about footnote placement. Hume places footnotes in what to us are odd places:

1. at the ends of sentences or clauses, but before the final punctuation: "... end of sentence<fn>." or "... end of clause<fn>; ...".
2. before words: "WORD1 <fn>WORD2"
3. between words: "WORD1 <fn> WORD2" -- with spaces before and after the footnote.

For case (1), I have placed the footnotes after the punctuation. For case (2), I have left the footnote where it is, even though we would find it proper to have the footnote after the word. For case (3), I have moved the footnote before the second word, to assimilate it to case (2), which is much more common. (It seems to me that case (3) isn't intentional but is an artifact of typesetting.)

I am hesitant to change Hume's text much, but I wonder: does this seem right, or for cases (2) and (3) should I put the footnote after WORD2, as would be natural for us?

Bennett

[Emma Sweeney]

Please send examples of each case in the text.

Emma

[Bennett Helm]

Example of (1): p. 2: "... mark the difference<fn>."

Example of (2): p. 69: "There are <fn>seven ..."

Example of (3): p. 17: "... A <fn> great philosopher ..."

There are many examples of each; very few instances fit how we would place footnotes.

Bennett

[Emma Sweeney]

That all seems fine.

I did find a 1911 edition of A Treatise of Human Nature where the footnote locations are adjusted. Do you think the placement in this edition makes more sense than in the 1739 edition? If so, you could adjust the endnotes to match the 1911 edition.

Emma

[Bennett Helm]

Hume's book was originally published in 1739, though the Selby-Bigge edition I'm using and that Project Gutenberg uses (which is the standard edition for philosophers — used in most secondary literature that I'm familiar with) was published in 1896 and uses the 1739 text, lightly edited. Because that's the standard, I don't want to deviate too much from it (though the transcription modernizes many spellings and contractions [such as " ’tis" -> "it is"], which I have kept).

As I indicated, my inclination is to assimilate case (3) ("text <fn> text") to case (2) ("text <fn>text"), and adjust case (1) ("text<fn>.") to put the footnote after the final punctuation.

Ultimately, though, it's an editorial decision, so I'll defer to you. Let me know.

Bennett

[Emma Sweeney]

I don't know the text very well, so the decision to follow the Selby-Bigge edition is fine.

Emma

[Alex Cabal]

We should adjust noterefs to appear after their references in all cases,
and after punctuation. The 1911 edition is a fine reference if it does
that in all cases. Otherwise I think it's pretty easy to make a common
sense judgement about what the noteref refers to and move it after that
reference. For example 2 what the 1911 edition did looks fine, for
example 3 you could put the noteref after `a great philosopher`.

On 7/19/26 3:56 PM, Emma Sweeney wrote:
> I don't know the text very well, so the decision to follow the Selby-
> Bigge edition is fine.
>
> Emma
> On Sunday, July 19, 2026 at 3:36:39 PM UTC-4 Bennett Helm wrote:
>
> Hume's book was originally published in 1739, though the Selby-Bigge
> edition I'm using and that Project Gutenberg uses (which is the
> standard edition for philosophers — used in most secondary
> literature that I'm familiar with) was published in 1896 and uses
> the 1739 text, lightly edited. Because that's the standard, I don't
> want to deviate too much from it (though the transcription
> modernizes many spellings and contractions [such as " ’tis" -> "it
> is"], which I have kept).
>
> As I indicated, my inclination is to assimilate case (3) ("text <fn>
> text") to case (2) ("text <fn>text"), and adjust case (1)
> ("text<fn>.") to put the footnote after the final punctuation.
>
> Ultimately, though, it's an editorial decision, so I'll defer to
> you. Let me know.
>
> Bennett
>
> On Sunday, July 19, 2026 at 1:44:07 PM UTC-4 Emma Sweeney wrote:
>
> That all seems fine.
>

> I did find a 1911 edition of A <https://archive.org/details/
> atreatiseonhuman00humeuoft/page/n7/mode/2up>Treatise of Human
> Nature <https://archive.org/details/atreatiseonhuman00humeuoft/
> page/n7/mode/2up> where the footnote locations are adjusted. Do

> you think the placement in this edition makes more sense than in
> the 1739 edition? If so, you could adjust the endnotes to match
> the 1911 edition.
>
> Emma
> On Sunday, July 19, 2026 at 12:02:10 AM UTC-4 Bennett Helm wrote:
>

> Example of (1): p. 2 <https://archive.org/details/0213-bk/
> page/2/mode/1up>: "... mark the difference<fn>."
>
> Example of (2): p. 69 <https://archive.org/details/0213-bk/
> page/69/mode/1up>: "There are <fn>seven ..."
>
> Example of (3): p. 17 <https://archive.org/details/0213-bk/
> page/17/mode/1up>: "... A <fn> great philosopher ..."

>
> There are many examples of each; very few instances fit how
> we would place footnotes.
>
> Bennett
>
> On Saturday, July 18, 2026 at 11:13:48 PM UTC-4 Emma Sweeney
> wrote:
>
> Please send examples of each case in the text.
>
> Emma
> On Saturday, July 18, 2026 at 10:51:35 PM UTC-4 Bennett
> Helm wrote:
>
> I have a question about footnote placement. Hume
> places footnotes in what to us are odd places:
>

> 1. at the ends of sentences or clauses, but before

> the final punctuation: "... end of
> sentence<fn>." or "... end of clause<fn>; ...".

> 2. before words: "WORD1 <fn>WORD2"
> 3. between words: "WORD1 <fn> WORD2" -- with spaces

> before and after the footnote.
>
> For case (1), I have placed the footnotes after the
> punctuation. For case (2), I have left the footnote
> where it is, even though we would find it proper to

> have the footnote /after/ the word. For case (3), I

> have moved the footnote before the second word, to
> assimilate it to case (2), which is much more
> common. (It seems to me that case (3) isn't
> intentional but is an artifact of typesetting.)
>
> I am hesitant to change Hume's text much, but I
> wonder: does this seem right, or for cases (2) and
> (3) should I put the footnote after WORD2, as would
> be natural for us?
>
> Bennett
>

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com
> <mailto:standardebook...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/97c42026-7c6e-412b-82ea-73061e246fb9n%40googlegroups.com
> <https://groups.google.com/d/msgid/
> standardebooks/97c42026-7c6e-412b-82ea-73061e246fb9n%40googlegroups.com?
> utm_medium=email&utm_source=footer>.

[Bennett Helm]

Ok -- will do.

Bennett

[Bennett Helm]

After 2 rounds of proofreading, I'm getting close. A few questions:

1. I have a `production-notes.md` file, though I'm uncertain where the file goes. Is it at the root of the project? in `src/epub/`? somewhere else? Do I need to put anything into the metadata to indicate that there is a production notes file?
2. I am uncertain whether the "Introduction" should be identified as front matter or as main matter. The Selby-Bigge edition has it as front matter, but the 1911 edition Emma linked to above has it as main matter. Currently I have it as front matter, but when I build the ebook and open it in the Apple Books app, the book automatically opens to the first page of the main matter, thus skipping the Introduction. I'm not sure how common that is as a behavior of ebook apps, but since this is a substantive introduction, that would seem to be unwanted behavior. Thoughts?

Otherwise, I just have the descriptions to write before it's ready for review.

Bennett

[Emma Sweeney]

1. The production-notes.md file is placed in the ebook root. You don't need to do anything else.

2. This looks like frontmatter. I never use the Apple Books app, so I am unsure how it normally behaves. Have you tested the ebook in Calibre or other ereader programs?

Emma

[Alex Cabal]

Introductions are always frontmatter. We can't control how ebook readers
behave.

On 7/31/26 12:42 PM, Emma Sweeney wrote:
> 1. The production-notes.md file is placed in the ebook root. You don't
> need to do anything else.
>
> 2. This looks like frontmatter. I never use the Apple Books app, so I am
> unsure how it normally behaves. Have you tested the ebook in Calibre or
> other ereader programs?
>
>
> Emma
> On Thursday, July 30, 2026 at 9:16:44 AM UTC-4 Bennett Helm wrote:
>
> After 2 rounds of proofreading, I'm getting close. A few questions:
>

> 1. I have a `production-notes.md` file, though I'm uncertain where

> the file goes. Is it at the root of the project? in `src/epub/`?
> somewhere else? Do I need to put anything into the metadata to
> indicate that there is a production notes file?

> 2. I am uncertain whether the "Introduction" should be identified

> details/ <https://archive.org/details/>

> > atreatiseonhuman00humeuoft/page/n7/mode/2up>Treatise of
> Human
> > Nature <https://archive.org/details/

> atreatiseonhuman00humeuoft/ <https://archive.org/details/
> atreatiseonhuman00humeuoft/>

> > page/n7/mode/2up> where the footnote locations are
> adjusted. Do
> > you think the placement in this edition makes more sense
> than in
> > the 1739 edition? If so, you could adjust the endnotes to
> match
> > the 1911 edition.
> >
> > Emma
> > On Sunday, July 19, 2026 at 12:02:10 AM UTC-4 Bennett
> Helm wrote:
> >
> > Example of (1): p. 2 <https://archive.org/details/0213-

> bk/ <https://archive.org/details/0213-bk/>

> > page/2/mode/1up>: "... mark the difference<fn>."
> >
> > Example of (2): p. 69 <https://archive.org/details/0213-

> bk/ <https://archive.org/details/0213-bk/>

> > page/69/mode/1up>: "There are <fn>seven ..."
> >
> > Example of (3): p. 17 <https://archive.org/details/0213-

> bk/ <https://archive.org/details/0213-bk/>

> d/msgid/ <https://groups.google.com/d/msgid/>
> >
> standardebooks/97c42026-7c6e-412b-82ea-73061e246fb9n%40googlegroups.com <http://40googlegroups.com>
> > <https://groups.google.com/d/msgid/ <https://
> groups.google.com/d/msgid/>
> >
> standardebooks/97c42026-7c6e-412b-82ea-73061e246fb9n%40googlegroups.com <http://40googlegroups.com>?
> > utm_medium=email&utm_source=footer>.

>
> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com
> <mailto:standardebook...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/e093ff48-dd35-47cf-8441-6052dd709ecfn%40googlegroups.com
> <https://groups.google.com/d/msgid/standardebooks/e093ff48-
> dd35-47cf-8441-6052dd709ecfn%40googlegroups.com?
> utm_medium=email&utm_source=footer>.

[Robin Whittleton]

Oh, I assumed readers did this because we don’t put the frontmatter in the landmarks, causing them to jump to the first landmark which is the bodymatter. Maybe I’m wrong?

-Robin

> To unsubscribe from this group and stop receiving emails from it, send an email to standardebook...@googlegroups.com.
> To view this discussion visit https://groups.google.com/d/msgid/standardebooks/fcc85b4d-1cf0-4c9b-83c5-cc53faa48ce9%40standardebooks.org.

[Vince]

I believe you’re correct. I’ve experimented in the past with my own (non-SE) books, and if the frontmatter is put in the landmarks, that’s where the book opens. I assumed we did that (left out the frontmatter from the landmarks) on purpose.

[Alex Cabal]

We exclude almost everything based on the epub spec:
https://www.w3.org/TR/epub-34/#sec-nav-landmarks

> It is advised to limit the number of items defined in the landmarks
nav to only items that a reading system is likely to use in its user
interface. The element is not meant to repeat the table of contents.

In practice this means bodymatter and reference-related items like LoI,
endnotes, glossary, etc. In our case ToC is also excluded because it's
not in the spine.

[Vince]

I’m not arguing for or against, but the spec not only doesn't preclude us from including a frontmatter item, it specifically says it’s OK to do so if it’s something “a reading system is likely to use.” And since (at least some) reading systems do use the landmarks to determine where the book opens the first time, then if that’s where we want the book to open, we should include the item. If it’s not, then we shouldn’t.

[Alex Cabal]

From memory I believe ibooks just opens to bodymatter in the landmarks
no matter what. If you were to put frontmatter in landmarks, then it
would still just open in bodymatter. Though I haven't tested that just now.

On 7/31/26 2:07 PM, Vince wrote:
> I’m not arguing for or against, but the spec not only doesn't preclude
> us from including a frontmatter item, it specifically says it’s OK to do
> so if it’s something “a reading system is likely to use.” And since (at

> least some) reading systems /do/ use the landmarks to determine where

> the book opens the first time, then if that’s where we want the book to
> open, we should include the item. If it’s not, then we shouldn’t.
>
>> On Jul 31, 2026, at 1:46 PM, 'Alex Cabal' via Standard Ebooks
>> <standar...@googlegroups.com> wrote:
>>
>> We exclude almost everything based on the epub spec:https://

>> www.w3.org/TR/epub-34/#sec-nav-landmarks <https://www.w3.org/TR/
>> epub-34/#sec-nav-landmarks>

>>
>> > It is advised to limit the number of items defined in the landmarks nav to only items that a reading system is likely to use in its user interface. The element is not meant to repeat the table of contents.
>>
>> In practice this means bodymatter and reference-related items like
>> LoI, endnotes, glossary, etc. In our case ToC is also excluded because
>> it's not in the spine.
>>
>> On 7/31/26 1:16 PM, Vince wrote:
>>> I believe you’re correct. I’ve experimented in the past with my own
>>> (non-SE) books, and if the frontmatter is put in the landmarks,
>>> that’s where the book opens. I assumed we did that (left out the
>>> frontmatter from the landmarks) on purpose.
>>>> On Jul 31, 2026, at 12:57 PM, Robin Whittleton <ro...@reala.net> wrote:
>>>>
>>>> Oh, I assumed readers did this because we don’t put the frontmatter
>>>> in the landmarks, causing them to jump to the first landmark which
>>>> is the bodymatter. Maybe I’m wrong?
>>>>
>>>> -Robin
>>>>
>>>>> On 31 Jul 2026, at 19:54, 'Alex Cabal' via Standard Ebooks
>>>>> <standar...@googlegroups.com> wrote:
>>>>>
>>>>> Introductions are always frontmatter. We can't control how ebook
>>>>> readers behave.
>

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com
> <mailto:standardebook...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/16E3675A-1F3C-45AD-A0DD-C77186949E5C%40letterboxes.org
> <https://groups.google.com/d/msgid/standardebooks/16E3675A-1F3C-45AD-
> A0DD-C77186949E5C%40letterboxes.org?utm_medium=email&utm_source=footer>.

[Vince]

As I said below, "I’ve experimented in the past with my own (non-SE) books, and if the frontmatter is put in the landmarks, that’s where the book opens.” I just tested it again and confirmed it. But that’s just Apple Books; I don’t own a reader, so have no idea what others do.

But, as I also said, I’m not arguing for or against, just that the spec doesn’t prevent us from doing so. Some frontmatter isn’t worth opening to, there’s no way for the tool to know the difference, and I’m pretty sure we don't want to be manually adjusting the landmarks. So either we always put it there (if frontmatter* is present) and have it open to non-interesting frontmatter, or we leave things as they are.

*And by “frontmatter,” I would assume that would only be something like a preface or introduction, not a dedication or epigraph, which don’t seem (to me) worth opening to.

[Alex Cabal]

I just tried it on iOS 17.7.11 and if I include the following in the
landmarks as the first `<li>`, it still opens to the bodymatter by
default, skipping all the frontmatter:

````
<li>
<a href="text/imprint.xhtml" epub:type="frontmatter imprint">Imprint</a>
</li>
````

>>>> <mailto:standar...@googlegroups.com>> wrote:
>>>>
>>>> We exclude almost everything based on the epub spec:https://

>>>> www.w3.org/TR/epub-34/#sec-nav-landmarks <http://www.w3.org/TR/
>>>> epub-34/#sec-nav-landmarks><https://www.w3.org/TR/ epub-34/#sec-nav-
>>>> landmarks <https://www.w3.org/TR/%20epub-34/#sec-nav-landmarks>>

>>>>
>>>> > It is advised to limit the number of items defined in the
>>>> landmarks nav to only items that a reading system is likely to use
>>>> in its user interface. The element is not meant to repeat the table
>>>> of contents.
>>>>
>>>> In practice this means bodymatter and reference-related items like
>>>> LoI, endnotes, glossary, etc. In our case ToC is also excluded
>>>> because it's not in the spine.
>>>>
>>>> On 7/31/26 1:16 PM, Vince wrote:
>>>>> I believe you’re correct. I’ve experimented in the past with my own
>>>>> (non-SE) books, and if the frontmatter is put in the landmarks,
>>>>> that’s where the book opens. I assumed we did that (left out the
>>>>> frontmatter from the landmarks) on purpose.
>>>>>> On Jul 31, 2026, at 12:57 PM, Robin Whittleton <ro...@reala.net>
>>>>>> wrote:
>>>>>>
>>>>>> Oh, I assumed readers did this because we don’t put the
>>>>>> frontmatter in the landmarks, causing them to jump to the first
>>>>>> landmark which is the bodymatter. Maybe I’m wrong?
>>>>>>
>>>>>> -Robin
>>>>>>
>>>>>>> On 31 Jul 2026, at 19:54, 'Alex Cabal' via Standard Ebooks
>>>>>>> <standar...@googlegroups.com> wrote:
>>>>>>>
>>>>>>> Introductions are always frontmatter. We can't control how ebook
>>>>>>> readers behave.
>

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com
> <mailto:standardebook...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/37EEE958-EDB6-470B-BF79-8BAED8674054%40letterboxes.org
> <https://groups.google.com/d/msgid/standardebooks/37EEE958-EDB6-470B-
> BF79-8BAED8674054%40letterboxes.org?utm_medium=email&utm_source=footer>.

[Vince]

Had you ever opened the book before? Had the book ever been on your iPad before? (It remembers the opening location for a book even if you delete the book from the iPad entirely and re-add it.)

Otherwise, all I can say is it works here, and worked here the previous time I tried it, which was probably a couple of years ago.

[Alex Cabal]

No, I always pick new ebooks when testing, I know it seems to remember
the old position even if you delete the ebook. The current iPad I'm
using is fairly old but still has a solid percentage of use.

It definitely selects "bodymatter" as the start position. If I change
the frontmatter semantic to bodymatter, then it starts there. So maybe
that could be something for us to do in the compatible epub build.

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com
> <mailto:standardebook...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/EA49F691-8174-48EB-BFFF-D7F3A16AE1AE%40letterboxes.org
> <https://groups.google.com/d/msgid/standardebooks/EA49F691-8174-48EB-
> BFFF-D7F3A16AE1AE%40letterboxes.org?utm_medium=email&utm_source=footer>.

[Vince]

I think it’s the extra text after “frontmatter.” I just tried it twice on two new books. With the first book, I used “epub:type=“frontmatter introduction,” and it didn’t work, i.e. it opened to the body text. In the other book, I just used “epub:type=“frontmatter,” and it opened to the introduction. When I tested it earlier today, I also just had “frontmatter” (I don’t remember what I did a couple of years ago).

So maybe it’s just sufficient to use “frontmatter” without specifying anything else? It seems better to leave out information than to specify the wrong information.

[Alex Cabal]

Interesting. The solution I had already committed is for the compatible
build, in the landmarks replacing the href to the bodymatter with a href
to the first spine item.

I think I like that even with this knew determination, because I'm not
sure how we'd put frontmatter in the landmarks, or if it even belongs
there according to the spec. We can't put links to each frontmatter
item, because then we're just recreating the ToC. But it also doesn't
seem right to put a link to the titlepage (or whatever) and calling it
"start", because obviously the first spine item is the "start" of the
book, so why do the landmarks need a special link to that obvious location?

So by doing this in the compatible epub we acknowledge iBook's unusual
behavior while avoiding this frontmatter problem entirely.

Although, I will mention that the spec itself says:

> bodymatter [epub-ssv-11] — Reading systems often use this landmark to
automatically jump users past the front matter when they begin reading.

So if a reading system *wants* to skip the frontmatter, is it right for
us to tell it otherwise?

>>>>>> <mailto:standar...@googlegroups.com><mailto:standar...@googlegroups.com <mailto:standar...@googlegroups.com>>> wrote:
>>>>>>
>>>>>> We exclude almost everything based on the epub spec:https://
>>>>>> www.w3.org/TR/epub-34/#sec-nav-landmarks <http://www.w3.org/TR/

>>>>>> epub-34/#sec-nav-landmarks><http://www.w3.org/TR/ <http://
>>>>>> www.w3.org/TR/>epub-34/#sec-nav-landmarks><https://www.w3.org/TR/

>>>>>> <https://www.w3.org/TR/>epub-34/#sec-nav- landmarks <https://

>>>>>> www.w3.org/TR/%20epub-34/#sec-nav-landmarks <https://www.w3.org/

>>>>>> TR/%20epub-34/#sec-nav-landmarks>>>
>>>>>>
>>>>>> > It is advised to limit the number of items defined in the
>>>>>> landmarks nav to only items that a reading system is likely to use
>>>>>> in its user interface. The element is not meant to repeat the
>>>>>> table of contents.
>>>>>>
>>>>>> In practice this means bodymatter and reference-related items like
>>>>>> LoI, endnotes, glossary, etc. In our case ToC is also excluded
>>>>>> because it's not in the spine.
>>>>>>
>>>>>> On 7/31/26 1:16 PM, Vince wrote:
>>>>>>> I believe you’re correct. I’ve experimented in the past with my
>>>>>>> own (non-SE) books, and if the frontmatter is put in the
>>>>>>> landmarks, that’s where the book opens. I assumed we did that
>>>>>>> (left out the frontmatter from the landmarks) on purpose.
>>>>>>>> On Jul 31, 2026, at 12:57 PM, Robin Whittleton <ro...@reala.net>
>>>>>>>> wrote:
>>>>>>>>
>>>>>>>> Oh, I assumed readers did this because we don’t put the
>>>>>>>> frontmatter in the landmarks, causing them to jump to the first
>>>>>>>> landmark which is the bodymatter. Maybe I’m wrong?
>>>>>>>>
>>>>>>>> -Robin
>>>>>>>>
>>>>>>>>> On 31 Jul 2026, at 19:54, 'Alex Cabal' via Standard Ebooks
>>>>>>>>> <standar...@googlegroups.com> wrote:
>>>>>>>>>
>>>>>>>>> Introductions are always frontmatter. We can't control how
>>>>>>>>> ebook readers behave.
>

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com
> <mailto:standardebook...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/C7261AFC-C8C1-4552-BD61-B94F7C2FF4FA%40letterboxes.org
> <https://groups.google.com/d/msgid/standardebooks/C7261AFC-C8C1-4552-
> BD61-B94F7C2FF4FA%40letterboxes.org?utm_medium=email&utm_source=footer>.

[Tim Walters]

Just one reader/kibitzer here, but I *always* want to see the front matter. The jolt I get when I open a book and it starts at a completely unexpected place is my least favorite thing about Standard Ebooks.

[Vince]

That’s why I think it’s better to leave off information (i.e. just use “frontmatter”) than to mis-state what it actually is. If the reading system wants to open to bodymatter, they can just look for the first bodymatter and use it, so having a frontmatter landmark won’t affect them. If the reading system wants to use the first landmark, then they can.

As I mentioned earlier, if a book only has a dedication and/or epigraph, I personally wouldn’t put any frontmatter in the landmarks. I would reserve a frontmatter landmark for “significant” (for lack of a better term) frontmatter, e.g. introduction, maybe preface. And I would only put the first one, not all of them—it’s only [possibly] being used to open the book, so any after the first one don’t matter. This is also why it doesn’t hurt not to include the epub:type of the actual file being included; since there’s only going to be one, “frontmatter” is descriptive enough.

E.g., one of the books I tested on has a dedication, an editors introdution, an introduction, a preface, and an epigraph. I would only put the introduction in the landmark, since it’s the first one of the three we (I) care about.

[Alex Cabal]

But that's a subjective preference. Some people might want to read *all*
the frontmatter.

And I still don't think that addresses the fundamental problem of, if a
reading system wants to start from the beginning, depending on a
landmark is not how to do that because the start of an ebook is a
fundamental concept defined by the spine; but if it wants to skip to the
bodymatter (or reference material like the LoI), then presumably that's
what landmarks are for, because the start of the bodymatter cannot be
determined by looking at the spine alone.

In that sense I think ibooks is doing this wrong; if you've found that
putting an item with epub:type exactly equal to "frontmatter" is the
only way ibooks will start at that file, then it's:

1) processing epub:type incorrectly since epub:type may contain multiple
whitespace-separated items, and

2) relying on the landmarks to determine the start of the *entire
ebook*, instead of using it to determine the start of the *semantic
bodymatter*.

So maybe a better thing to do in the compatible build is to just give in
and put a "start" item pointing to the titlepage? But that's also
technically incorrect since we must omit the `titlepage` semantic from
epub:type to please ibooks. So if the previous solution wasn't
technically correct, neither is this one. But maybe it's less incorrect?

>>>>>>>> <mailto:standar...@googlegroups.com><mailto:standar...@googlegroups.com <mailto:standar...@googlegroups.com>><mailto:standar...@googlegroups.com <mailto:standar...@googlegroups.com><mailto:standar...@googlegroups.com <mailto:standar...@googlegroups.com>>>> wrote:
>>>>>>>>
>>>>>>>> We exclude almost everything based on the epub spec:https://
>>>>>>>> www.w3.org/TR/epub-34/#sec-nav-landmarks <http://www.w3.org/TR/
>>>>>>>> epub-34/#sec-nav-landmarks><http://www.w3.org/TR/ <http://

>>>>>>>> www.w3.org/TR/>epub-34/#sec-nav-landmarks><http://www.w3.org/TR/
>>>>>>>> <http://www.w3.org/TR/><http://www.w3.org/TR/ <http://
>>>>>>>> www.w3.org/TR/>>epub-34/#sec-nav-landmarks><https://www.w3.org/
>>>>>>>> TR/ <https://www.w3.org/TR/><https://www.w3.org/TR/ <https://

>>>>>>>> www.w3.org/TR/>>epub-34/#sec-nav- landmarks <https://www.w3.org/

>>>>>>>> TR/%20epub-34/#sec-nav-landmarks <http://www.w3.org/TR/
>>>>>>>> %20epub-34/#sec-nav-landmarks><https://www.w3.org/ TR/
>>>>>>>> %20epub-34/#sec-nav-landmarks <https://www.w3.org/%20TR/

>>>>>>>> %20epub-34/#sec-nav-landmarks>>>>
>>>>>>>>
>>>>>>>> > It is advised to limit the number of items defined in the
>>>>>>>> landmarks nav to only items that a reading system is likely to
>>>>>>>> use in its user interface. The element is not meant to repeat
>>>>>>>> the table of contents.
>>>>>>>>
>>>>>>>> In practice this means bodymatter and reference-related items
>>>>>>>> like LoI, endnotes, glossary, etc. In our case ToC is also
>>>>>>>> excluded because it's not in the spine.
>>>>>>>>
>>>>>>>> On 7/31/26 1:16 PM, Vince wrote:
>>>>>>>>> I believe you’re correct. I’ve experimented in the past with my
>>>>>>>>> own (non-SE) books, and if the frontmatter is put in the
>>>>>>>>> landmarks, that’s where the book opens. I assumed we did that
>>>>>>>>> (left out the frontmatter from the landmarks) on purpose.
>>>>>>>>>> On Jul 31, 2026, at 12:57 PM, Robin Whittleton
>>>>>>>>>> <ro...@reala.net> wrote:
>>>>>>>>>>
>>>>>>>>>> Oh, I assumed readers did this because we don’t put the
>>>>>>>>>> frontmatter in the landmarks, causing them to jump to the
>>>>>>>>>> first landmark which is the bodymatter. Maybe I’m wrong?
>>>>>>>>>>
>>>>>>>>>> -Robin
>>>>>>>>>>
>>>>>>>>>>> On 31 Jul 2026, at 19:54, 'Alex Cabal' via Standard Ebooks
>>>>>>>>>>> <standar...@googlegroups.com> wrote:
>>>>>>>>>>>
>>>>>>>>>>> Introductions are always frontmatter. We can't control how
>>>>>>>>>>> ebook readers behave.
>

> --
> You received this message because you are subscribed to the Google
> Groups "Standard Ebooks" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to standardebook...@googlegroups.com
> <mailto:standardebook...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/

> standardebooks/D7AD603C-3992-4F94-B767-0D103225EC9F%40letterboxes.org
> <https://groups.google.com/d/msgid/standardebooks/D7AD603C-3992-4F94-
> B767-0D103225EC9F%40letterboxes.org?utm_medium=email&utm_source=footer>.

[Vince]

But that's a subjective preference. 

Yes, of course it is, I said that multiple times (I personally…, I would…). But I think it’s a rational subjective preference. How many out of a hundred care about opening the book to a dedication? I don’t know, but my guess is not very many. (All of them will now jump out of the woodwork and reply to this thread. :)

2) relying on the landmarks to determine

It’s using it to determine where to open. That’s it. I don’t think it’s making any judgments about what the landmark is, just that it’s present. Here’s a link that says how Apple Books processes the landmarks. 

If you always want to open to the titlepage, then just put the titlepage in the landmark with a type of frontmatter and be done.

We exclude almost everything based on the epub spec:https:// www.w3.org/TR/epub-34/#sec-nav-landmarks <http://www.w3.org/TR/epub-34/#sec-nav-landmarks><http://www.w3.org/TR/ <http:// www.w3.org/TR/>epub-34/#sec-nav-landmarks><http://www.w3.org/TR/<http://www.w3.org/TR/><http://www.w3.org/TR/ <http:// www.w3.org/TR/>>epub-34/#sec-nav-landmarks><https://www.w3.org/ TR/ <https://www.w3.org/TR/><https://www.w3.org/TR/ <https:// www.w3.org/TR/>>epub-34/#sec-nav- landmarks <https://www.w3.org/TR/%20epub-34/#sec-nav-landmarks <http://www.w3.org/TR/ %20epub-34/#sec-nav-landmarks><https://www.w3.org/ TR/ %20epub-34/#sec-nav-landmarks <https://www.w3.org/%20TR/ %20epub-34/#sec-nav-landmarks>>>>

[Bennett Helm]

I think I'm basically done. There is one remaining issue, which I cannot figure out. Having added the long-description in content.opf, I run `se clean .`. However, contrary to what it says in Step 24 of the step-by-step guide, that does not escape html tags in the long-description. (It does do that in the (short) description.) Consequently, `se lint .` throws error m-016.

When I manually substitute "&lt;" for "<" and "&gt;" for ">" throughout the long-description, `se lint .` gives me the same error.

Either way (unescaped or manually escaped), when running `se build --check-only .`, I get error RSC-005.

So I'm not sure what's going on. Currently I've left it with normal (unescaped) html tags.

Other than that, everything is pushed to github, and I'm ready for review.

Bennett

[Emma Sweeney]

Recently, formatting has changed for the descriptions. Use <meta property="schema:abstract"> for the short description and <dc:description> for the long description. After making these changes, se clean should convert it into escaped HTML.

Emma

[Bennett Helm]

Thanks. I've made that change, and `se clean .` does convert to escaped HTML, and it passes the `se lint` checks.

However, I'm still getting 6 errors from `se build --check-only .`; these errors are all from line 46, which contains the first line of the (long) description:

• epubcheck │ RSC-005 │ content.opf(46:129) │ Error while parsing file: text not allowed here; expected data
• epubcheck │ RSC-005 │ content.opf(46:146) │ Error while parsing file: text not allowed here; expected data
• epubcheck │ RSC-005 │ content.opf(46:387) │ Error while parsing file: text not allowed here; expected data
• epubcheck │ RSC-005 │ content.opf(46:129) │ Error while parsing file: element "a" not allowed anywhere; expected data
• epubcheck │ RSC-005 │ content.opf(46:149) │ Error while parsing file: element "i" not allowed anywhere; expected data
• epubcheck │ RSC-005 │ content.opf(46:394) │ Error while parsing file: element "meta" incomplete; expected data

Curiously, when I substitute within the <dc:description> tag the description from a published SE book, I get the same errors.

Bennett

[Emma Sweeney]

You shouldn't have <i> or <a> elements inside <meta property="schema:abstract">.

Emma

[Bennett Helm]

Ok. I've rewritten the abstract to remove tags, and I'm not receiving these errors. And I've sorted out a couple of other errors revealed by `se build --check-only .`. It's ready for review.

Bennett

[Lukas Bystricky]

Sounds good. I'll get to that in the next couple days.

--

You received this message because you are subscribed to the Google Groups "Standard Ebooks" group.

To unsubscribe from this group and stop receiving emails from it, send an email to standardebook...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/standardebooks/ab299e2e-ba44-4e43-b216-c3f6023aa262n%40googlegroups.com.

[Lukas Bystricky]

Very nice work Bennett on a complicated production. I've filed a few issues, mostly minor, but you'll have to do a rebase. Let me know if you need help with that.