curl new version docs advice and opinions requested

[Ken Brown]

On 10/17/2020 5:38 PM, Brian Inglis wrote:
> Hi folks,
> 
> The latest curl version has converted some more docs to md and dropped some, so
> I'm reconsidering what is packaged with the utility, what is delegated to the
> -docs package, and whether that should just be included in the -devel package.
> 
> The following extract from the cygport shows what was included, what I think I
> should include as it is generally useful, and everything now in the docs
> directory, such that everything else appears to be likely to be of interest only
> to developers or maintainers, all shown with sizes below.
> 
> #DOCS="docs/BINDINGS.md docs/BUGS.md docs/CONTRIBUTE.md
> #   -docs/DISTRO-DILEMMA docs/FAQ docs/FEATURES docs/HISTORY.md
> #   docs/HTTP-COOKIES.md docs/INTERNALS.md docs/KNOWN_BUGS.md
> #   -docs/LICENSE-MIXING docs/MAIL-ETIQUETTE -docs/MANUAL -docs/RESOURCES
> #   -docs/SECURITY docs/SSLCERTS.md docs/THANKS docs/TheArtOfHttpScripting.md
> #   docs/TODO docs/VERSIONS.md"
> 
> DOCS="docs/CIPHERS.md docs/FAQ docs/FEATURES docs/HTTP_COOKIES.md
>      docs/MAIL-ETIQUETTE docs/PARALLEL-TRANSFERS.md docs/README.md
>      docs/SSLCERTS.md docs/SSL-PROBLEMS.md docs/TheArtOfHttpScripting.md"
> 
> However, I am unsure whether I should still include the long and detailed
> HISTORY.md and THANKS which gives credits, and anything else others may consider
> generally useful.
> 
> Also whether to include docs/examples/ C programs in -devel or -docs packages,
> and whether I should even bother with a separate -docs packages, as all that
> other information appears to be for developers, and appears not to be generally
> useful IMHO.
> 
>    Lines   Words   Bytes Path
>        9      33     315 docs/INSTALL
>       12      65     353 docs/DEPRECATE.md
>       12      61     510 docs/README.md
>       19      67     602 docs/ROADMAP.md
>       29     109     685 docs/MQTT.md
>       23     141     917 docs/EXPERIMENTAL.md
>       24     143    1090 docs/CMakeLists.txt
>       39     181    1093 docs/ALTSVC.md
>       32     210    1607 docs/CODE_OF_CONDUCT.md
>      124     235    2013 docs/CURL-DISABLE.md
>       58     342    2086 docs/PARALLEL-TRANSFERS.md
>       56     378    2339 docs/VERSIONS.md
>       86     399    2501 docs/DYNBUF.md
>      110     528    3278 docs/RELEASE-PROCEDURE.md
>       87     539    3520 docs/SSL-PROBLEMS.md
>      142     383    3756 docs/HTTP3.md
>       89     582    3776 docs/INSTALL.cmake
>       87     676    4005 docs/HELP-US.md
>      106     682    4347 docs/BUG-BOUNTY.md
>      103     694    4403 docs/curl-config.1
>      135     598    4744 docs/ECH.md
>      123     466    4898 docs/Makefile.am
>      119     732    4942 docs/mk-ca-bundle.1
>      127     745    4945 docs/HTTP2.md
>      134     812    5214 docs/HTTP-COOKIES.md
>      132     849    5481 docs/SECURITY-PROCESS.md
>      127     402    5544 docs/BINDINGS.md
>      168     986    5903 docs/CODE_REVIEW.md
>      166     994    6116 docs/CHECKSRC.md
>      207     954    6153 docs/FEATURES
>      167    1097    6479 docs/GOVERNANCE.md
>      265    1195    7852 docs/CODE_STYLE.md
>      173    1272    8346 docs/SSLCERTS.md
>      246     589   10596 docs/options-in-versions
>      516     722   10802 docs/CIPHERS.md
>      384    1653   10997 docs/HISTORY.md
>      266    2050   11950 docs/BUGS.md
>      285    2027   11983 docs/MAIL-ETIQUETTE
>      307    2158   13701 docs/CONTRIBUTE.md
>      509    2904   20405 docs/INSTALL.md
>      692    4521   28382 docs/TheArtOfHttpScripting.md
>      921    3360   30208 docs/Makefile.in
>      827    4564   31749 docs/KNOWN_BUGS
>     2276    4900   33901 docs/THANKS
>     1102    6442   43923 docs/INTERNALS.md
>     1370    7345   49854 docs/TODO
>     1550   10679   66585 docs/FAQ
>     3369   23622  146097 docs/curl.1
>     5936   30590  200839 total docs/cmdline-opts/
>    14829   75861  577241 total docs/libcurl/
>    20219   72936  636989 total docs/examples/
>    17910   95086  640946 total docs/
>    27893  146109 1083108 total docs/libcurl/opts/

I often use Fedora as a guide when questions like this come up:

   https://src.fedoraproject.org/rpms/curl/blob/master/f/curl.spec

Ken