[Bug] docs: remaining issues with markdown manual using mkdocs

[neteler]

Describe the bug

After the important work in #3849 to enable a markdown based manual using mkdocs this report collects yet open issues.

Prep

Convert HTML files to Markdown: -> see #4620

Issue collection

Manual pages not properly generated (a man/build_*.py issue):

• intro page: missing GUI introduction page --> fixed in docs: add Intro: Graphical User Interface #4746

Missing files to be installed (a Makefile issue):
Fixed in #5048 :

• wxGUI pages: dist.x86_64-pc-linux-gnu/docs/mkdocs/site/wxGUI.md and related are missing from mkdocs:
  • WARNING - Doc file 'g.gui.rdigit.md' contains a link 'wxGUI.md', but the target is not found among documentation files.
  • WARNING - Doc file 'g.gui.rdigit.md' contains a link 'wxGUI.components.md', but the target is not found among documentation files., etc.
• icons: the GUI icons/ directory is yet missing: dist.x86_64-pc-linux-gnu/docs/mkdocs/site/icons/ (see wxGUI.md etc. which needs it)
• barscales PNG files : WARNING - Doc file 'd.barscale.md' contains a link 'barscales/classic.png', but the target is not found among documentation files.
• colortables PNG files : WARNING - Doc file 'd.vect.md' contains a link 'colortables/population_dens.png', but the target is not found among documentation files. etc.
• northarrows PNG files : WARNING - Doc file 'd.northarrow.md' contains a link 'northarrows/9.png', but the target is not found among documentation files.
• further files to be installed into MD space:
  • display/d.graph/grass_logo.txt
  • gui/wxpython/gmodeler/g_gui_gmodeler_zipcodes_avg_elevation.gxm
• some files are not showing up in mkdocs:
  • r.mapcalc, r.colors, ...
  • projectionintro, base files is doc/projectionintro.html

Formatting issues:

• leftover .html: mkdocs warning e.g. "'d.mon.md' contains 'wxGUI.html#map-display-window'" which should be ' 'wxGUI.md#map-display-window' --> fixed in docs: script to convert HTML manual pages to markdown #4620
• keywords: missing dash instead of white space (maybe to be fixed in lib/gis/parser_rest_md.c" line 507?):
  • example dist.x86_64-pc-linux-gnu/docs/mkdocs/site/keywords.html#map management should be dist.x86_64-pc-linux-gnu/docs/mkdocs/site/keywords.html#map-management --> fixed in manual: markdown support fixes and HTML fixes #4807
• keywords: anchors are expected to be lowercase (e.g., #ACCA -> #acca) --> fixed in manual: markdown support fixes and HTML fixes #4807
• topic filenames contain white spaces in MD filenames:
  • 'topic_time management.md': file name should better be 'topic_time_management.md' (underscore rather than white space) --> fixed in manual: markdown support fixes and HTML fixes #4807
• keywords anchors: warnings in build-mkdocs step (cd man; make build-mkdocs):
  • Doc file 'topic_time management.md' contains a link 'keywords.md#time management', but the doc 'keywords.md' does not contain an anchor '#time management'. -> it should be 'keywords.md#time-management'` --> fixed in manual: markdown support fixes and HTML fixes #4807
• JSON codeblocks should be marked as such rather than bash (e.g. in r.report manual page), not sure how to automate this
  • fixed in docs: fix code snippet languages #5095
• C codeblocks should be marked as such rather than bash (e.g. in r.li.daemon manual page), not sure how to automate this
  • fixed in docs: fix code snippet languages #5095

Too complex figure code in HTML

Our HTML style recommendation for figures is not converted properly. This affects ~170 HTML files.

• Some figures looks ugly after MD conversion. For details, see [Bug] Conversion of HTML manual pages to markdown fails for HTML figure code #4864
  • fixed in various PRs

[neteler]

keywords: missing dash instead of white space (maybe to be fixed in lib/gis/parser_rest_md.c" line 507?):

This seems to help:

--- a/lib/gis/parser_rest_md.c
+++ b/lib/gis/parser_rest_md.c
@@ -537,7 +537,7 @@ void print_escaped_for_md_keywords(FILE *f, const char *str)
         else {
             /* keyword index */
             char *str_link;
-            str_link = G_str_replace(str_s, " ", "%20");
+            str_link = G_str_replace(str_s, " ", "-");
             G_str_to_lower(str_link);
             fprintf(f, "[%s](keywords.md#%s)", str_s, str_link);
             G_free(str_link);

Does it make sense, @landam?

==> see attempt in #4807

[neteler]

Help wanted: while most formatting issues are now solved, I need support for the missing files to be installed (see description above): I just don't get why they aren't installed into the "mkdocs" subdirectories?