PDF outline entry is incomplete when rubby is used in a heading title

[maxigaz]

If I use rubby inside the title of a level 1 heading, none of the arguments inside the ruby function will show up in the outline of the PDF document.

Here's a minimal example:

#import "@preview/rubby:0.10.2": get-ruby

#let ruby = get-ruby(
  size: 0.5em,         // Ruby font size
  dy: 0pt,             // Vertical offset of the ruby
  pos: top,            // Ruby position (top or bottom)
  alignment: "center", // Ruby alignment ("center", "start", "between", "around")
  delimiter: "|",      // The delimiter between words
  auto-spacing: true,  // Automatically add necessary space around words
)

= Dialogue and Grammar (#ruby("かいわ", "会話")・#ruby("ぶんぽう", "文法")#ruby("へん", "編"))

= Reading and Writing (#ruby("よ", "読")み#ruby("か", "書")き#ruby("へん", "編"))

If I compile this with typst and open it with Evince under Arch Linux, this is what I see when I enable the side pane and the outline view:

Output + PDF outline (bright image)

In other words, this is what I expect to see on the left:

Dialogue and Grammar (会話・文法編)
Reading and Writing (読み書き編)

And this is what is actually displayed instead:

Dialogue and Grammar (・)
Reading and Writing (みき)

I can reproduce the same in Zathura (using the mupdf backend) on Arch Linux as well. (In that application, the outline view can be toggled by pressing the Tab key by default.)

[Andrew15-5]

Hmm, interesting. This definitely depends on typst/typst#1889, though I posted a workaround that should be good enough for it to be usable in this case: typst/typst#1889 (comment).

Are you a native Japanese speaker? I see a potential problem of how exactly different users would want the heading in the outline to look like. If there is a standard way for it in Japanese, please let me know. For example, I think it's fair that some would prefer including ruby in the outline (but how exactly should this look like?). If there is a high demand, I think it's fine to introduce 2 ways of doing this, but it can quickly go out of hand and become too complex to maintain all the options.

If the standard way is to strip away the ruby and include just the base text, then it's pretty easy to implement, although on the second thought, the ruby function must be aware of its context, which is not exactly possible. But perhaps a metadata marking approach could work:

#show heading: it => metadata("context", "inside heading") + it + metadata("context", "outside heading)

Or maybe it's better to use state:

#let inside-heading = state("inside heading", false)
#show heading: it => inside-heading.update(true) + it + inside-heading.update(false)

Then it's definitely possible to fetch context inside-heading.get(). Hmm, but the problem here is that using context on a part of the heading will completely remove that part from the outline, because it's an opaque content type and not a string or plain text. I would have to think about it and maybe ask others how they do similar things.

[maxigaz]

I posted a workaround that should be good enough for it to be usable in this case: typst/typst#1889 (comment).

I've given it a try. Setting what should appear in the outline and on the actual pages separately works, but there's a problem: this makes level 2 headings appear as level 1 headings, level 3 as level 2 etc. only in the outline.

source

#import "@preview/rubby:0.10.2": get-ruby

#let ruby = get-ruby(
  size: 0.5em,         // Ruby font size
  dy: 0pt,             // Vertical offset of the ruby
  pos: top,            // Ruby position (top or bottom)
  alignment: "center", // Ruby alignment ("center", "start", "between", "around")
  delimiter: "|",      // The delimiter between words
  auto-spacing: true,  // Automatically add necessary space around words
)

#let chapter(alt, body) = {
  {
    show heading: none
    heading(alt)
  }
  heading(outlined: false, body)
}

// = Dialogue and Grammar (会話・文法編)
// = Dialogue and Grammar (#ruby("かいわ", "会話")・#ruby("ぶんぽう", "文法")#ruby("へん", "編"))

#chapter[Dialogue and Grammar (会話・文法編)][Dialogue and Grammar (#ruby("かいわ", "会話")・#ruby("ぶんぽう", "文法")#ruby("へん", "編"))]

== Test Level 2

=== Test Level 3

=== Test Level 3

== Test Level 2

// = Reading and Writing (読み書き編)
// = Reading and Writing (#ruby("よ", "読")み#ruby("か", "書")き#ruby("へん", "編"))

#chapter[Reading and Writing (読み書き編)][Reading and Writing (#ruby("よ", "読")み#ruby("か", "書")き#ruby("へん", "編"))]

== Test Level 2

=== Test Level 3

=== Test Level 3

== Test Level 2

Here's how it looks in Zathura:

screenshot

And here's how it looks when I don't use the workaround (the levels are correct):

screenshot

Are you a native Japanese speaker?

No, I'm just learning Japanese (on my own), and I'm using Typst for my personal notes.

I see a potential problem of how exactly different users would want the heading in the outline to look like. If there is a standard way for it in Japanese, please let me know. For example, I think it's fair that some would prefer including ruby in the outline (but how exactly should this look like?). If there is a high demand, I think it's fine to introduce 2 ways of doing this, but it can quickly go out of hand and become too complex to maintain all the options.

