Skip to content

Commit

Permalink
doc: Convert HTML to Markdown (#1332)
Browse files Browse the repository at this point in the history 
This converts HTML markup in .md files to Markdown using the ./utils/grass_html2md.sh script from core.

In addition to the automatic conversion it:

- Does basic whitespace cleanup (esp. double whitespace in lists).
- Removes empty first line for v.area.stats.
- Uses text code blocks where appropriate for i.sentinel.preproc.
- Specifies text for r.fuzzy.system code blocks with syntax and explanation examples.
- Disable the fix for valid r.fuzzy.system syntax.

It further adjusts linting to accommodate the auto-converted Markdown.

It does not touch r.landscape.evol because that tool has already had Markdown documentation (which needs to be revised manually as needed). Block quotes in r.green tools will also need extra revisions later.
  • Loading branch information
@wenzeslaus
wenzeslaus authored Feb 20, 2025
1 parent a5ff8c1 commit 53de819
Show file tree
Hide file tree
Showing 487 changed files with 33,663 additions and 35,626 deletions.
10 changes: 10 additions & 0 deletions .markdownlint.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@ first-line-h1: false
# Errors from .html to .md rename (first step in HTML to Markdown conversion)
heading-increment: false
heading-style: false
no-emphasis-as-heading: false
no-blanks-blockquote: false
no-multiple-space-blockquote: false
ul-style: false
ul-indent: false
no-trailing-spaces: false
Expand All @@ -29,10 +32,17 @@ ol-prefix: false
blanks-around-lists: false
no-inline-html: false
no-bare-urls: false
no-space-in-links: false
no-empty-links: false
no-space-in-emphasis: false
no-alt-text: false
emphasis-style: false
reference-links-images: false
table-pipe-style: false
table-column-count: false
blanks-around-tables: false
# The block above this is to be eventually removed.

# The warning is triggered even for code blocks with language set to text,
# so r.fuzzy.system syntax triggers the warning even when completely valid.
commands-show-output: false
1 change: 1 addition & 0 deletions .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ repos:
- id: trailing-whitespace
exclude: |
(?x)^(
.*\.md$|
.*\.ascii$|
.*\.ref$|
.*\.diff$|
Expand Down
39 changes: 18 additions & 21 deletions src/db/db.join/db.join.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,18 @@
<h2>DESCRIPTION</h2>
## DESCRIPTION

<em>db.join</em> joins the content of one attribute table into another
*db.join* joins the content of one attribute table into another
attribute table through common attributes.

<h2>NOTES</h2>
## NOTES

<em>db.join</em> is a front-end to <em>db.execute</em> to allow easier usage.

The attribute table must be stored in a SQL database (SQLite, PostgreSQL,
*db.join* is a front-end to *db.execute* to allow easier usage. The
attribute table must be stored in a SQL database (SQLite, PostgreSQL,
MySQL, ODBC, ...). The DBF backend is not supported. Tables can be
imported with <em>db.in.ogr</em>.

<h2>EXAMPLES</h2>
imported with *db.in.ogr*.

## EXAMPLES

<div class="code"><pre>
```sh
# join soils_legend into mysoils attribute table
db.join mysoils col=label otable=soils_legend ocol=shortname

Expand All @@ -27,19 +25,18 @@ cat|label|id|shortname|longname
4|BcB|4|BcB|Boneek silt loam, 2 to 6
5|BcC|5|BcC|Boneek silt loam, 6 to 9
...
</pre></div>
```

<h2>SEE ALSO</h2>
## SEE ALSO

<em>
<a href="https://grass.osgeo.org/grass-stable/manuals/db.execute.html">db.execute</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/db.in.ogr.html">db.in.ogr</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/db.select.html">db.select</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/v.db.join.html">v.db.join</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/v.db.update.html">v.db.update</a><br>
<a href="https://grass.osgeo.org/grass-stable/manuals/sql.html">GRASS SQL interface</a>
</em>
*[db.execute](https://grass.osgeo.org/grass-stable/manuals/db.execute.html),
[db.in.ogr](https://grass.osgeo.org/grass-stable/manuals/db.in.ogr.html),
[db.select](https://grass.osgeo.org/grass-stable/manuals/db.select.html),
[v.db.join](https://grass.osgeo.org/grass-stable/manuals/v.db.join.html),
[v.db.update](https://grass.osgeo.org/grass-stable/manuals/v.db.update.html)
[GRASS SQL
interface](https://grass.osgeo.org/grass-stable/manuals/sql.html)*

<h2>AUTHOR</h2>
## AUTHOR

Markus Neteler
136 changes: 58 additions & 78 deletions src/display/d.explanation.plot/d.explanation.plot.md
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,46 @@
<h2>DESCRIPTION</h2>
## DESCRIPTION

<em>d.explantion.plot</em> creates a plot of rasters and their relations
which can serve as an explanation of a raster operation performed by
a module or function.
*d.explantion.plot* creates a plot of rasters and their relations which
can serve as an explanation of a raster operation performed by a module
or function.

<p>
Up to four rasters are supported. The default operators assume rasters to
have the following relation:
Up to four rasters are supported. The default operators assume rasters
to have the following relation:

<p><em>
a + b -> c
</em></p>
*a + b -\> c*

## EXAMPLES

<h2>EXAMPLES</h2>

<h3>Example using generated data</h3>
### Example using generated data

In Bash:

<div class="code"><pre>
```sh
g.region n=99 s=0 e=99 w=0 rows=3 cols=3
r.mapcalc expression="a = rand(0., 5)" seed=1
r.mapcalc expression="b = rand(0., 5)" seed=2
r.mapcalc expression="c = rand(0., 5)" seed=3
r.series input=a,b,c output=d method=average
</pre></div>
```

In Python:

<div class="code"><pre>
```sh
import grass.jupyter as gj
plot = gj.Map(use_region=True, width=700, height=700)
plot.d_background(color="white")
plot.run("d.explanation.plot", a="a", b="b", c="c", d="d", operator_font="FreeMono:Regular")
plot.show()
</pre></div>
```

![image-alt](d_explanation_plot_with_r_series.png)

<center>
<img src="d_explanation_plot_with_r_series.png">
<p><em>Figure: Resulting image for r.series</em></p>
</center>
*Figure: Resulting image for r.series*

<h3>Example using artificial data</h3>
### Example using artificial data

<div class="code"><pre>
r.in.ascii input=- output=input_1 &lt;&lt;EOF
```sh
r.in.ascii input=- output=input_1 <<EOF
north: 103
south: 100
east: 103
Expand All @@ -56,7 +51,7 @@ cols: 3
* 5 *
* 5 5
EOF
r.in.ascii input=- output=input_2 &lt;&lt;EOF
r.in.ascii input=- output=input_2 <<EOF
north: 103
south: 100
east: 103
Expand All @@ -72,56 +67,41 @@ g.region raster=input_1
r.patch input=input_1,input_2 output=result
d.mon wx0 width=400 height=400 output=r_patch.png
d.explanation.plot a=input_1 b=input_2 c=result
</pre></div>

<center>
<img src="d_explanation_plot.png">
<p><em>Figure: Resulting image for r.patch</em></p>
</center>

<h2>KNOWN ISSUES</h2>

<ul>
<li>
Issue <a href="https://trac.osgeo.org/grass/ticket/3381">#3381</a>
prevents d.rast.num to be used with <tt>d.mon cairo</tt>,
so <tt>d.mon wx0</tt> needs to be used with this module.
Using environmental variables for rendering directly or
using tools such as <em>Map</em> from <em>grass.jupyter</em>
avoids the issues.
</li>
<li>
Issue <a href="https://trac.osgeo.org/grass/ticket/3382">#3382</a>
prevents usage of centered text with <tt>d.mon wx0</tt>, so the
hardcoded values for text does not work perfectly.
</li>
<li>
Issue <a href="https://trac.osgeo.org/grass/ticket/3383">#3383</a>
prevents d.rast.num to be saved to the image with
<tt>d.mon wx0</tt>, taking screenshot is necessary
(with a powerful screenshot tool, this also
addresses the copping issue below).
</li>
<li>
The size of the display must be square to have rasters and their
cells as squares, e.g., <tt>d.mon wx0 width=400 height=400</tt>
must be used. The image needs to be cropped afterwards,
e.g. using ImageMagic's <tt>mogrify -trim image.png</tt>.
</li>
</ul>


<h2>SEE ALSO</h2>

<em>
<a href="https://grass.osgeo.org/grass-stable/manuals/g.region.html">g.region</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/d.frame.html">d.frame</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/d.rast.num.html">d.rast.num</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/d.grid.html">d.grid</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/d.mon.html">d.mon</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/v.mkgrid.html">v.mkgrid</a>
</em>

<h2>AUTHOR</h2>

Vaclav Petras, <a href="https://geospatial.ncsu.edu/geoforall/">NCSU GeoForAll Lab</a>
```

![image-alt](d_explanation_plot.png)

*Figure: Resulting image for r.patch*

## KNOWN ISSUES

- Issue [\#3381](https://trac.osgeo.org/grass/ticket/3381) prevents
d.rast.num to be used with `d.mon cairo`, so `d.mon wx0` needs to be
used with this module. Using environmental variables for rendering
directly or using tools such as *Map* from *grass.jupyter* avoids
the issues.
- Issue [\#3382](https://trac.osgeo.org/grass/ticket/3382) prevents
usage of centered text with `d.mon wx0`, so the hardcoded values for
text does not work perfectly.
- Issue [\#3383](https://trac.osgeo.org/grass/ticket/3383) prevents
d.rast.num to be saved to the image with `d.mon wx0`, taking
screenshot is necessary (with a powerful screenshot tool, this also
addresses the copping issue below).
- The size of the display must be square to have rasters and their
cells as squares, e.g., `d.mon wx0 width=400 height=400` must be
used. The image needs to be cropped afterwards, e.g. using
ImageMagic's `mogrify -trim image.png`.

## SEE ALSO

*[g.region](https://grass.osgeo.org/grass-stable/manuals/g.region.html),
[d.frame](https://grass.osgeo.org/grass-stable/manuals/d.frame.html),
[d.rast.num](https://grass.osgeo.org/grass-stable/manuals/d.rast.num.html),
[d.grid](https://grass.osgeo.org/grass-stable/manuals/d.grid.html),
[d.mon](https://grass.osgeo.org/grass-stable/manuals/d.mon.html),
[v.mkgrid](https://grass.osgeo.org/grass-stable/manuals/v.mkgrid.html)*

## AUTHOR

Vaclav Petras, [NCSU GeoForAll
Lab](https://geospatial.ncsu.edu/geoforall/)
92 changes: 41 additions & 51 deletions src/display/d.frame/d.frame.md
View file
Original file line number Diff line number Diff line change
@@ -1,37 +1,33 @@
<h2>DESCRIPTION</h2>

<em>d.frame</em> manages display frames on the current user's graphics
monitor. Graphics are displayed in rectangular frames on whatever
graphics monitor the user is currently directing GRASS display output
to (defined by <em><a href="https://grass.osgeo.org/grass-stable/manuals/d.mon.html">d.mon</a></em> module). These
frames are created and managed with this module.

<p>
Note that GRASS frame contents <em>are not</em> retained when one
frame covers another. You cannot shuffle frames from top to bottom and
then back again. They simply define rectangular areas on the screen
where subsequent drawing will occur.

<h2>NOTES</h2>

The coordinates for the <b>at</b> option are stated in the form
<em>top,bottom,left,right</em> values are in percent. The upper-left
corner of the graphics monitor always is at location 0,0 while the
monitor's lower-right corner is always at 100,100.

<p>
If the user has created multiple display frames that overlap one another,
whatever the user displays in the active frame will overwrite
## DESCRIPTION

*d.frame* manages display frames on the current user's graphics monitor.
Graphics are displayed in rectangular frames on whatever graphics
monitor the user is currently directing GRASS display output to (defined
by *[d.mon](https://grass.osgeo.org/grass-stable/manuals/d.mon.html)*
module). These frames are created and managed with this module.

Note that GRASS frame contents *are not* retained when one frame covers
another. You cannot shuffle frames from top to bottom and then back
again. They simply define rectangular areas on the screen where
subsequent drawing will occur.

## NOTES

The coordinates for the **at** option are stated in the form
*top,bottom,left,right* values are in percent. The upper-left corner of
the graphics monitor always is at location 0,0 while the monitor's
lower-right corner is always at 100,100.

If the user has created multiple display frames that overlap one
another, whatever the user displays in the active frame will overwrite
those portions of the underlying frame where these frames overlap.

<p>
<b>Important note:</b> This version of <em>d.frame</em> works only
with GRASS 7.0. Further versions of GRASS come with their own
built-in <em>d.frame</em> module.
**Important note:** This version of *d.frame* works only with GRASS 7.0.
Further versions of GRASS come with their own built-in *d.frame* module.

<h2>EXAMPLE</h2>
## EXAMPLE

<div class="code"><pre>
```sh
# start a new graphics monitor, the data will be rendered to
# /tmp/map.png image output file of size 600x540px
d.mon cairo out=/tmp/map.png width=600 height=540 --o
Expand Down Expand Up @@ -65,33 +61,27 @@ d.text text='RGB true colors' bgcolor=220:220:220 color=black size=6

# release the current graphics monitor
d.mon -r
</pre></div>
```

<center>
<img src="d_frame.png" alt="d.frame example"><br>
<em>Figure: d.frame example</em>
</center>
![image-alt](d_frame.png)
*Figure: d.frame example*

<h2>SEE ALSO</h2>
## SEE ALSO

<em>
<a href="https://grass.osgeo.org/grass-stable/manuals/d.erase.html">d.erase</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/d.info.html">d.info</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/d.mon.html">d.mon</a>,
<a href="https://grass.osgeo.org/grass-stable/manuals/d.redraw.html">d.redraw</a>
</em>
*[d.erase](https://grass.osgeo.org/grass-stable/manuals/d.erase.html),
[d.info](https://grass.osgeo.org/grass-stable/manuals/d.info.html),
[d.mon](https://grass.osgeo.org/grass-stable/manuals/d.mon.html),
[d.redraw](https://grass.osgeo.org/grass-stable/manuals/d.redraw.html)*

<p>
<a href="https://grass.osgeo.org/grass-stable/manuals/variables.html#list-of-selected-grass-environment-variables-for-rendering">GRASS environment variables for
rendering</a> (GRASS_RENDER_FRAME)
[GRASS environment variables for
rendering](https://grass.osgeo.org/grass-stable/manuals/variables.html#list-of-selected-grass-environment-variables-for-rendering)
(GRASS\_RENDER\_FRAME)

<h2>AUTHORS</h2>
## AUTHORS

Martin Landa, Czech Technical University in Prague, Czech Republic

<p>
Based on <em>d.frame</em> from GRASS 6:<br>
Based on *d.frame* from GRASS 6:
James Westervelt, U.S. Army Construction Engineering Research
Laboratory<br>
Michael Shapiro, U.S. Army Construction Engineering
Research Laboratory
Laboratory
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
Loading

0 comments on commit 53de819

Please sign in to comment.