[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
• 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.
    • issue must be in man/build_class.py in which wxGUI is not yet supported

Missing files to be installed (a Makefile issue):

• 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
• C codeblocks should be marked as such rather than bash (e.g. in r.li.daemon manual page), not sure how to automate this

Too complex figure code in HTML

Our HTML style recommendation for figures is not converted properly.

Some figures looks ugly after MD conversion:

• v.fill.holes.html figures
  • see this section and below:

    grass/vector/v.fill.holes/v.fill.holes.html

    Line 13 in fc94e29

    <div align="center" style="margin: 10px">

• v.to.rast3.html figure
• ...
• Caption not properly detected: mkdocs/site/raster3dintro.html

Comment: While pandoc LUA filters might do the job the highly individual HTML code seems to suggest that only manual HTML -> markdown conversion will address these issues. Manual (?) edits will be needed in ~170 files.

[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?