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

curl/docs/libcurl/*: fix some formatting of man pages #8365

Closed
wants to merge 1 commit into from

Conversation

samueloph
Copy link
Contributor

@samueloph samueloph commented Jan 31, 2022

Details:

From "mandoc -Tlint":

mandoc: curl_getdate.3:64:2: WARNING: skipping paragraph macro: PP empty
mandoc: curl_global_init_mem.3:56:2: ERROR: skipping end of block that is not open: RE
mandoc: curl_url_cleanup.3:29:2: STYLE: fill mode already enabled, skipping: fi
mandoc: curl_url_dup.3:29:2: STYLE: fill mode already enabled, skipping: fi
mandoc: curl_url_set.3:32:2: STYLE: fill mode already enabled, skipping: fi

From "test-groff -b -mandoc -T utf8 -rF0 -t -w w -z":

[ "test-groff" is a developmental version of "groff" ]

troff: <curl_getdate.3>:108: warning: trailing space
troff: <curl_getdate.3>:109: warning: trailing space

Patch originally submitted to Debian at:
https://bugs.debian.org/963559

Details:

 From "mandoc -Tlint":

mandoc: curl_getdate.3:64:2: WARNING: skipping paragraph macro: PP empty
mandoc: curl_global_init_mem.3:56:2: ERROR: skipping end of block that is not open: RE
mandoc: curl_url_cleanup.3:29:2: STYLE: fill mode already enabled, skipping: fi
mandoc: curl_url_dup.3:29:2: STYLE: fill mode already enabled, skipping: fi
mandoc: curl_url_set.3:32:2: STYLE: fill mode already enabled, skipping: fi

  From "test-groff -b -mandoc -T utf8 -rF0 -t -w w -z":

  [ "test-groff" is a developmental version of "groff" ]

troff: <curl_getdate.3>:108: warning: trailing space
troff: <curl_getdate.3>:109: warning: trailing space

Patch originally submitted to Debian at:
https://bugs.debian.org/963559
Copy link
Member

@bagder bagder left a comment

Thanks, but this left me really curious...

.BR curl_easy_escape "(3), " curl_easy_unescape "(3), "
.BR CURLOPT_TIMECONDITION "(3), " CURLOPT_TIMEVALUE "(3) "
.BR curl_easy_escape "(3), " curl_easy_unescape "(3),"
.BR CURLOPT_TIMECONDITION "(3), " CURLOPT_TIMEVALUE "(3)"
Copy link
Member

@bagder bagder Jan 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one puzzles me.

  1. mandoc -Tlint curl_getdate.3 on my debian unstable does not warn on this for me
  2. I count a total of 79 similar lines, only counting .3 files in the same directory. Shouldn't then all of them be fixed at the same time?

Copy link
Contributor Author

@samueloph samueloph Jan 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one is not from mandoc, but from test-groff, which is not something I have installed but it makes sense I guess, the finding (from the submitter of the patch) was:

From "test-groff -b -mandoc -T utf8 -rF0 -t -w w -z":

[ "test-groff" is a developmental version of "groff" ]

troff: <curl_getdate.3>:108: warning: trailing space
troff: <curl_getdate.3>:109: warning: trailing space

There's a good chance it can be ignored if you think it's fine (it might be too cosmetic to spend the time to fix across all the files).

Copy link
Member

@bagder bagder Jan 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It feels very arbitrary to only fix it in a single file. If we consider this a problem then we should fix it everywhere. If it isn't a problem, then we don't need to fix any file. Why is it a problem? I don't spot any difference at all in the generated result I get with man -l curl_getdate.3.

Copy link
Contributor Author

@samueloph samueloph Jan 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's drop it then.

I believe this means there's only a single legitimate change to the whole PR, which is for:
mandoc: curl_getdate.3:64:2: WARNING: skipping paragraph macro: PP empty

@@ -27,7 +27,7 @@ curl_url_cleanup - free a CURLU handle
#include <curl/curl.h>

void curl_url_cleanup(CURLU *handle);
.fi
.
Copy link
Member

@bagder bagder Jan 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. My mandoc doesn't complain on this
  2. This pattern is used in all libcurl function man pages, why are these three singled out?
  3. Why leave a dot?

Copy link
Contributor Author

@samueloph samueloph Jan 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I also don´t get these anymore, apparently mandoc stopped complaining about it sometime ago.

This hunk can be dropped.

I don't know why the original submitter decided to go with a dot, I wasn't the original reviewer of the patch either so I just kept refreshing it. I figured sending it upstream was a good opportunity to drop changes like this.

@bagder
Copy link
Member

@bagder bagder commented Feb 1, 2022

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants