curl new version docs advice and opinions requested

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

curl new version docs advice and opinions requested

Brian Inglis
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/

--
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

This email may be disturbing to some readers as it contains
too much technical detail. Reader discretion is advised.
[Data in binary units and prefixes, physical quantities in SI.]
Reply | Threaded
Open this post in threaded view
|

Re: curl new version docs advice and opinions requested

cygwin-apps mailing list
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
Reply | Threaded
Open this post in threaded view
|

Re: curl new version docs advice and opinions requested

Brian Inglis
On 2020-10-17 16:48, Ken Brown via Cygwin-apps wrote:
> On 10/17/2020 5:38 PM, Brian Inglis wrote:
>> 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.

> 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, thanks for that pointer: I'll check there; and in future.
Other distros e.g. Debian, aren't as quick on the updates, so no help there.

Fedora provides even less than previous Cygwin, and less than I want to, so I
will go ahead with my choices of small, general docs in the base package, and
include all docs and example code in the -doc package, this release.

Anyone downstream should feel free to pipe up with comments or suggestions.

--
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

This email may be disturbing to some readers as it contains
too much technical detail. Reader discretion is advised.
[Data in binary units and prefixes, physical quantities in SI.]