Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Allow different headings and captions in outline and bookmark #4643

Closed
wants to merge 2 commits into from
Closed

Allow different headings and captions in outline and bookmark #4643

wants to merge 2 commits into from

Conversation

EpicEricEE
Copy link
Contributor

Closes #1889, closes #1295, implements #1892 (comment).

Summary

Added a (non-exposed) outlined-content element to be used for figure captions and headings. It is created internally by casting the dictionary

(
  document: [...],
  outline: [...],
  bookmark: "...",
)

where only the key document is required for the default value. If any of the other keys are omitted, outline is derived from the default value, and bookmark from the outline value. The bookmark value has to be of a string, while the other two can be any content. If this dictionary is not used when passing the body of a heading or figure caption, the element is still created implicitly with all fields having the same value (bookmark being converted to a string).

Example

Code Output 
#show outline: set heading(outlined: true)

#outline(title: (
  document: [Outline],
  outline: [Outline in Outline]
))

#outline(title: "Figures", target: figure)

#heading((
  document: [Document Heading],
  outline: [Outline Heading],
  bookmark: "Bookmark Heading"
))

#figure(
  rect(),
  caption: (
    document: [A rectangle],
    outline: [A rect in the outline]
  )
)

Example Output

Notes

  • The title parameter of outline and bibliography elements also supports this new type.
  • You can currently still specify the bookmark option for figure captions, even though it won't be displayed anywhere.
  • In show rules, the heading.body and figure.caption.body elements are now of the type outlined-content which always has the fields document, outline and bookmark available. The type itself also has a show rule and returns the document value by default.
  • I decided to only go for the document / outline / bookmark style and not also for long / short because long would only be a synonym for document, and because bookmark inherits its value from outline, so short would also basically only be a synonym for outline (when bookmark is not set).

To-do

  • Decide on name of element (I don't really like outlined-content but couldn't think of anything better)
  • Decide whether the outlined and bookmarked parameters of headings should somehow be replaced by this
  • Maybe improve documentation

@MDLC01
Copy link
Contributor

MDLC01 commented Aug 9, 2024

Doesn't this make heading's outlined and outlined, and figure's outline parameters obsolete? Because with this PR I feel like this could be done simply by setting the corresponding argument to none or some content / string.

@EpicEricEE
Copy link
Contributor Author

That's what I meant with the second to-do item.

One drawback is that something like show heading.where(level: 3): set heading(bookmarked: false) wouldn't be possible anymore, or at least not as easy. This is also the case for things like adding the outline in the outline (or removing the bibliography, etc.), as it is now usually done via show outline: set heading(outlined: true)

@laurmaedje laurmaedje added the waiting-on-review This PR is waiting to be reviewed. label Aug 15, 2024
@PgBiel
Copy link
Contributor

PgBiel commented Aug 20, 2024

Regarding the design, in principle this is already possible for arbitrary content in any context using state, at least for the outline. I wonder, therefore, if the only further step we need to take is to expose such an API (which applies to more general contexts as well) but more ergonomically. Though I do understand the appeal of a more minimal API, but maybe this is currently a bit too minimal / ad-hoc? Or are there going to be extra features within heading and figure themselves which integrate with / are aware of the dictionary separating normal, outline and bookmark content?

@EpicEricEE
Copy link
Contributor Author

Regarding the design, in principle this is already possible for arbitrary content in any context using state, at least for the outline.

Indeed. It would still require something for the bookmarked title though.

I wonder, therefore, if the only further step we need to take is to expose such an API (which applies to more general contexts as well) but more ergonomically.

Do you mean something in the likes of (exact design aside)

#heading(context if inside(outline) [ ... ] else [ ... ])

which would resemble the behavior of the commonly used in-outline state but internally? I agree that something more generally applicable would be nice.

Or are there going to be extra features within heading and figure themselves which integrate with / are aware of the dictionary separating normal, outline and bookmark content?

A nice to have would be to allow configuration of whether the heading number should be part of the bookmarked title, but that doesn't seem to be something that can be implemented nicely with either design.

@laurmaedje
Copy link
Member

I generally like the context-based solution, though I see how even just context if inside(outline) [ ... ] else [ ... ] might be a bit alienating and feel too complex for inclusion in the non-template prose part of a document.

As for the bookmark: Is it truly necessary to distinguish between the outline and the bookmark text or could the bookmark just always resolve to the outline variant?

@laurmaedje laurmaedje added waiting-on-design This PR or issue is blocked by design work. and removed waiting-on-review This PR is waiting to be reviewed. labels Aug 26, 2024
@laurmaedje
Copy link
Member

laurmaedje commented Sep 26, 2024 •
edited
Loading

It seems to me that we need more discussion (ideally on Discord) before settling on a solution, so I'll close this for now. Thanks still!

@laurmaedje laurmaedje closed this Sep 26, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
waiting-on-design This PR or issue is blocked by design work.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Different heading text for outline/bookmark and displaying Short figure caption for outline
4 participants
@EpicEricEE @MDLC01 @PgBiel @laurmaedje