Doc updates

[moschmdt]

Changes see commit messages.

Points for discussion:

1. The default Markdownlint settings do not allow multiple equal headings in the same document which is used extensively in the CLI docs. It would be possible to allow this setting in the .markdownlint.json file via the MD024 rule configuration.
   Pipelines will fail because of this!

2. A similar problem appears when generating the PDF based on Markdown files since the file name is scraped of the link, e.g. cmd_soar.md#synopsis $\rightarrow$ #synopsis and cmd_print.md#synopsis $\rightarrow$ #synopsis, in the final document. A possible solution/ suggestion is to either discourage linking against synopsis, explanation and usage chapters or always append the command, e.g. Synopsis becomes Synopsis Print?

[garfieldnate]

1. Definitely want the pipelines to all succeed. What is the issue with adding the exception to the lint configuration? It seems like a content style suggestion more than a markdown suggestion to me, and I'd rather treat content updates as a separate issue when we feel it is necessary.
2. I didn't understand this point, but would it be fixed by disabling that lint?

[moschmdt]

Sorry for the late answer, apparently missed the notification.

1. Partially agree, the rationale of MD024 provides the explanation.

2. For instance, the PDF version of the Soar manual is generated in the following way: all Markdown documents are summarized in a single intermediate document by pandoc prior to conversion to PDF. This also includes all reference/cli docs. In the intermediate document, the
   links are manipulated by the luafilter, cf. path_filter.lua. As a consequence, multiple similar headings can occur and links may not longer be unique.