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

libcurl option manpages consistency cleanup #7656

Closed
wants to merge 4 commits into from

Conversation

@bagder
Copy link
Member

@bagder bagder commented Sep 1, 2021

All man pages for libcurl options now need to:

  1. feature an example
  2. feature eight mandatory sections (extra sections are fine)
  3. feature those mandatory sections in the correct order

Failure to comply makes test 1173 error.

docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 Outdated Show resolved Hide resolved
docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 Show resolved Hide resolved
docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 Outdated Show resolved Hide resolved
docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 Show resolved Hide resolved
docs/libcurl/opts/CURLOPT_XFERINFODATA.3 Outdated Show resolved Hide resolved
docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 Outdated Show resolved Hide resolved
@deepcode-ci-bot
Copy link

@deepcode-ci-bot deepcode-ci-bot bot commented Sep 1, 2021

Congratulations 🎉. DeepCode analyzed your code in 0.658 seconds and we found no issues. Enjoy a moment of no bugs ☀️.

👉 View analysis in DeepCode’s Dashboard | Configure the bot

👉 The DeepCode service and API will be deprecated in August, 2021. Here is the information how to migrate. Thank you for using DeepCode 🙏 ❤️ !

If you are using our plugins, you might be interested in their successors: Snyk's JetBrains plugin and Snyk's VS Code plugin.

@bagder bagder force-pushed the bagder/opt-manpage-examples branch from 62a7b14 to 7f8179d Sep 1, 2021
@danielgustafsson
Copy link
Member

@danielgustafsson danielgustafsson commented Sep 1, 2021

Copy link
Member

@danielgustafsson danielgustafsson left a comment

Whats in here looks good to me now, unless there are plans to expand it I think this is ready.

tests/manpage-syntax.pl Outdated Show resolved Hide resolved
@bagder
Copy link
Member Author

@bagder bagder commented Sep 1, 2021

This is enough for this PR, no expansion planned. I'll just need to make sure all builds work properly with this.

@bagder

This comment has been hidden.

@bagder
Copy link
Member Author

@bagder bagder commented Sep 2, 2021

Right, that’s exactly what I was thinking of, including the relevant CURL_AT_LEAST_VERSION(); snippet ready to be copy/pasted into code. That being said, it might be a tad repetitive and not really worth it since it’s so simple to use.

It is also the problem of build-time vs run-time. Using CURL_AT_LEAST_VERSION() will certainly make your program build with older libcurls but for cases where you build your program with a new libcurl and run it with an old, you need other checks so the CURL_AT_LEAST_VERSION() won't be enough so it would be very important to not mislead the user into believing so. I'm not sure how to best do that!

@danielgustafsson
Copy link
Member

@danielgustafsson danielgustafsson commented Sep 2, 2021

@bagder bagder force-pushed the bagder/opt-manpage-examples branch from b7a2cab to 6f6114b Sep 2, 2021
bagder added 4 commits Sep 3, 2021
Extended manpage-syntax.pl (run by test 1173) to check that every man
page for a libcurl option has an EXAMPLE section that is more than two
lines. Then fixed all errors it found and added examples.
In every libcurl option man page there are now 8 mandatory sections that
must use the right name in the correct order and test 1173 verifies
this. Only 14 man pages needed adjustments.

The sections and the order is as follows:

 - NAME
 - SYNOPSIS
 - DESCRIPTION
 - PROTOCOLS
 - EXAMPLE
 - AVAILABILITY
 - RETURN VALUE
 - SEE ALSO
... that they refer to actual existing libcurl options.
@bagder bagder force-pushed the bagder/opt-manpage-examples branch from 1f20544 to 2fa9027 Sep 3, 2021
@bagder bagder closed this in 1731a77 Sep 4, 2021
bagder added a commit that referenced this issue Sep 4, 2021
In every libcurl option man page there are now 8 mandatory sections that
must use the right name in the correct order and test 1173 verifies
this. Only 14 man pages needed adjustments.

The sections and the order is as follows:

 - NAME
 - SYNOPSIS
 - DESCRIPTION
 - PROTOCOLS
 - EXAMPLE
 - AVAILABILITY
 - RETURN VALUE
 - SEE ALSO

Reviewed-by: Daniel Gustafsson
Closes #7656
bagder added a commit that referenced this issue Sep 4, 2021
... that they refer to actual existing libcurl options.

Reviewed-by: Daniel Gustafsson
Closes #7656
@bagder bagder deleted the bagder/opt-manpage-examples branch Sep 4, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

2 participants