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

[wenzeslaus]

trafficstars

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?

[Prakharkarsh1]

Yeah that’s fine @wenzeslaus but in order to see if the changes that are made in script are getting reflected or not, I have to run make command again and again, isn’t it?

[wenzeslaus]

No need for any make here as far as I can tell. python utils/g.html2man/g.html2man.py is just like running any other script. The script file is utils/g.html2man. As an input it uses things created by make, here dist.x86_64-pc-linux-gnu/docs/html/d.graph.html, but that can stay the same for your experiments. (If make is needed for some reason anyway, you can run make in a specific directory where you are making changes which is faster than make on the whole system.)

[Prakharkarsh1]

Ok thanks a lot @wenzeslaus

[Prakharkarsh1]

I have raised a Pull request. Please check it and do let me know if any changes are required.

[Prakharkarsh1]

Hello @wenzeslaus can you please tell me if any changes are required??