I'm not aware of any standards or conventions about this either, but I have come across the free book An Introduction to Japanese - Syntax, Grammar & Language, written in XeLaTeX. In the PDF version, on pages iv-vii, the outline contains multiple examples of Kanji written together with Furigana.

[Andrew15-5]

I'll try and remember to come back to the heading levels issue at some point, but sounds like it shouldn't be hard to fix it.

No, I'm just learning Japanese (on my own), and I'm using Typst for my personal notes.

Kewl, a fellow おたく!

I'm not aware of any standards or conventions about this either, but I have come across the free book An Introduction to Japanese - Syntax, Grammar & Language, written in XeLaTeX. In the PDF version, on pages iv-vii, the outline contains multiple examples of Kanji written together with Furigana.

I've looked into it a bit, and you refer to the in-document outline which is completely different from the PDF outline which this issue is about. Here is the equivalent of 5th section's outline:

source

#import "@preview/rubby:0.10.2": get-ruby
#let r = get-ruby() // #r[top][base]

#set text(font: ("Liberation Serif", "Noto Serif CJK JP"))
#set outline.entry(fill: repeat(gap: 0.5em)[.])
#show outline.entry.where(level: 1): set outline.entry(fill: none)
#show outline.entry.where(level: 1): strong
#set heading(numbering: "1.1")
#counter(heading).update(4)

#outline(title: "Table of Contents")
#counter(page).update(221)

= Counters and counting
== Counting
=== Rules for #r[いち][一]
#counter(page).update(225)
=== Rules for #r[さん][三]
=== Rules for #r[ろく][六]
=== Rules for #r[はち][八]
=== Rules for #r[じゅう][十]
=== How many?
=== The rules in summary

output

So you can totally copy it perfectly (with some more set/show rules). The only issue I see here is the line spacing is different when you use ruby vs. when you don't. I suspect that this probably will be impossible or hard to do within rubby, so maybe when typst/typst#4224 is introduced this can be tackled. But I need to do a full rewrite first anyway, only then I can assess the line spacing thing.

But the PDF outline looks like this:

PDF outline screenshot

This confirms the fact that the way you would write the alt text can vary from person to person, since we don't know if a standard way exists. This makes me think that perhaps we should make this an upstream issue that was already mentioned. So users can define their own heading-with-alt function and use it when they want to use rubby in the heading.

[Andrew15-5]

As a side note, I've updated your messages by enclosing the source/screenshots in a details tag to greatly reduce the amount of scrolling required to navigate the comments. (Also as a dark theme enjoyer I don't like bright images, so it helps with that too.) You can see how it's done if you start editing your message.

This is generally preferred in any issue/PR etc. in any project, if you see that it's probably too long. Like there are comments with over 100 lines of code block text (or even more) that takes several seconds to scroll through. Just a rule of thumb. You don't have to use it all the time, but it's better to keep this in mind.

[maxigaz]

I've looked into it a bit, and you refer to the in-document outline which is completely different from the PDF outline which this issue is about.

Oh, yeah. Sorry about that! My mind was preoccupied with a lot of things. I see in your comment that you did address the relevant part (how the author handled naming the outline entries vs. how they appeared on the pages).

As a side note, I've updated your messages by enclosing the source/screenshots in a details tag to greatly reduce the amount of scrolling required to navigate the comments. (Also as a dark theme enjoyer I don't like bright images, so it helps with that too.) You can see how it's done if you start editing your message.

Fair enough. I normally do wrap sections in details tags when an issue or comment body is getting long... except on days when 'stuff happens'. Thanks for the reminder, though!

[Andrew15-5]

I will leave this open until the typst/typst#1889 is implemented. Or if someone will find the one and only proper/standard way of doing it in Japanese documents, if such a thing even exists.

[Andrew15-5]

I've given it a try. Setting what should appear in the outline and on the actual pages separately works, but there's a problem: this makes level 2 headings appear as level 1 headings, level 3 as level 2 etc. only in the outline.

I think it's just some current limitation and the fact that the hack isn't perfect. If you change the order, it does work:

#let chapter(alt, body) = {
  heading(outlined: false, body)
  show heading: none
  heading(alt)
}

But now typst/typst#1889 (comment) becomes an issue again. If PDF outline structure is more important, I think the fact that the click to jump will scroll slightly past the visible title is fine. So it depends on a specific use case.

It looks like the 2nd-level heading is somehow glued to the 1st-level heading that is not bookmarked, and since it's not bookmarked it makes the 2nd-level heading lose its parent and become 1st-level? I would assume that this is a separate bug.

BTW, if you want to have ruby in the table of contents, you should use this instead:

#let chapter(alt, body) = {
  {
    show heading: none
    heading(outlined: false, bookmarked: true, alt)
  }
  heading(bookmarked: false, body)
}

Or if you care more about a correct PDF outline:

#let chapter(alt, body) = {
  heading(bookmarked: false, body)
  show heading: none
  heading(outlined: false, bookmarked: true, alt)
}

[maxigaz]

Or if you care more about a correct PDF outline:

#let chapter(alt, body) = {
  heading(bookmarked: false, body)
  show heading: none
  heading(outlined: false, bookmarked: true, alt)
}

I confirm that it works perfectly. Thank you!