.nf/.fi are not handled well

[vapier]

the .nf and .fi macros are used to force newlines to be retained. it's quite handy for creating a flat list, or for code snippets.
https://www.gnu.org/software/groff/manual/html_node/Manipulating-Filling-and-Adjusting.html

the perl script oddly indents the code instead. i guess it's going for automatic code mode or something ?

example input:

.nf
One item.
Another item.
.fi

a reasonable md rendering would be to just add <br> to the end of each line i think:

One item.<br>
Another item.<br>

[vapier]

hmm, i see there's a -f option here. i wonder why that exists ? .nf and .fi do not disable formatting in their content.

[mle86]

.nf....fi is often used for code examples.

That's why my script indents that text by 4 spaces, turning them into Code Blocks.

In man pages, inline formatting (such as \fB) may be included within .nf....fi-formatted text.
Normally the script will remove this kind of extra formatting because Markdown doesn't support any formatting in code blocks.
With the -f command line option, these formatting sequences are turned into HTML (<b> etc) instead, which also means that the 4-space-indentation won't do anymore: code blocks will be printed as <pre><code>... to make it work.

Neither mode is suited for plain text .nf usage.
I'll add an inline command to disable code-styled output.

[mle86]

I'm thinking this syntax:

.\" PLAIN
.nf
...
.fi

This way the formatting still looks the same in man pages (as it should, because it has no such thing as <pre>) but the Markdown output can be different (i.e. <pre> instead of <pre><code>).

[mle86]

GitHub still renders <pre> as a code block, even if there's no <code>.

Current alternative:
Just modify the line ends (add two spaces) so that visible linebreaks are enforced.
Markdown renderers will still remove and line-start whitespace and will still collapse multiple whitespace charactrs though.

[vapier]

imo the output should match the input as much as possible by default, so if the man page author used formatting (like bold/italic), that'd be copied across by default. but if you have a different opinion wrt default, that's fine ;).

i guess i was more confused by a bug in the parser and thought the script was intending to do something else. it's not handling quoted args correctly. here's an example input:

.TH NOSIG 1
.SH NAME
.nf
.BR nosig " [\fIoptions\fR...] [\fI--\fR] \fIprogram\fR [\fIarguments\fR...]"
.BR nosig " [\fI--add|--del\fR] \fIsigspec\fR [\fI--block|--unblock|--set\fR] [...] \fIprogram\fR [...]"
.fi

this incorrectly retains the quotes:

# nosig(1)

    nosig " [options...] [--] program [arguments...]"
    nosig " [--add|--del] sigspec [--block|--unblock|--set] [...] program [...]"

[mle86]

Having -f not be the default case was a conscious decision:

• Without -f, the script tries to output pure Markdown. This may lose some formatting infos but is the safer choice for purists or finicky viewers (although I think that all current Markdown viewers support basic HTML).
• With -f, the script tries to conserve the input's formatting as much as possible, using inline HTML to do so.

As to your other point:

for some reason, I originally assumed that there can be no Roff commands inside a .nf....fi block
so my script always removes them (which leads to unexpected output in case of commands with quoted arguments such as .BR).
That's not true of course and I'll write a patch shortly to support that.

[mle86]

Apart from \fB etc, code blocks now support .B/.I/... as well as .BR/.IR/...
when the -f option is given.

Without that option, all formatting is still stripped from .nf blocks
but now the argument quotes are removed correctly.

[mle86]

Thank you for your feedback!

[vapier]

the -f option renders well now for me, thanks