manual: markdown support fixes and HTML fixes (#4807)

This PR addresses issues identified in #4748: Manual pages: - fixes of broken HTML tags, href entries and broken URLs not converted properly - fix title of `lib/btree2/btree2lib.dox` Markdown support in build system: - `.html` -> `.md` file extension fixes - replace white space in keyword anchors with dash (expected by mkdocs) - avoid white space in "topics" file names - avoid ":" in title (looks bad in side menu) - reorder mkdocs navigation menu and add missing entries (`man/mkdocs/mkdocs.yml`)
OSGeo · Dec 6, 2024 · f3405fe · f3405fe
1 parent 83537f7
commit f3405fe
Show file tree

Hide file tree

Showing 40 changed files with 102 additions and 89 deletions.
diff --git a/gui/wxpython/rlisetup/g.gui.rlisetup.html b/gui/wxpython/rlisetup/g.gui.rlisetup.html
@@ -328,7 +328,7 @@ <h2>REFERENCES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="r.li.daemon.html">r.li.daemon</a>
 </em>
 <p>

diff --git a/imagery/i.rectify/i.rectify.html b/imagery/i.rectify/i.rectify.html
@@ -144,9 +144,9 @@ <h3>Resampling method</h3>
 <p>In the bilinear, cubic and lanczos methods, if any of the surrounding cells used to
 interpolate the new cell value are NULL, the resulting cell will be NULL, even if
 the nearest cell is not NULL. This will cause some thinning along NULL borders,
-such as the coasts of land areas in a DEM. The bilinear_f, cubic_f and lanczos_f
-interpolation methods can be used if thinning along NULL edges is not desired.
-These methods "fall back" to simpler interpolation methods along NULL borders.
+such as the coasts of land areas in a DEM. The <em>bilinear_f</em>, <em>cubic_f</em>
+and <em>lanczos_f</em> interpolation methods can be used if thinning along NULL edges is
+not desired. These methods "fall back" to simpler interpolation methods along NULL borders.
 That is, from lanczos to cubic to bilinear to nearest.
 <p>If nearest neighbor assignment is used, the output map has the same raster
 format as the input map. If any of the other interpolations is used, the

diff --git a/imagery/i.smap/i.smap.html b/imagery/i.smap/i.smap.html
@@ -10,18 +10,17 @@ <h2>DESCRIPTION</h2>
 
 <p>
 <em>i.smap</em> has two modes of operation. The first mode
-is the sequential maximum a posteriori (SMAP) mode
-[<a href="#ref1">1</a>,<a href="#ref2">2</a>].  The SMAP
+is the sequential maximum a posteriori (SMAP) mode (see
+Bouman and Shapiro, 1992; Bouman and Shapiro, 1994). The SMAP
 segmentation algorithm attempts to improve segmentation
 accuracy by segmenting the image into regions rather than
-segmenting each pixel separately
-(see <a href="#notes">NOTES</a>).
+segmenting each pixel separately (see NOTES below).
 
 <p>
 The second mode is the more conventional maximum likelihood (ML)
 classification which classifies each pixel separately,
 but requires somewhat less computation. This mode is selected with
-the <b>-m</b> flag (see <a href="#mflag.html">below</a>).
+the <b>-m</b> flag (see below).
 
 <h2>OPTIONS</h2>
 
@@ -30,9 +29,7 @@ <h3>Flags:</h3>
 <dl>
 <dt><b>-m</b>
 <dd>Use maximum likelihood estimation (instead of smap).
-Normal operation is to use SMAP estimation (see
-<a href="#notes">NOTES</a>).
-
+Normal operation is to use SMAP estimation (see NOTES below).
 </dl>
 
 <h3>Parameters:</h3>
@@ -57,7 +54,7 @@ <h3>Parameters:</h3>
 statistics) for the classes to be identified in the image.
 This signature file is produced by the program
 <em><a href="i.gensigset.html">i.gensigset</a></em>
-(see <a href="#notes">NOTES</a>).
+(see NOTES below).
 
 <dt><b>blocksize=</b><em>value</em>
 
@@ -102,7 +99,7 @@ <h3>Parameters:</h3>
 </dl>
 
 
-<h2 id="notes">NOTES</h2>
+<h2>NOTES</h2>
 
 The SMAP algorithm exploits the fact that nearby pixels in
 an image are likely to have the same class.  It works by
@@ -129,8 +126,9 @@ <h2 id="notes">NOTES</h2>
 <p>
 The module <em>i.smap</em> does not support MASKed or NULL cells. Therefore
 it might be necessary to create a copy of the classification results
-using e.g. r.mapcalc:
-<p><div class="code"><pre>
+using e.g. <em>r.mapcalc</em>:
+<p>
+<div class="code"><pre>
 r.mapcalc "MASKed_map = classification_results"
 </pre></div>
 
