Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

manpage paragraph incorrect indentation #13803

Closed
jay opened this issue May 27, 2024 · 4 comments
Closed

manpage paragraph incorrect indentation #13803

jay opened this issue May 27, 2024 · 4 comments

Comments

@jay
Copy link
Member

jay commented May 27, 2024

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_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 ""

nroff2

website version after roffit conversion of nroff generated by cd2nroff:

website2

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:

.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
Copy link
Member

bagder commented May 28, 2024

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.

bagder added a commit that referenced this issue May 28, 2024
Like when we list a series of options and then want to add "normal" text
again afterwards.

Without this, the indentation level wrongly continues even after the
final "##" header, making following text wrongly appear to belong to the
header above.

Adjusted CURLOPT_SSLVERSION.md to use this to show the idea.

Fixes #13803
Reported-by: Jay Satiro
bagder added a commit that referenced this issue May 28, 2024
Like when we list a series of options and then want to add "normal" text
again afterwards.

Without this, the indentation level wrongly continues even after the
final "##" header, making following text wrongly appear to belong to the
header above.

Adjusted CURLOPT_SSLVERSION.md to use this to show the idea.

Fixes #13803
Reported-by: Jay Satiro
@jay
Copy link
Member Author

jay commented May 28, 2024

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
Copy link
Member

bagder commented May 28, 2024

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

@bagder bagder closed this as completed in 24b66a1 May 29, 2024
jay added a commit to jay/roffit that referenced this issue May 29, 2024
Prior to this change when .PP (regular paragraph) was used after
.IP (indented paragraph) roffit would not change the indent level which
resulted in regular paragraphs having the same indent as the previously
indented paragraph.

Ref: curl/curl#13803 (comment)

Closes #xxxxx
@jay
Copy link
Member Author

jay commented May 29, 2024

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

bagder pushed a commit to bagder/roffit that referenced this issue Jun 4, 2024
Prior to this change when .PP (regular paragraph) was used after
.IP (indented paragraph) roffit would not change the indent level which
resulted in regular paragraphs having the same indent as the previously
indented paragraph.

Ref: curl/curl#13803 (comment)

Closes #xxxxx
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Development

Successfully merging a pull request may close this issue.

2 participants