- cmake: enable `BUILD_DOCS` by default (this controls converting and
installing `.3` files from `.md` sources)
- cmake: speed up generating `.3` files by using a single command per
directory, instead of a single command per file. This reduces external
commands by about a thousand. (There remains some CMake logic kicking
in resulting in 500 -one per file- external `-E touch_nocreate` calls.)
- cd2nroff: add ability to process multiple input files.
- cd2nroff: add `-k` option to use the source filename to form the
output filename. (instead of the default in-file `Title:` line.)
Follow-up to 3f08d80b22
Follow-up to ea0b575dab#12753
Follow-up to eefcc1bda4#12730Closes#12762
curldown is this new file format for libcurl man pages. It is markdown
inspired with differences:
- Each file has a set of leading headers with meta-data
- Supports a small subset of markdown
- Uses .md file extensions for editors/IDE/GitHub to treat them nicely
- Generates man pages very similar to the previous ones
- Generates man pages that still convert nicely to HTML on the website
- Detects and highlights mentions of curl symbols automatically (when
their man page section is specified)
tools:
- cd2nroff: converts from curldown to nroff man page
- nroff2cd: convert an (old) nroff man page to curldown
- cdall: convert many nroff pages to curldown versions
- cd2cd: verifies and updates a curldown to latest curldown
This setup generates .3 versions of all the curldown versions at build time.
CI:
Since the documentation is now technically markdown in the eyes of many
things, the CI runs many more tests and checks on this documentation,
including proselint, link checkers and tests that make sure we capitalize the
first letter after a period...
Closes#12730
