cross-referencing in an EPUB?

[daudvyd]

I'm writing with Sigil. I'd like to automatically number figure captions using a CSS counter and then reference that counter in inline content such as "...see Figure 4..." where the number "4" is automatically produced and updated as I add more figures and shuffle their order. My understanding from these examples is that I can use an id tag to identify which figure caption I want to reference and target-counter to get the counter. The code below numbers the figure captions, but cannot get those numbers afterward to put inline. So, (1) I've written it incorrectly, (2) Sigil does not implement this CSS feature, or (3) both (1) and (2). Can anyone help?

<p>See Fig <a href="#fig3items">000</a></p>
<figure>
<ul>
<li>item1</li>
<li>item2</li>
<li>item3</li>
</ul>
<figcaption id="fig3items">Three Items</figcaption>
</figure>

body {
counter-reset: chapter;
counter-reset: figure;
counter-increment: chapter 5;
}

figure figcaption {
	counter-increment: figure;
}

figure figcaption:before {
	content: "Figure " counter(chapter) "-" counter(figure) ": ";
}

a::after {
  content: target-counter(attr(href, url),figure)}

[Hitch]

Well....

Firstly, honestly, writing WITH Sigil is generally a bad idea. It's not a word processor and it does not have most of the functionality that even basic word processors use--like automatically numbering figures.

Secondly, "figure" is not supported in about half of all ePUB-reading software/devices.

Hitch

[Hitch]

Oh, and I'd also suggest you move this to the Sigil forum--ask one of the mods to do it.

Hitch

[daudvyd]

Thank you. What do you personally use for writing ebooks?

[Hitch]

Originally Posted by daudvyd

Thank you. What do you personally use for writing ebooks?

ANY Word processor would be better. Word, if you're MSFT-inclined, especially--especially--if you're going to use figures, captions, cross-referencing, etc. I can't emphasize that enough. For example, Pages, which is an Apple/Mac product, doesn't do indexing at all, so you don't want that (presumably).

So, in my personal order of preference, MSFT Word, which is truly the most advanced, followed by Libre Office, which is, all things considered, nearly as advanced as Word (and can also export to ePUB, by the way, which Word as yet does not do).

