MkDocs: Fixes missing Parameter tabs in documentation

[saket0187]

Fixes #6305

Problem Description

The Parameters section in MkDocs-generated documentation only displays the "Command line" tab for some modules like v.out.ogr, v.in.ogr, etc., while the "Python (grass.script)" and "Python (grass.tools)" tabs are missing. This affects module documentation pages built with Material for MkDocs.

Root Cause

In lib/gis/parser_md_common.c, the G__md_print_escaped() function was not handling newlines properly for Markdown output. Material for MkDocs requires continuation lines within tab blocks to be indented with 4 spaces. Without proper Markdown line breaks and indentation, MkDocs exits the tab block prematurely, causing the remaining tabs to not render.

Solution

Following maintainer feedback, refactored newline handling in parser_md_common.c:

• Created dedicated G__md_print_escaped_newline() function for newline special case handling
• Uses MD_NEWLINE (two trailing spaces) followed by newline and 4-space indentation
• Keeps newline logic separate from other character escapes (<, >, *, \t)

This ensures proper Markdown hard line breaks with continuation indentation for MkDocs tab rendering.

Testing

• Tested with v.out.ogr and v.in.ogr modules
• Verified all 3 tabs now render correctly in the Parameters section
• Compiled and tested on WSL Ubuntu 24.04
• Generated HTML shows data-tabs="2:3" with all tabs visible

Before Fix

Only Command line tab visible

After Fix

All three tabs (Command line, Python grass.script, Python grass.tools) display correctly

---

Note: This supersedes the previous PR which became messy due to other commits. This is a clean implementation addressing maintainer feedback about keeping newline handling as a separate function.

[saket0187]

@petrasovaa I've implemented your both suggestions:

1. Created G__md_print_escaped_newline() function to handle newlines as a special case
2. Uses MD_NEWLINE "\n " which expands to two trailing spaces + newline + 4-space indent

Regarding the tab change: I've reverted \t back to      since you mentioned it's unrelated.

The newline fix now properly renders all three tabs in the Parameters section. Please let me know if any adjustments are needed!

[petrasovaa]

There is an indent variable in the code calling the escape functions, so it would be good to pass it instead the hardcoded 4 spaces. I take back my suggestions to use a separate function, I don't think it makes sense like that, sorry about that.

[saket0187]

There is an indent variable in the code calling the escape functions, so it would be good to pass it instead the hardcoded 4 spaces. I take back my suggestions to use a separate function, I don't think it makes sense like that, sorry about that.

Adding the indent variable as a parameter will require modifying G__md_print_escaped() at all places where it is called across parser_md_cli.c and parser_md_python.c. Should I proceed with this update?

Also, the implementation cannot be done with the do_escape macro because indent is a runtime variable, not a compile-time string literal. I plan to use:

case '\n':
    fputs(MD_NEWLINE "\n", f);
    fputs(indent, f);
    break;

is this ok?

[petrasovaa]

There is an indent variable in the code calling the escape functions, so it would be good to pass it instead the hardcoded 4 spaces. I take back my suggestions to use a separate function, I don't think it makes sense like that, sorry about that.

Adding the indent variable as a parameter will require modifying G__md_print_escaped() at all places where it is called across parser_md_cli.c and parser_md_python.c. Should I proceed with this update?

Yes, that's ok.

Also, the implementation cannot be done with the do_escape macro because indent is a runtime variable, not a compile-time string literal. I plan to use:

case '\n':
    fputs(MD_NEWLINE "\n", f);
    fputs(indent, f);
    break;

is this ok?

Yes, the code will be more readable without the macro anyway.

[saket0187]

@petrasovaa I have already made the commit. Kindly review and approve it.

[petrasovaa]

@petrasovaa I have already made the commit. Kindly review and approve it.

For better readability, get rid of the macro completely for that function, thanks!

[petrasovaa]

Looks great! Thank you!