manpage paragraph incorrect indentation

[jay]

The manpages display correctly in curldown format but paragraphs may have incorrect indentation when converted to nroff format (via cd2nroff) and then further to html (via roffit). The incorrect indentation is visible in a few places in the libcurl option website documentation.

The problem seems to be ## header in curldown format starts indented paragraph format (.IP) for nroff but there's no way to stop the indentation for future paragraphs in the same section. CURLOPT_SSLVERSION for example:

curl/docs/libcurl/opts/CURLOPT_SSLVERSION.md

Lines 66 to 82 in fd567d4

	## CURL_SSLVERSION_TLSv1_2
	TLS v1.2 or later (Added in 7.34.0)
	## CURL_SSLVERSION_TLSv1_3
	TLS v1.3 or later (Added in 7.52.0)
	The maximum TLS version can be set by using *one* of the
	CURL_SSLVERSION_MAX_ macros below. It is also possible to OR *one* of the
	CURL_SSLVERSION_ macros with *one* of the CURL_SSLVERSION_MAX_ macros.
	The MAX macros are not supported for WolfSSL.
	## CURL_SSLVERSION_MAX_DEFAULT
	The flag defines the maximum supported TLS version by libcurl, or the default
	value from the SSL library is used. libcurl uses a sensible default maximum,

In this example ## CURL_SSLVERSION_TLSv1_3 will be converted by cd2nroff as .IP CURL_SSLVERSION_TLSv1_3 and then subsequent paragraphs are all indented so says nroff format. However that is not desired because the second paragraph that starts "The maximum TLS version..." is not supposed to be indented. In the pictures below I used a red arrow to indicate where the paragraph should be.

scripts/cd2nroff < docs/libcurl/opts/CURLOPT_SSLVERSION.md | nroff -Tascii -man | grep ""

website version after roffit conversion of nroff generated by cd2nroff:

Older versions of curl used the nroff manpage format and so they had .RS/.RE for relative start/end of indentation, and roffit knew to end the indentation. For example this from 8.5.0:

curl/docs/libcurl/opts/CURLOPT_SSLVERSION.3

Lines 57 to 70 in 7161cb1

	.IP CURL_SSLVERSION_TLSv1_2
	TLS v1.2 or later (Added in 7.34.0)
	.IP CURL_SSLVERSION_TLSv1_3
	TLS v1.3 or later (Added in 7.52.0)
	.RE
	The maximum TLS version can be set by using \fIone\fP of the
	CURL_SSLVERSION_MAX_ macros below. It is also possible to OR \fIone\fP of the
	CURL_SSLVERSION_ macros with \fIone\fP of the CURL_SSLVERSION_MAX_ macros.
	The MAX macros are not supported for WolfSSL.
	.RS
	.IP CURL_SSLVERSION_MAX_DEFAULT
	The flag defines the maximum supported TLS version by libcurl, or the default
	value from the SSL library is used. libcurl uses a sensible default maximum,

---

I tried for some time to fix this but nothing worked well enough that I want to build on it. The simplest fix I tried was resetting subsequent paragraph style via .PP rather than processing .RS .RE. Though that works for nroff to reset the indentation it does not work for roffit. Also- I'm not sure if this does what I intend in nroff anyway albeit it seems to work visually, at the cost of ending all indented paragraphs after a single paragraph.

--- a/scripts/cd2nroff
+++ b/scripts/cd2nroff
@@ -459,7 +459,7 @@ sub single {
         else {
             # don't output newlines if this is the first content after a
             # header
-            push @desc, "\n" if($blankline && !$header);
+            push @desc, ".PP\n" if($blankline && !$header);
             $blankline = 0;
             $header = 0;

[bagder]

For the cmdline docs (parsed by managen) we use a "blank" ## header to signal the end of the list of .IP, and I think that might work here was well without it feeling very invasive. It requires a minor edit of the source file, but gives us more control and the output seems to be fine. Let me do a PR to show you what I mean.

[jay]

That's a good idea but it runs into the same issue I had with .PP when generating the html via roffit. If I decrease the indent level on .pp that seems to work. Or maybe reset the indent level to 0?

diff --git a/roffit b/roffit
index 56c1fda..c01cfef 100755
--- a/roffit
+++ b/roffit
@@ -499,12 +499,13 @@ sub parsefile {
             elsif($keyword =~ /^pp$/i) {
                 # PP ends a TP section, but some TP sections don't use it
                 # Often used to separate paragraphs
                 $within_tp=0;
                 showp(@p);
                 @p="";
+                $indentlevel-- if ($indentlevel);
             }
             elsif($keyword =~ /^fi$/i) {
                 # .fi = fill-in, extra space will be ignored and text that is
                 # entered like this, the fill-in command will continue until
                 # you enter a .nf command and vice-versa

[bagder]

That seems to be a roffit issue as the man page looks fine with this fix.

[jay]

That seems to be a roffit issue as the man page looks fine with this fix.

Thanks. Yes I agree, see proposal at bagder/roffit#48