@@ -216,10 +214,10 @@ <h2>SEE ALSO</h2>
 <a href="r.support.html">r.support</a></em> for setting semantic labels,
 <br>
 <em>
-<a href="i.group.html">i.group</a></em> for creating groups and subgroups
+<a href="i.group.html">i.group</a></em> for creating groups and subgroups,
 <br>
 <em><a href="r.mapcalc.html">r.mapcalc</a></em>
-to copy classification result in order to cut out MASKed subareas
+to copy classification result in order to cut out MASKed subareas,
 <br>
 <em><a href="i.gensigset.html">i.gensigset</a></em>
 to generate the signature file required by this program

diff --git a/imagery/imageryintro.html b/imagery/imageryintro.html
@@ -246,8 +246,8 @@ <h3>Radiometric corrections</h3>
 
 <h3>Time series processing</h3>
 
-GRASS also offers support for time series processing (<a
-href="r.series.html">r.series</a>). Statistics can be derived from a
+GRASS also offers support for time series processing
+(<a href="r.series.html">r.series</a>). Statistics can be derived from a
 set of coregistered input maps such as multitemporal satellite
 data. The common univariate statistics and also linear regression can
 be calculated.

diff --git a/lib/btree2/btree2lib.dox b/lib/btree2/btree2lib.dox
@@ -1,4 +1,4 @@
-/*! \page btree2 btree2 library
+/*! \page btree2 GRASS Btree2 and k-d tree libraries
 
 \tableofcontents
 

diff --git a/lib/gis/parser_rest_md.c b/lib/gis/parser_rest_md.c
@@ -503,7 +503,7 @@ void print_escaped_for_md_keywords(FILE *f, const char *str)
     str_s = G_store(str);
     G_strip(str_s);
 
-    /* HTML link only for second keyword */
+    /* HTML link only for second keyword = topic */
     if (st->n_keys > 1 && strcmp(st->module_info.keywords[1], str) == 0) {
 
         const char *s;
@@ -535,9 +535,9 @@ void print_escaped_for_md_keywords(FILE *f, const char *str)
             fprintf(f, ".md)");
         }
         else {
-            /* keyword index */
+            /* keyword index, mkdocs expects dash */
             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);

