Skip to content

Merged msgids in messages.pot caused by improper SUMMARY.md lists #2341

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
Open
hwhsu1231 opened this issue Apr 18, 2025 · 3 comments · May be fixed by #2343
Open

Merged msgids in messages.pot caused by improper SUMMARY.md lists #2341

hwhsu1231 opened this issue Apr 18, 2025 · 3 comments · May be fixed by #2343

Comments

@hwhsu1231
Copy link

Problem Description

Recently, I attempted to use the mdbook-i18n-helper preprocessor to generate Gettext .po translation files for the rustc-dev-guide. However, I encountered some unexpected msgid content in the generated messages.pot file.

For example:

#: src/SUMMARY.md:3
msgid "Getting Started About this guide"
msgstr ""

#: src/SUMMARY.md:231
msgid ""
"Appendix A: Background topics Appendix B: Glossary Appendix C: Code Index "
"Appendix D: Compiler Lecture Series Appendix E: Bibliography"
msgstr ""

These msgids correspond to the following lines in SUMMARY.md:

rustc-dev-guide/src/SUMMARY.md

Lines 3 to 4 in 8e69daa

[Getting Started](./getting-started.md)
[About this guide](./about-this-guide.md)

rustc-dev-guide/src/SUMMARY.md

Lines 232 to 236 in 8e69daa

[Appendix A: Background topics](./appendix/background.md)
[Appendix B: Glossary](./appendix/glossary.md)
[Appendix C: Code Index](./appendix/code-index.md)
[Appendix D: Compiler Lecture Series](./appendix/compiler-lecture.md)
[Appendix E: Bibliography](./appendix/bibliography.md)

It turns out that these lines are not written in proper Markdown list format.

Possible Solutions

The correct way to format these entries is as bullet lists, like so:

- [Getting Started](./getting-started.md)
- [About this guide](./about-this-guide.md)
- [Appendix A: Background topics](./appendix/background.md)
- [Appendix B: Glossary](./appendix/glossary.md)
- [Appendix C: Code Index](./appendix/code-index.md)
- [Appendix D: Compiler Lecture Series](./appendix/compiler-lecture.md)
- [Appendix E: Bibliography](./appendix/bibliography.md)

Writing the entries as proper Markdown lists ensures that Gettext can extract each item into a separate msgid, rather than merging them into a single line.

Demo Commands

git clone --depth=1 https://github.com/rust-lang/rustc-dev-guide.git
cd rustc-dev-guide
conda create --prefix ./.conda --yes
conda activate ./.conda
conda install conda-forge::rust conda-forge::openssl --channel conda-forge --yes
export PATH=$(pwd)/.conda/bin:${PATH}
export LD_LIBRARY_PATH=$(pwd)/.conda/lib:${LD_LIBRARY_PATH}
cargo install mdbook mdbook-toc mdbook-mermaid mdbook-linkcheck2 mdbook-i18n-helpers --root ./.conda
export MDBOOK_OUTPUT='{"xgettext":{}}'
mdbook build --dest-dir ./po
kate ./po/messages.pot
@jieyouxu
Copy link
Member

jieyouxu commented Apr 18, 2025 •
edited
Loading

AFAIK this is not a bug, this is what mdBook SUMMARY.md suffix syntax requires.

@hwhsu1231 hwhsu1231 mentioned this issue Apr 18, 2025
Closed
@hwhsu1231
Copy link
Author

hwhsu1231 commented Apr 18, 2025 •
edited
Loading

AFAIK this is not a bug, this is what mdBook SUMMARY.md suffix syntax requires.

@jieyouxu Got it. Then, what about adding a blank line between each of the prefix/suffix chapters. For example:

[Getting Started](./getting-started.md)

[About this guide](./about-this-guide.md)
[Appendix A: Background topics](./appendix/background.md)

[Appendix B: Glossary](./appendix/glossary.md)

[Appendix C: Code Index](./appendix/code-index.md)

[Appendix D: Compiler Lecture Series](./appendix/compiler-lecture.md)

[Appendix E: Bibliography](./appendix/bibliography.md)

@jieyouxu
Copy link
Member

cc @tshepang if you have any opinions, I don't really write enough mdBook to know if this makes a difference

@hwhsu1231 hwhsu1231 linked a pull request Apr 18, 2025 that will close this issue
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
2 participants
@jieyouxu @hwhsu1231