util/util_readme: Use HTML comments in generated output
commitb6f3ee3f8f79fc4f07515f275442128dad9d8ce9
authorNicholas Chin <nic.c3.14@gmail.com>
Sun, 27 Oct 2024 22:23:45 +0000 (27 16:23 -0600)
committerFelix Singer <service+coreboot-gerrit@felixsinger.de>
Sun, 27 Oct 2024 23:50:57 +0000 (27 23:50 +0000)
tree08aa78b3386ea03e2065dba80de6b9e507e4927e
parent10d22313f70593c5ea8965aceb7cf5e862ad5221
util/util_readme: Use HTML comments in generated output

Util_readme adds comments to the top of the generated Doc/util.md file
to indicate that it is generated and should not be edited directly.
These comments are not intended to show up in the rendered HTML output.
Since Markdown does not have a native way of adding comments, the
`[comment text]: #` syntax is often used to mark the line as a comment.
This takes advantage of the fact that references (often used throughout
the docs to list long URLs at the end of the document and reference them
in inline links) aren't rendered. However, MyST parser detects these as
a duplicate reference and issues a warning, since both lines use "//" as
the comment text.

Address this by using HTML comments, since Markdown also allows raw HTML
to be used. This seems like a cleaner option compared to repurposing
references and appears to have better compatibility with various
Markdown readers, which may be useful if someone wants to read the
documentation outside of doc.coreboot.org.

While we are here, regenerate Documentation/util.md and util/README.md

Change-Id: Ibd4f61009c01c7b64594d88c5d86e472f0ccaa6c
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/84885
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
Documentation/util.md
util/README.md
util/util_readme/util_readme.sh