diff --git a/man/build_md.py b/man/build_md.py
@@ -193,15 +193,15 @@
 )
 
 modclass_intro_tmpl = string.Template(
-    r"""Go to [${modclass} introduction](${modclass_lower}intro.html) | [topics](topics.html)
+    r"""Go to [${modclass} introduction](${modclass_lower}intro.md) | [topics](topics.md)
 """
 )
 # "
 
 
 modclass_tmpl = string.Template(
     r"""Go [back to help overview](index.md)
-### ${modclass} commands:
+### ${modclass} commands
 | Module | Description |
 |--------|-------------|
 """
@@ -217,7 +217,7 @@
 
 moduletopics_tmpl = string.Template(
     r"""
-- [${name}](topic_${key}.html)
+- [${name}](topic_${key}.md)
 """
 )
 

diff --git a/man/build_topics.py b/man/build_topics.py
@@ -78,7 +78,9 @@ def build_topics(ext):
         topicsfile.write(headertopics_tmpl)
 
         for key, values in sorted(keywords.items(), key=lambda s: s[0].lower()):
-            with Path(man_dir, f"topic_%s.{ext}" % key).open("w") as keyfile:
+            with Path(man_dir, f"topic_%s.{ext}" % key.replace(" ", "_")).open(
+                "w"
+            ) as keyfile:
                 if ext == "html":
                     keyfile.write(
                         header1_tmpl.substitute(
@@ -125,7 +127,7 @@ def build_topics(ext):
                         "*See also the corresponding keyword"
                         " [{key}](keywords.md#{key})"
                         " for additional references.*\n".format(
-                            key=key.replace("_", " ")
+                            key=key.replace(" ", "-").replace("_", "-").lower()
                         )
                     )
 

diff --git a/man/mkdocs/mkdocs.yml b/man/mkdocs/mkdocs.yml
@@ -28,14 +28,16 @@ nav:
   - Display: display.md
   - General: general.md
   - Imagery: imagery.md
-  - Keywords: keywords.md
   - Misc: miscellaneous.md
+  - Postscript: postscript.md
   - Raster: raster.md
   - Raster 3D: raster3d.md
   - SQL: sql.md
   - Temporal: temporal.md
   - Variables: variables.md
   - Vector: vector.md
+  - Keywords: keywords.md
+  - Topics: topics.md
 markdown_extensions:
   - admonition
   - pymdownx.details

diff --git a/raster/r.basins.fill/r.basins.fill.html b/raster/r.basins.fill/r.basins.fill.html
@@ -31,8 +31,8 @@ <h2>NOTES</h2>
 
 <h2>SEE ALSO</h2>
 
-See Appendix A of the <b>GRASS</b> <a
-href="https://grass.osgeo.org/gdp/raster/r.watershed.ps">Tutorial:
+See Appendix A of the <b>GRASS</b>
+<a href="https://grass.osgeo.org/gdp/raster/r.watershed.ps">Tutorial:
 r.watershed</a> for further details on the combined use of
 <em>r.basins.fill</em> and <em>r.watershed</em>.
 

diff --git a/raster/r.in.poly/r.in.poly.html b/raster/r.in.poly/r.in.poly.html
@@ -8,7 +8,7 @@ <h2>DESCRIPTION</h2>
 The <b>input</b> file is an ASCII text file containing the
 polygon, linear, and point feature definitions.
 The format of this file is described in the
-<a href="#format"><i>INPUT FORMAT</i></a> section below.
+<em>INPUT FORMAT</em> section below.
 
 <p>
 The number of raster <b>rows</b> to hold in memory is per default 4096.
@@ -31,7 +31,7 @@ <h2>NOTES</h2>
 <p>
 Polygons are filled, i.e. they define an area.
 
-<h3 id="format">Input Format</h3>
+<h3>Input Format</h3>
 
 The input format for the <b>input</b> file consists of
 sections describing either polygonal areas, linear features, or

diff --git a/raster/r.li/r.li.cwed/r.li.cwed.html b/raster/r.li/r.li.cwed/r.li.cwed.html
@@ -60,7 +60,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.dominance/r.li.dominance.html b/raster/r.li/r.li.dominance/r.li.dominance.html
@@ -60,7 +60,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.edgedensity/r.li.edgedensity.html b/raster/r.li/r.li.edgedensity/r.li.edgedensity.html
@@ -81,7 +81,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.mpa/r.li.mpa.html b/raster/r.li/r.li.mpa/r.li.mpa.html
@@ -68,7 +68,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.mps/r.li.mps.html b/raster/r.li/r.li.mps/r.li.mps.html
@@ -70,7 +70,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.padcv/r.li.padcv.html b/raster/r.li/r.li.padcv/r.li.padcv.html
@@ -60,7 +60,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.padrange/r.li.padrange.html b/raster/r.li/r.li.padrange/r.li.padrange.html
@@ -62,7 +62,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.padsd/r.li.padsd.html b/raster/r.li/r.li.padsd/r.li.padsd.html
@@ -62,7 +62,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.patchdensity/r.li.patchdensity.html b/raster/r.li/r.li.patchdensity/r.li.patchdensity.html
@@ -73,7 +73,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.patchnum/r.li.patchnum.html b/raster/r.li/r.li.patchnum/r.li.patchnum.html
@@ -56,7 +56,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.pielou/r.li.pielou.html b/raster/r.li/r.li.pielou/r.li.pielou.html
@@ -59,7 +59,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.renyi/r.li.renyi.html b/raster/r.li/r.li.renyi/r.li.renyi.html
@@ -62,7 +62,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.richness/r.li.richness.html b/raster/r.li/r.li.richness/r.li.richness.html
@@ -59,7 +59,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.shannon/r.li.shannon.html b/raster/r.li/r.li.shannon/r.li.shannon.html
@@ -60,7 +60,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.shape/r.li.shape.html b/raster/r.li/r.li.shape/r.li.shape.html
@@ -61,7 +61,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.li/r.li.simpson/r.li.simpson.html b/raster/r.li/r.li.simpson/r.li.simpson.html
@@ -60,7 +60,7 @@ <h2>EXAMPLES</h2>
 <h2>SEE ALSO</h2>
 
 <em>
-<a href="r.li.html">r.li</a> - package overview,
+<a href="r.li.html">r.li</a> (package overview),
 <a href="g.gui.rlisetup.html">g.gui.rlisetup</a>
 </em>
 

diff --git a/raster/r.quantile/r.quantile.html b/raster/r.quantile/r.quantile.html
@@ -30,10 +30,9 @@ <h2>REFERENCES</h2>
 <ul>
 <li>Hyndman and Fan (1996) <i>Sample Quantiles in Statistical
 Packages</i>, <b>American Statistician</b>. American Statistical
-Association. 50 (4): 361-365. DOI: <a
-href="https://doi.org/10.2307/2684934>10.2307/2684934">10.2307/2684934</a></li>
-<li><a
-href="https://www.itl.nist.gov/div898/handbook/prc/section2/prc262.htm"><i>Engineering
+Association. 50 (4): 361-365. DOI:
+<a href="https://doi.org/10.2307/2684934>10.2307/2684934">10.2307/2684934</a></li>
+<li> <a href="https://www.itl.nist.gov/div898/handbook/prc/section2/prc262.htm"><i>Engineering
 Statistics Handbook: Percentile</i></a>, NIST</li>
 </ul>