Naming conventions for html-pages

OHappyDay

unread,

Jul 30, 2026, 1:26:54 PMJul 30

to PreTeXt support

Dear all,

in a new book project I experienced a weird situation which I could not track down to the root immediately.

Here is what I did:

Created 2 chapters with subchapters:
- xml:id="ch-1"
- xml:id="ch-2"
- xml:id="ch-2-1"
- xml:id="ch-2-2"
ch-2 also contained an introduction without an xml:id
After building to html the navigation behaved weird: deadlocked between ch-2-1 and ch-2-2

After some thoughts I found the culprit: the introduction was placed in it's own page named ch-2-2.html. But chapter 2-2 was also named ch-2-2.html which explains the above behaviour.

After applying an xml:id="ch-2-intro" to the introduction the deadlock was resolved because the introduction got now a new filename ch-2-intro.html.

Other question: What can I do to have the introduction on the chapter page instead of having its own page? In an earlier project from some years ago this is what I achieved (but I don't know how). Or is this not possible anymore?

Thanks

Klaus

Rob Beezer

unread,

Jul 30, 2026, 2:53:26 PMJul 30

to pretext...@googlegroups.com

Very good! You've hit an obscure situation that we are aware of, but really
cannot fix.

First - using ids that are numbers is a bad practice - let PreTeXt number for
you. And once you rearrange your work (it happens!) all those numbers will be
mixed up.

Second - you can use @label which will influence page names, and it does not
have to match your @xml:id, so you can keep them if you really insist.

Explanation - when you do not provide an identifier, we make one for you. We
use the most recent identifier you did provide and start using the location of
children at each level above. So your "ch-2-2" matched our automatic "ch-2"
plus a "-2". I think that is it (or similar). So your sequential/hierarchical
numbering is getting caught up with our attempts to bail you out.

Best practice: put a @label on each division and do not use numbers. That will
bail you out here.

Now, secondarily. A division #introduction now gets its own page in HTML
output, not semi-hidden on a "summary" page. This was announced on July 8 on
pretext-announce with a subject mentioning "division companions".

Rob

On 7/30/26 10:26, 'OHappyDay' via PreTeXt support wrote:
> Dear all,
>
> in a new book project I experienced a weird situation which I could not track
> down to the root immediately.
>
> Here is what I did:
>

> * Created 2 chapters with subchapters:
> o xml:id="ch-1"
> o xml:id="ch-2"
> o xml:id="ch-2-1"
> o xml:id="ch-2-2"
> * ch-2 also contained an introduction without an xml:id
> * After building to html the navigation behaved weird: deadlocked between

> ch-2-1 and ch-2-2
>
> After some thoughts I found the culprit: the introduction was placed in it's own
> page named ch-2-2.html. But chapter 2-2 was also named ch-2-2.html which
> explains the above behaviour.
>
> After applying an xml:id="ch-2-intro" to the introduction the deadlock was
> resolved because the introduction got now a new filename ch-2-intro.html.
>

> *Other question*: What can I do to have the introduction on the chapter page

> instead of having its own page? In an earlier project from some years ago this
> is what I achieved (but I don't know how). Or is this not possible anymore?
>
> Thanks
> Klaus
>

> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt support" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to pretext-suppo...@googlegroups.com <mailto:pretext-
> support+u...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/pretext-
> support/2b5721ef-bfd7-4c45-93ec-af945934e99cn%40googlegroups.com <https://
> groups.google.com/d/msgid/pretext-support/2b5721ef-bfd7-4c45-93ec-
> af945934e99cn%40googlegroups.com?utm_medium=email&utm_source=footer>.

OHappyDay

unread,

Jul 30, 2026, 4:44:16 PMJul 30

to PreTeXt support

Rob,

thanks for the clarification. That explains it well and I did not see the announcement.

Klaus

David Austin

unread,

Jul 30, 2026, 5:28:50 PMJul 30

to pretext...@googlegroups.com

PreFigure has a similar issue in that some element ids are generated internally. After reports of some puzzling behavior, we began to prepend "__" to generated ids to reduce the likelihood of collisions with authored ids.

David

To unsubscribe from this group and stop receiving emails from it, send an email to pretext-suppo...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-support/MTAwMDAzZWl4TVlhV2g.1785437602%40pnsh.

Rob Beezer

unread,

Jul 31, 2026, 10:44:38 AMJul 31

to pretext...@googlegroups.com

> we began to prepend "__"

That is a very good idea. A bit ugly, but a good idea.

@xml:id is internal, not normally witnessed by a reader. But @label does become
things like HTML filenames - the collision seen here. Ugly. And I'm not sure
if anything gets messed up if it leads with an underscore. Any generated files
using automatic ids for filenames would need regeneration.

We could prepend with "ptx-". Aah, we just banned that construction so HTML ids
have a crude namespace of their own.

Can't decide if the disease is worth the cure. This is the first report, and we
have had this potential for years, iirc.

Rob

On 7/30/26 14:28, David Austin wrote:
> PreFigure has a similar issue in that some element ids are generated
> internally. After reports of some puzzling behavior, we began to prepend "__"
> to generated ids to reduce the likelihood of collisions with authored ids.
>
> David
>

> support%2Bunsu...@googlegroups.com> <mailto:pretext- <mailto:pretext->
> > support+u...@googlegroups.com
> <mailto:support%2Bunsu...@googlegroups.com>>.

> > To view this discussion visit https://groups.google.com/d/msgid/pretext-

> <https://groups.google.com/d/msgid/pretext->
> > support/2b5721ef-bfd7-4c45-93ec-af945934e99cn%40googlegroups.com
> <http://40googlegroups.com> <https://
> > groups.google.com/d/msgid/pretext-support/2b5721ef-bfd7-4c45-93ec-
> <http://groups.google.com/d/msgid/pretext-support/2b5721ef-bfd7-4c45-93ec->
> > af945934e99cn%40googlegroups.com?utm_medium=email&utm_source=footer
> <http://40googlegroups.com?utm_medium=email&utm_source=footer>>.

>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt support" group.
> To unsubscribe from this group and stop receiving emails from it, send an

> email to pretext-suppo...@googlegroups.com <mailto:pretext-
> support%2Bunsu...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/pretext-

> support/MTAwMDAzZWl4TVlhV2g.1785437602%40pnsh <https://groups.google.com/d/
> msgid/pretext-support/MTAwMDAzZWl4TVlhV2g.1785437602%40pnsh>.

>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt support" group.
> To unsubscribe from this group and stop receiving emails from it, send an email

> to pretext-suppo...@googlegroups.com <mailto:pretext-
> support+u...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/pretext-support/

> CANXmVMC1M4YbjgDpBizx60iBRJOo0abF88%2B--cMDqRkcY3topA%40mail.gmail.com <https://
> groups.google.com/d/msgid/pretext-support/
> CANXmVMC1M4YbjgDpBizx60iBRJOo0abF88%2B--cMDqRkcY3topA%40mail.gmail.com?
> utm_medium=email&utm_source=footer>.

OHappyDay

unread,

Jul 31, 2026, 12:38:14 PMJul 31

to PreTeXt support

I added a label but fell into another trap: although the final error message mentions that only letters, numbers, hyphens and underscore are allowed, some German letters that are not in the ASCII character set (umlauts) prevent the project to be built. So an umlaut is not a letter in that sense?

I could not find a hint on what character set the content of a label is based on.

Klaus

Rob Beezer

unread,

Jul 31, 2026, 1:27:22 PMJul 31

to pretext...@googlegroups.com

Yes, we are only allowing the 26 Latin letters, no accents. Sorry - I am
sympathetic. But if we allow a wider spread I think we will have problems with
older operating systems and file systems.

We want to be international, but I think we will need to be English-centric on
this one. I can clarify the error message.

Rob

> > <https://groups.google.com/d/msgid/pretext- <https://groups.google.com/d/
> msgid/pretext->>
> > > support/2b5721ef-bfd7-4c45-93ec-af945934e99cn%40googlegroups.com
> <http://40googlegroups.com>
> > <http://40googlegroups.com <http://40googlegroups.com>> <https://
> > > groups.google.com/d/msgid/pretext-support/2b5721ef-bfd7-4c45-93ec-
> <http://groups.google.com/d/msgid/pretext-support/2b5721ef-bfd7-4c45-93ec->
> > <http://groups.google.com/d/msgid/pretext-support/2b5721ef-
> bfd7-4c45-93ec- <http://groups.google.com/d/msgid/pretext-support/2b5721ef-
> bfd7-4c45-93ec->>
> > > af945934e99cn%40googlegroups.com?utm_medium=email&utm_source=footer
> <http://40googlegroups.com?utm_medium=email&utm_source=footer>
> > <http://40googlegroups.com?utm_medium=email&utm_source=footer

> <http://40googlegroups.com?utm_medium=email&utm_source=footer>>>.
> >
> > --
> > You received this message because you are subscribed to the Google Groups
> > "PreTeXt support" group.
> > To unsubscribe from this group and stop receiving emails from it, send an
> > email to pretext-suppo...@googlegroups.com <mailto:pretext-
> > support%2Bunsu...@googlegroups.com>.
> > To view this discussion visit https://groups.google.com/d/msgid/pretext-

> <https://groups.google.com/d/msgid/pretext->
> > support/MTAwMDAzZWl4TVlhV2g.1785437602%40pnsh <https://groups.google.com/
> d/ <https://groups.google.com/d/>

> > msgid/pretext-support/MTAwMDAzZWl4TVlhV2g.1785437602%40pnsh>.
> >
> > --
> > You received this message because you are subscribed to the Google Groups
> > "PreTeXt support" group.
> > To unsubscribe from this group and stop receiving emails from it, send an
> email
> > to pretext-suppo...@googlegroups.com <mailto:pretext-
> > support+u...@googlegroups.com>.
> > To view this discussion visit https://groups.google.com/d/msgid/pretext-

> support/ <https://groups.google.com/d/msgid/pretext-support/>
> > CANXmVMC1M4YbjgDpBizx60iBRJOo0abF88%2B--cMDqRkcY3topA%40mail.gmail.com
> <http://40mail.gmail.com> <https://
> > groups.google.com/d/msgid/pretext-support/ <http://groups.google.com/d/
> msgid/pretext-support/>
> > CANXmVMC1M4YbjgDpBizx60iBRJOo0abF88%2B--cMDqRkcY3topA%40mail.gmail.com
> <http://40mail.gmail.com>?
> > utm_medium=email&utm_source=footer>.

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

> support/35561b64-f928-49b6-bb0a-0b61313e610en%40googlegroups.com <https://
> groups.google.com/d/msgid/pretext-support/35561b64-f928-49b6-
> bb0a-0b61313e610en%40googlegroups.com?utm_medium=email&utm_source=footer>.

OHappyDay

unread,

Jul 31, 2026, 2:04:12 PMJul 31

to PreTeXt support

Thanks

Rob Beezer

unread,

Jul 31, 2026, 4:12:17 PMJul 31

to pretext...@googlegroups.com

> I can clarify the error message.

And more:

https://github.com/PreTeXtBook/pretext/pull/3100

And I learned something. An @xml:id that leads with a number (my assistant
likes "2fish", for *some* reason), will not be parsed at all if it is in the
root file. So watch out for that one. It is so early in processing we can't do
much to help. Just education.

Thanks, Klaus, for the reports (as usual!).

Rob

> > pretext- <https://groups.google.com/d/msgid/pretext- <https://

> groups.google.com/d/msgid/pretext->>
> > > <https://groups.google.com/d/msgid/pretext- <https://groups.google.com/

> d/msgid/pretext-> <https://groups.google.com/d/ <https://groups.google.com/d/>

> > msgid/pretext->>
> > > > support/2b5721ef-bfd7-4c45-93ec-af945934e99cn%40googlegroups.com
> <http://40googlegroups.com>
> > <http://40googlegroups.com <http://40googlegroups.com>>
> > > <http://40googlegroups.com <http://40googlegroups.com>
> <http://40googlegroups.com <http://40googlegroups.com>>> <https://
> > > > groups.google.com/d/msgid/pretext-support/2b5721ef-bfd7-4c45-93ec-
> <http://groups.google.com/d/msgid/pretext-support/2b5721ef-bfd7-4c45-93ec->
> > <http://groups.google.com/d/msgid/pretext-support/2b5721ef-
> bfd7-4c45-93ec- <http://groups.google.com/d/msgid/pretext-support/2b5721ef-
> bfd7-4c45-93ec->>

> > > <http://groups.google.com/d/msgid/pretext-support/2b5721ef- <http://
> groups.google.com/d/msgid/pretext-support/2b5721ef->
> > bfd7-4c45-93ec- <http://groups.google.com/d/msgid/pretext-
> support/2b5721ef- <http://groups.google.com/d/msgid/pretext-support/2b5721ef->

> > > To view this discussion visit https://groups.google.com/d/msgid/
> pretext- <https://groups.google.com/d/msgid/pretext->
> > <https://groups.google.com/d/msgid/pretext- <https://groups.google.com/d/
> msgid/pretext->>

> > > support/MTAwMDAzZWl4TVlhV2g.1785437602%40pnsh <https://
> groups.google.com/ <https://groups.google.com/>
> > d/ <https://groups.google.com/d/ <https://groups.google.com/d/>>

> > > msgid/pretext-support/MTAwMDAzZWl4TVlhV2g.1785437602%40pnsh>.
> > >
> > > --
> > > You received this message because you are subscribed to the Google Groups
> > > "PreTeXt support" group.
> > > To unsubscribe from this group and stop receiving emails from it, send an
> > email
> > > to pretext-suppo...@googlegroups.com <mailto:pretext-
> > > support+u...@googlegroups.com>.
> > > To view this discussion visit https://groups.google.com/d/msgid/

> pretext- <https://groups.google.com/d/msgid/pretext->
> > support/ <https://groups.google.com/d/msgid/pretext-support/ <https://
> groups.google.com/d/msgid/pretext-support/>>
> > > CANXmVMC1M4YbjgDpBizx60iBRJOo0abF88%2B--cMDqRkcY3topA%40mail.gmail.com
> <http://40mail.gmail.com>
> > <http://40mail.gmail.com <http://40mail.gmail.com>> <https://
> > > groups.google.com/d/msgid/pretext-support/ <http://groups.google.com/d/
> msgid/pretext-support/> <http://groups.google.com/d/ <http://
> groups.google.com/d/>
> > msgid/pretext-support/>
> > > CANXmVMC1M4YbjgDpBizx60iBRJOo0abF88%2B--cMDqRkcY3topA%40mail.gmail.com
> <http://40mail.gmail.com>
> > <http://40mail.gmail.com <http://40mail.gmail.com>>?

> > > utm_medium=email&utm_source=footer>.
> >
> > --
> > You received this message because you are subscribed to the Google Groups
> > "PreTeXt support" group.
> > To unsubscribe from this group and stop receiving emails from it, send an
> email
> > to pretext-suppo...@googlegroups.com <mailto:pretext-
> > support+u...@googlegroups.com>.
> > To view this discussion visit https://groups.google.com/d/msgid/pretext-

> <https://groups.google.com/d/msgid/pretext->
> > support/35561b64-f928-49b6-bb0a-0b61313e610en%40googlegroups.com
> <http://40googlegroups.com> <https://
> > groups.google.com/d/msgid/pretext-support/35561b64-f928-49b6- <http://
> groups.google.com/d/msgid/pretext-support/35561b64-f928-49b6->
> > bb0a-0b61313e610en%40googlegroups.com?utm_medium=email&utm_source=footer

> <http://40googlegroups.com?utm_medium=email&utm_source=footer>>.
>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt support" group.
> To unsubscribe from this group and stop receiving emails from it, send an email
> to pretext-suppo...@googlegroups.com <mailto:pretext-

> support+u...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/pretext-support/

> d3028440-2412-437f-8d7c-e9985dda5676n%40googlegroups.com <https://
> groups.google.com/d/msgid/pretext-support/d3028440-2412-437f-8d7c-
> e9985dda5676n%40googlegroups.com?utm_medium=email&utm_source=footer>.

OHappyDay

unread,

Jul 31, 2026, 4:24:12 PMJul 31

to PreTeXt support

Thanks, Rob, it's always a pleasure to contribute to the project.

Rob Beezer

unread,

Jul 31, 2026, 5:17:35 PMJul 31

to pretext...@googlegroups.com

And now an FAQ for the original symptom.

https://github.com/PreTeXtBook/pretext/pull/3101

Reply all

Reply to author

Forward

Naming conventions for html-pages - conflicts

OHappyDay

Rob Beezer

OHappyDay

David Austin

Rob Beezer

OHappyDay

Rob Beezer

OHappyDay

Rob Beezer

OHappyDay

Rob Beezer