Merged `msgid`s in `messages.pot` caused by improper `SUMMARY.md` lists

[hwhsu1231]

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]

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

[hwhsu1231]

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]

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

[tshepang]

looks odd, but I guess it does not hurt (and it helps @hwhsu1231)