[Bug] g.html2man reports "can't handle line breaks" during the build

[wenzeslaus]

Describe the bug

Building GRASS GIS gives several can't handle line breaks in <dt>...</dt> warning messages. These come from running utils/g.html2man/g.html2man.py which, I assume, can't convert some of the HTML code to the man page format.

This means that the documentation (manual pages for modules and maybe some others) use HTML syntax which is not supported by the other documentation tool namely g.html2man.

To Reproduce

Options:

1. Run the build.
2. See some build, e.g., on binder where you can play with the result, too.
3. With some tweaking you can run the command outside of the build (see the code below and in the screenshot section).

python utils/g.html2man/g.html2man.py dist.x86_64-pc-linux-gnu/docs/html/d.graph.html test.txt

The path dist.x86_64-pc-linux-gnu/docs/html is from the result of the build because g.html2man expects the HTML file to be the HTML file already processed during the build (dist.x86_64-pc-linux-gnu/docs/html/d.graph.html), not the one in the source code (display/d.graph/d.graph.html).

Expected behavior

No error messages. This can be achieved either by:

1. removing the problematic HTML code (line breaks) in the HTML files (requires only HTML editing but it may not be the best for the documentation), or by
2. replacing the line breaks by simple spaces in g.html2man (requires Python coding), or by
3. finding a different syntax in man pages (probably too complicated)

Screenshots

Part of the build output:

VERSION_NUMBER=8.1.dev VERSION_DATE=2022 MODULE_TOPDIR=../.. \
		python3 /home/jovyan/dist.x86_64-pc-linux-gnu/utils/mkhtml.py d.graph > /home/jovyan/dist.x86_64-pc-linux-gnu/docs/html/d.graph.html
VERSION_NUMBER=8.1.dev /home/jovyan/dist.x86_64-pc-linux-gnu/utils/g.html2man.py "/home/jovyan/dist.x86_64-pc-linux-gnu/docs/html/d.graph.html" "/home/jovyan/dist.x86_64-pc-linux-gnu/docs/man/man1/d.graph.1"
can't handle line breaks in <dt>...</dt>
can't handle line breaks in <dt>...</dt>
can't handle line breaks in <dt>...</dt>
can't handle line breaks in <dt>...</dt>
can't handle line breaks in <dt>...</dt>
can't handle line breaks in <dt>...</dt>

vyan/dist.x86_64-pc-linux-gnu/docs/man/man1/wxGUI.image2target.1"
can't handle line breaks in <dt>...</dt>

VERSION_NUMBER=8.1.dev /home/jovyan/dist.x86_64-pc-linux-gnu/utils/g.html2man.py "/home/jovyan/dist.x86_64-pc-linux-gnu/docs/html/g.gui.image2target.html" "/home/jovyan/dist.x86_64-pc-linux-gnu/docs/man/man1/g.gui.image2target.1"
can't handle line breaks in <dt>...</dt>

VERSION_NUMBER=8.1.dev /home/jovyan/dist.x86_64-pc-linux-gnu/utils/g.html2man.py "/home/jovyan/dist.x86_64-pc-linux-gnu/docs/html/g.gui.image2target.html" "/home/jovyan/dist.x86_64-pc-linux-gnu/docs/man/man1/g.gui.image2target.1"
can't handle line breaks in <dt>...</dt>

System description

• Operating System: Ubuntu 20.04
• GRASS GIS version: main, releasebranch_8_0

Additional context

Documentation is kept in HTML files, but converted to man pages during the build. man pages are available on system where man program is while the HTML is used in most cases including the online documentation.

[sohamchari]

Hi, I would like to fix this issue as my first contribution.

[wenzeslaus]

Sounds good @sohamchari. Just pick one of the three expected behaviors and base your fix on that. I think number 2 has the highest chance of success.

[sohamchari]

Yes thanks, I shall work on it.

[Prakharkarsh1]

heyy!! I would also like to contribute to fix this issue!!

[wenzeslaus]

@Prakharkarsh1 See above. There is couple options what to do. Fixing utils/g.html2man/g.html2man.py code is probably the best option. @sohamchari may work on it too (again, see above), but we can deal with two similar PRs if that happens.

Alternatively, I can recommend #575 which is great for easy code fix and getting to know the procedure.

[Prakharkarsh1]

Thanks for information, I’ll work on it!

[Prakharkarsh1]

@wenzeslaus Is there any easy way to debug the python script? Right now I'm uninstalling all the executables using make command ("make clean" command)and installing it again after making some changes in python script which takes time("make" command). Thanks!

[wenzeslaus]

See the issue description, you can run the the g.html2man.py script like this:

python utils/g.html2man/g.html2man.py dist.x86_64-pc-linux-gnu/docs/html/d.graph.html test.txt

Is that what you are looking for?