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.

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

DOC: Appendices bookmarks not being generated #227

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

albert-github
Copy link
Contributor

@albert-github albert-github commented Mar 25, 2025

Adding appendices properly to bookmarks. Closes #128.

@github-actions github-actions bot added language:LaTeX Changes to LaTeX code type:BookStyle Changes to book style files type:Documentation Documentation improvement or change labels Mar 25, 2025
@albert-github albert-github marked this pull request as draft March 25, 2025 09:12
@albert-github albert-github marked this pull request as ready for review March 25, 2025 10:35
@dzenanz
Copy link
Member

dzenanz commented Mar 25, 2025

This is how current PDF looks like for me:
Screenshot 2025-03-25 08 35 26
What is this PR trying to change?

@dzenanz
Copy link
Member

dzenanz commented Mar 25, 2025

Now I see #128. But I still see bookmarks (I think that's what the content in the left panel is):
Screenshot 2025-03-25 08 40 24

@albert-github
Copy link
Contributor Author

@dzenanz

I don't see the double appendices / Appendix in the propose patch anymore (see results in the GHA aritfacts: https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/actions/runs/14055782571)

I see with this commit:
image

With the 5.4.2 version I see:

image

Note especially the place of the word appendices and the extra > in the new version, also when collapsing all high level parts we now see:

image

whilst in version 5.24.2 we see:

image

Copy link
Member

@dzenanz dzenanz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the effort on addressing all these issues Albert!

@thewtex thewtex requested a review from jhlegarreta March 25, 2025 14:54
Copy link
Member

@jhlegarreta jhlegarreta left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for doing this @albert-github.

I would please ask you to stick to the ITK commit message guidelines:
https://docs.itk.org/en/stable/contributing/#commit-messages

Please, read the section and do read Chris Beam's post.

Having clear, self-contained messages helps reviewing, and, especially, navigating history.

So

$ git commit --amend

@dzenanz
Copy link
Member

dzenanz commented Mar 28, 2025

Jon, could you please amend the commit with the message you would like to see? That could serve as another example for Albert to learn our preferred norms.

Generate bookmarks for Appendices:
- Transition to a new part using `\part{Appendices}`.
- Transition to the A, B, C numbering using `\appendix`.
- Redefine the `\part` and `\partname` commands to an empty string so
  that the "Part" and part number (name) values are not displayed.
\renewcommand{\thepart}{}
\renewcommand{\partname}{}
\part{Appendices}
\appendix
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if \begin{appendices} and \end{appendices} are kept? I've read that they are better for long documents vs. using \appendix.

@jhlegarreta
Copy link
Member

jhlegarreta commented Mar 29, 2025

Jon, could you please amend the commit with the message you would like to see? That could serve as another example for Albert to learn our preferred norms.

@dzenanz I've done this, but as I've not investigated the fix or possibilities, thoroughly, it is just guesswork or a mere description, so @albert-github I'd be grateful if you could amend the commit message.

Also, as it detaches from the commit message that I put, there is not a single command there that says explicitly which ones makes the bookmarks to be displayed, which should be the whole point of the fix.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
language:LaTeX Changes to LaTeX code type:BookStyle Changes to book style files type:Documentation Documentation improvement or change
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Appendices bookmarks not being generated
3 participants