(n.b./caveat: I'm not a published author, in the sense you're thinking. I've written millions of technical words, how-to manuals, legal docs with x-refs, etc. over the years. I currently own a company that makes eBooks--over 7K of them to date--and print design for paperbacks and hardcovers. So, I have a more-than-passing acquaintance with the HTML and CSS of eBooks.)

You can then export to HTML (filtered HTML, from Word) and open that in Sigil, if you're so inclined. But seriously, the functionality you're seeking--that's a massive uphill battle for eBooks and what will you do, when you export the HTML/ePUB, into devices that won't support count? It'll be a gigantic MESS.

Do that heavy lifting, renumbering with tags, references, etc. in the word processor. When it's all finalized, THEN export to ePUB/HTML. Trust me on this.

Hitch

[daudvyd]

Thanks Hitch. Have you tried technical writing with OxygenXML using DITA? If so, how does that approach compare with exporting from MS Word?

[Hitch]

Originally Posted by daudvyd

Thanks Hitch. Have you tried technical writing with OxygenXML using DITA? If so, how does that approach compare with exporting from MS Word?

Do you mind, before I answer this, if I ask what you're doing, precisely? May I ask why you are using DITA? Specifically? I mean...don't get me wrong, but you are sure going about this the bloody hard way.

So, what is it, PRECISELY, that you are creating? I don't mean you have to violate confidentiality agreements or the like, but DITA is a framework. I mean...what is the form of markup that you're trying to deploy here? Presumably, you're trying to, what, map new content or element types? is that what you're doing? And you were planning to do that in Sigil, manually?

MODS, we really need to move this to the Workshop, rather than Sigil. (daudvyd, don't worry, I'll ask them).

Hitch

[daudvyd]

I'm writing a role-playing game book (like Dungeons & Dragons) and would like -- if possible -- to produce an ebook (EPUB, MOBI, etc) and a print-ready PDF with more complex formatting from a single source. I'd like figures & cross-references, TOC, and indexes to be handled through markup rather than manually constructed. I may have a person index, technology index, spell index, etc. I'm not sure what the native format should be to allow maximum flexibility.

[Hitch]

Originally Posted by daudvyd

I'm writing a role-playing game book (like Dungeons & Dragons) and would like -- if possible -- to produce an ebook (EPUB, MOBI, etc) and a print-ready PDF with more complex formatting from a single source. I'd like figures & cross-references, TOC, and indexes to be handled through markup rather than manually constructed. I may have a person index, technology index, spell index, etc. I'm not sure what the native format should be to allow maximum flexibility.

Well...Word and Libre Office ("LO") both do that. Open Office ("OO") may, but LO is better maintained and supported. Most of what you're discussing is WHY word processing exists. I mean...they're not just electronic typewriters.

There really isn't any reason for you to dive into DITA. In something like Word, for example, you build almost everything through the use of headings, styles, field codes, and cross-references. You can create multiple indices, although that will take a bit of doing. BUT, you can't do any of it if you treat Word like a typewriter--you need to learn Styles & Headings; cross-referencing; indexing, building TOCs automatically, and working comfortably in outline mode. With those, you should be able to do everything you wish.

DITA...DITA is all well and good, but as I said, it's a framework, not a pre-made platform. Sure, you could do all the work and the brain damage, but I'm not certain it would do anything but CAUSE you work.

As far as a "single-source." Look--nothing does that. NOTHING. (You're talking the Holy Grail of bookmaking, just FYI. Those that claim that they have this are sacrificing a lot to get a single-source file. You can't do it with LaTEX--oh my GOD, you haven't suffered until you try to create an eBook from LaTeX).

You create a master document in Word. (Or LO, whatever.) You then create whichever format you want first--typically print. You create your TOC with the print requirements (page numbers, usually with dot leaders for a non-fiction sort of thing), and then, when you export your PDF, you then remove that TOC and recreate it for the eBook--this is basically push-button, you understand!!!--without page numbers, using links instead, which is what drives the NCX, etc. in ePUB. You also remove running headers, folios (page numbers), and any footers. Then from LO, you export an ePUB; from Word, you export filtered HTML and then you put that filtered HTML into Sigil and build an ePUB.

There's no point in building a MOBI any longer. Amazon no longer accepts mobi. If you want one to put on your own device, to sideload and preview, then you can export one from Kindle Previewer 3, and sideload it. Done and dusted.

Hitch

[Pierre Lawrence]

Don't you still need mobi for legacy reasons, i.e., for readers having early versions of the Kindle? Does amazon still offer that format for these readers?

[Hitch]

Originally Posted by Pierre Lawrence

Don't you still need mobi for legacy reasons, i.e., for readers having early versions of the Kindle? Does amazon still offer that format for these readers?

You can upload a mobi ONLY for fixed-layout.

Amazon produces an AZW for legacy readers--the point is, you can no longer upload one for regular, reflowable eBooks. Amazon takes the ePUB that you upload (or the Word file, zipped HTML, etc.) and builds the required file.

That's why, at my shop, even though we have stopped building mobi files (except for those customers that wish to preview on their own Kindle devices), we still build optimized ePUBs (ePUBs with Amazon-specific fallbacks and media queries, as if they are MOBI files). That way, Amazon can build the 3 formats or really, 4, that it requires to service all the registered devices--old MOBI, KF8, KFX and the AZK equivalent (for iOS).

Hitch

[Pierre Lawrence]

Hitch, thanks! Hadn't caught up with that. Explains the at the time puzzling message I got when I tried to view a mobi file on the Kindle previewer (basically that it converted the file to epub). I tried mobi thinking that was the format the previewer wanted.

[Hitch]

Originally Posted by Pierre Lawrence

Hitch, thanks! Hadn't caught up with that. Explains the at the time puzzling message I got when I tried to view a mobi file on the Kindle previewer (basically that it converted the file to epub). I tried mobi thinking that was the format the previewer wanted.

You betcha, Pierre. Happy to elaborate, any time. As I said, you can still export a MOBI therefrom, if it's needed, for someone to sideload to a PPW or other Kindle.

I would add, n.b., that many Kindle devices now, can take an ePUB "directly" through emailing it to your dedicated Kindle address. I've done that and tested it myself. You can try it and if it isn't yet activated for you, you'll get an "unsupported format" automated email--but I tried it and damned if it didn't just make a mobi "for" me to view on the device. Dang!

Hitch

[Quoth]

Use Word or LO Writer. No headers or footers and a small 4:3 page size. Save/export a docx for Sigil or Calibre to format epub. Upload epub to Amazon KDP. THEY make the format for whatever the customer has.

Save a proofed copy, add headers, footers, page numbers, set page size exactly to paper size. Change font sizes and faces in styles if needed. Export a PDF direct from LO (and later versions of Word. Earlier Word versions needed a plugin). LO Writer PDF output is 100% paper ready.

Calibre will convert docx from Word or LO Writer mapping styles 1:1 to CSS classes. You might need to edit css of classes for images. That's a separate topic.

The SAME epub is uploaded to Amazon. Smashwords (who also distribute to Kobo, Apple, Barnes & Noble etc) and Google Play Store PlayBooks.

Smashwords can't know what kind of kindle their own customers have, so we upload a Calibre dual Mobi for that (Kf7 + KF8). Don't ever upload such a thing to Amazon or anywhere else.


I have 30+ year interest in "Plot your own adventure" type books. You can't score or be interactive in a real ebook (make an iOS and Android app if you want that). Real ebooks have only reflowable styled text, headings (page breaks before automagically, no CSS or HTML, one file per heading that wants a page break), png or jpg images. Audio, colour, animation, transparency, video, interaction etc are in SOME ebook specs, but real ebooks don't use them as device compatibility is low. Fixed layout, image drop caps, tables etc don't work well.

A printed Plot your own adventure has Go to page nnn instructions. An ebook version replaces those with links to anchors at headings (so page breaks), that can easily be done in MS Word or LO Writer, then for PDF version you add the text of the page number to each link.

If you want anything fancier forget paper and ebooks and use an app framework.

Do not use a framework to make ebooks and paper books.


This, like most threads started in Writing, should be in the Workshop section.

Forget about Mobi. Only make an epub and only convert the epub to dual mobi if also distributing via Smashwords AS WELL as the epub.

Don't upload docx or doc to anyone.

Only upload PDF that's exact 1:1 for paper Print to someone producing a paper copy. Never upload epub, doc or docx for a paper version.

[Tex2002ans]

Originally Posted by Pierre Lawrence

Hitch, thanks! Hadn't caught up with that. Explains the at the time puzzling message I got when I tried to view a mobi file on the Kindle previewer (basically that it converted the file to epub).

And, Pierre:

Are you planning on just creating this EPUB for personal consumption/sharing?

Or are you trying to put this up for sale on the major retailers?

Originally Posted by daudvyd

I'm writing a role-playing game book (like Dungeons & Dragons) [...] a print-ready PDF with more complex formatting from a single source.

[...]

I'd like figures & cross-references, TOC, and indexes to be handled through markup rather than manually constructed.

You may want to check out this comment in:

• TeX Stack Exchange: "Showcase of beautiful typography done in TeX & friends"

which points to this project:

• https://github.com/rpgtex/DND-5e-LaTeX-Template

That may help with some of your stuff.

But I must admit, I'm not familiar at all with the D&D stuff. (Like what the official guides look like, what functionality they have, coloring of stats/tables, etc.)

Originally Posted by daudvyd

[...] and would like -- if possible -- to produce an ebook (EPUB, MOBI, etc) and [...]

That would be difficult, especially for one with such complex layout/features.

Originally Posted by daudvyd

I'd like to automatically number figure captions using a CSS counter and then reference that counter in inline content such as "...see Figure 4..." where the number "4" is automatically produced and updated as I add more figures and shuffle their order. My understanding from these examples is that I can use an id tag to identify which figure caption I want to reference and target-counter to get the counter.

Like Hitch explained, forget it.

This is bleeding edge code.

Absolutely no actual EPUB readers support this stuff yet, so it would be completely broken on real-life devices.

For the EPUB, you'd have to bake the numbers into the text itself... or have workflow like you mentioned:

• a source file
  
  • (Markdown, Word, LO, etc.)
• -> a middleman
  
  • conversion program which then generates the finalized numbers/references for you.
• -> output file

Originally Posted by daudvyd

I may have a person index, technology index, spell index, etc. I'm not sure what the native format should be to allow maximum flexibility.

And this throws an enormous wrench into the mix.

Indexes are... rough.

Multiple indexes are rougher.

Originally Posted by Hitch

Well...Word and Libre Office ("LO") both do that. Open Office ("OO") may, but LO is better maintained and supported.

Yeah... the word "OpenOffice" should never be mentioned again.

Here's a reddit post I wrote 3 months ago explaining the situation.

Only time it should be mentioned is pointing people to LibreOffice.

- - -

Long story short:

OpenOffice has been abandoned for over 10 years.

LibreOffice has:

• consistently gotten major updates every 6 months
• + ~100 bugfixes every few weeks.

It keeps on getting:

• better functionality
• better performance
• better compatibility (with Word/DOCX / all other formats)

... pretty much better everything. And has been for over 10 years.

Originally Posted by Hitch

As far as a "single-source." Look--nothing does that. NOTHING. (You're talking the Holy Grail of bookmaking, just FYI.

Yeah.

Originally Posted by Hitch

Those that claim that they have this are sacrificing a lot to get a single-source file. You can't do it with LaTEX--oh my GOD, you haven't suffered until you try to create an eBook from LaTeX).

lol. We'll figure it out one of these days!

I still see magic being done on Stack Exchange, but I haven't wrangled my mind around the LaTeX->HTML workflow yet.

And, as you know, in reality, most people's source files aren't clean... which throws MAJOR wrenches into the mix.

(Grumble, grumble, grumble, SI units... grumble grumble... thermodynamics...)

Originally Posted by Hitch

You create a master document in Word. (Or LO, whatever.) You then create whichever format you want first--typically print. [...] Then from LO, you export an ePUB; from Word, you export filtered HTML and then you put that filtered HTML into Sigil and build an ePUB.

Yeah... but in this specific case, I hesitate to recommend Word/LO.

Trying to consistently generate complicated tables (D&D stat blocks) + marking up the formatting/coloring (consistently) would be... disastrously hair-pulling.

(Similar situation when we dealt with Code Blocks + Syntax Highlighting.)

Is there a way you can create "templates" in Word, where you feed in something like:

Spoiler:

    %\DndMonsterMelee calls \DndMonsterAttack with the melee option
    \DndMonsterMelee[
      name=Flame Tongue Longsword,
      mod=+3,
      %reach=5,
      %targets=one target,
      dmg=\DndDice{1d8+1},
      dmg-type=slashing,
      plus-dmg=\DndDice{2d6},
      plus-dmg-type=fire,
      or-dmg=\DndDice{1d10+1},
      or-dmg-when=if used with two hands,
      %extra=,
    ]

and the formatted + fully-Styled block pops out?

- - - -

And then Indexing, oh boy, Indexing...

I'll just point to the latest topic where we discussed that + I linked to everything under the sun:

• 2021: "Indexing in SIGIL - How to add "See also...""

In Word + LibreOffice when you try to convert indexes to HTML... Index links? Poof. Page numbers? Poof.

And trying to handle multiple Indexes + complicated references? My gods... lol. I don't even want to imagine it in Word/LO.

Side Note: Have we figured out a good way to generate proper Index code out of Word/LibreOffice yet? I wonder if DAISY's tool works better. I'll have to test that out one of these days...

Originally Posted by Hitch

You create your TOC with the print requirements (page numbers, usually with dot leaders for a non-fiction sort of thing), and then, when you export your PDF, you then remove that TOC and recreate it for the eBook--this is basically push-button, you understand!!!--without page numbers, using links instead, which is what drives the NCX, etc. in ePUB. You also remove running headers, folios (page numbers), and any footers.

Yep. And if you're working in Word/LibreOffice:

#1 most important thing is Styles, Styles, Styles.

See:

• 2020: "eBook Formatting in Sigil"

specifically my posts #46, #50, and #52.