[gentoo-commits] proj/devmanual:master commit in: appendices/devbook-guide/

["Ulrich Müller" <ulm@gentoo.org>]

commit:     18bdafb3fcd4aa22b70d3102f8e210b2d88cf22f
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sat Jun 21 17:32:07 2025 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Jun 22 08:36:51 2025 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=18bdafb3

devbook-guide: Clarify intra-document references

Apparently, there is confusion about the syntax of intra-document
references; sometimes contributors copy the fragment identifier from
HTML output.

For now, this would produce correct links in HTML output, but it
relies on the properties of the conversion algorithm presently used
in the XSL stylesheet. However, the algorithm was adjusted at least
twice in the past (commit 1fb5bbc, commit 200818b) and may be changed
again in the future.

Therefore, clarify that the "#" separator must be followed by the
literal section title.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 appendices/devbook-guide/text.xml | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml
index e606588..81d8428 100644
--- a/appendices/devbook-guide/text.xml
+++ b/appendices/devbook-guide/text.xml
@@ -552,6 +552,12 @@ I could have written the two examples above in more compact form:
 <uri link="::quickstart/#First ebuild"/>, respectively.
 </p>
 
+<important>
+The component after the octothorpe must be the <e>literal</e> section title.
+Don't copy the fragment identifier from HTML output! So, in the above example,
+it is not <c>#first-ebuild</c> but <c>#First ebuild</c>.
+</important>
+
 </body>
 </subsection>
 </section>