From a7e7070fcf4435e6537c6ad6427eb877f75346d5 Mon Sep 17 00:00:00 2001
From: mgrojo <mgrojo@gmail.com>
Date: Sat, 23 Sep 2023 18:24:29 +0200
Subject: [PATCH 1/2] Add Help page with generated markdown output for all
 commands and topics

---
 _config.yml        |  1 +
 docs/index-alr.md  | 73 ++++++++++++++++++++++++++++++++++++++++++++++
 update-gh-pages.sh |  5 ++++
 3 files changed, 79 insertions(+)
 create mode 100644 docs/index-alr.md

diff --git a/_config.yml b/_config.yml
index b29f531b..26680646 100644
--- a/_config.yml
+++ b/_config.yml
@@ -46,6 +46,7 @@ header_pages:
   - crates.md
   - search.html
   - docs/index.md
+  - docs/index-alr.md
 
 # Devlopr
 author_logo: profile.png
diff --git a/docs/index-alr.md b/docs/index-alr.md
new file mode 100644
index 00000000..b93e81b1
--- /dev/null
+++ b/docs/index-alr.md
@@ -0,0 +1,73 @@
+---
+title: Help
+description: "alr manual pages"
+layout: default
+---
+<div class="card">
+  <style>
+/* Create two equal columns that floats next to each other */
+.doc_toc {
+  float: left;
+  width: 15em;
+}
+
+.doc_content {
+  float: left;
+  width: calc(100% - 15em);
+}
+
+/* Clear floats after the columns */
+.doc_row:after {
+  content: "";
+  display: table;
+  clear: both;
+}
+
+/* Responsive layout - makes the two columns stack on top of each other instead
+of next to each other */
+
+@media screen and (max-width: 60em) {
+  .doc_toc {
+    width: 100%;
+  }
+  .doc_content {
+    width: 100%;
+  }
+}
+
+/* Table-of-content style */
+#markdown-toc {
+  padding-left: 1em;
+  font-size: smaller;
+}
+#markdown-toc ul {
+  padding-left: 1em;
+}
+
+
+</style>
+<div class="doc_row">
+ <div class="doc_toc">
+  <div markdown="1">
+
+   * Do not remove this line (it will not be displayed)
+   {:toc}
+
+  </div>
+  <small style="color:#808080">
+      This help documentation has been generated from the builtin `alr` help
+      messages. Don't hesitate to suggest fix(es) and/or improvement(s) in
+      the <a href="https://github.com/alire-project/alire/src/alr">GitHub
+      repository.</a>
+  </small>
+ </div>
+  <div class="doc_content" markdown="1">
+
+ <!-- All the empty lines below, as well as the absence of indentation, seem to
+   be required for a correct parsing of the markdown files -->
+
+{% include_relative alr.md %}
+
+  </div>
+ </div>
+</div>
diff --git a/update-gh-pages.sh b/update-gh-pages.sh
index 7145a0d9..0da6b2bc 100644
--- a/update-gh-pages.sh
+++ b/update-gh-pages.sh
@@ -65,6 +65,11 @@ cp alire/doc/* docs/
 # Append the built-ins config doc generated from the tool
 alr --no-tty config --builtins-doc >> docs/configuration.md
 
+# Add the `alr` help page
+# Substitution is needed because <placeholder> from messages are interpreted by Jekyll
+# TODO This can be removed if all these <placeholders> are quoted as `code`.
+alr dev --markdown-help | sed 's/</`<`/g; s/>/`>`/g' > docs/alr.md
+
 # Cleanup alire repo
 rm -rf alire/
 

From 220e08f9125d38c3ac189f317b450d5638618610 Mon Sep 17 00:00:00 2001
From: mgrojo <mgrojo@gmail.com>
Date: Sat, 14 Oct 2023 20:08:46 +0200
Subject: [PATCH 2/2] Update the switch name for markdown and replace
 workaround by check

---
 update-gh-pages.sh | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/update-gh-pages.sh b/update-gh-pages.sh
index 0da6b2bc..088d60ae 100644
--- a/update-gh-pages.sh
+++ b/update-gh-pages.sh
@@ -66,9 +66,15 @@ cp alire/doc/* docs/
 alr --no-tty config --builtins-doc >> docs/configuration.md
 
 # Add the `alr` help page
-# Substitution is needed because <placeholder> from messages are interpreted by Jekyll
-# TODO This can be removed if all these <placeholders> are quoted as `code`.
-alr dev --markdown-help | sed 's/</`<`/g; s/>/`>`/g' > docs/alr.md
+alr dev --help-doc-markdown > docs/alr.md
+
+# Warn if there are any unquoted <placeholder> from messages, since they are
+# incorrectly evaluated by Jekyll and the format will be broken.
+# When this happens, the probable solution is to wrap these placeholders with
+# CLIC.Formatter.Terminal
+if grep -Hn '<[a-z_]*>' docs/alr.md | grep -v '`' ; then
+    echo 'Warning: <placeholder> found not quoted as `code` in docs/alr.md' >&2
+fi
 
 # Cleanup alire repo
 rm -rf alire/