Remove sha1.

Server and client prefer sha256 in the authentication protocol since
paraslash-0.7.0, while 0.6.x clients and servers only know about sha1. This
patch drops the compatibility code which enabled old clients to connect to
new servers and vice versa.

Now the client code no longer checks whether the sha256 feature is supported,
but requests and uses the feature unconditionally. The server still announces
the sha256 feature and accepts the corresponding feature request, but uses
sha256 unconditionally.

With this approach older 0.7.x clients are still compatible to current
server versions and current clients can still talk to servers running older
0.7.x versions.

Remove para_upgrade_db.

It is no longer needed since everybody should have upgraded by now, and it
blocks the road towards the removal of sha1.

aft: Compare the full hash, not just the first 20 bytes.

In 0.7.0 the hash algorithm for the hash column of the audio file table
changed from the 20 byte sha1 to the 32 byte sha256. However, the audio file
selector kept calling hash_compare() as the comparator, which looks only at
the first 20 bytes of the buffers passed.

This omission is clearly a bug, but given that we still accept old clients
which only know about sha1, it's benign because the truncated sha256 should
not be worse than sha1. Fix the bug anyway.

Fixes: 126b950f1bd70d1e5c200bc4157bbbb2798fc838

Improve documentation of set_max_chunk_size().

The old text implied that the function could be removed at some point, which
is not the case. Remove this part of the documentation and clarify what the
function actually does.

Warn about old (0.5.x or earlier) on-disk afhi.

Nine years ago, starting with commit 234647bb5, old on-disk entries are
reported with a notice to re-add the file in order to update the audio file
table. Bump the loglevel for now, and add a comment to turn the check into
a hard error eventually.

doxyen: Completely suppress brief descriptions.

This shortens the doxygen pages, removing lots of pointless duplications.

buffer_tree: Assert that we don't pass NULL to memcpy().

The buffer pointer cannot be NULL here because this only happens when the
buffer tree area is full, which is not the case thanks to the previous n <=
btr_pool_unused(btrp) check.

mp.c: Remove a dead store.

Found by the clang analyzer.

mood.c: Remove a dead store and fix the documentation of mood_load().

The function returns 1 on success, not the number of admissible files.

Found by the clang analyzer.

flac_afh: Check for possible integer overflows.

This is a callback function which should carefully check its inputs.

gcc-compat.h: Drop inline #define.

There is no reason to believe that the programmer does a better job than
the compiler here.

play.c: Kill pointless typedef.

The signature of the function pointer is too simple to warrant a typedef.

afs.h: Omit superfluous semicolons.

The DECLARE_BLOB_SYMBOLS macro expands to a bunch of declarations, each of
which is terminated by a semicolon. So don't add another one.

Makefile: Drop redundant -Wuninitialized.

It is implied by -Wextra, which is the same as -W, but more descriptive.

Merge topic branch t/build into master

A medium sized series for the build system which improves the way the git
version string is stored in the executables and man pages. Subsequent patches
of the series remove some warts from the makefile: we no longer use order-only
dependencies and the .PRECIOUS target.

The merge results in a conflict against the "remove regex include" commit
67388cd4fae0. This is trivial to resolve, though.

* refs/heads/t/build:
  Doxify version functions.
  Doxify OV_EXCLUDE_STATIC_CALLBACKS #define.
  Makefile: Fix braino in tarball target.
  build: Remove superfluous dependency in Makefile.real.
  build: Remove the .PRECIOUS target.
  build: Improve clean targets.
  build: Get rid of directory order-only dependencies.
  build: Compile with -Wunused -Wall also on BSD.
  build: Revamp git versioning.
  build: Merge version.{c,h} into string.{c,h}.

Include regex.h from para.h.

Every .c file includes it anyway.

doxygen: Don't show includes.

They use a lot of space and don't help much to understand the API or code.

load_afd(): Double check shared memory sizes.

The shared memory ID is sent by a trusted source, so it is a programming error
(rather than a runtime error that could be handled) if the size of the shared
memory area is smaller than the size of an audio file data structure. Thus,
the right thing to do is to abort immediately in this case.

about: Mention that paraslash works without internet access.

It's a noteworthy feature if software works without relying on third-party
internet services.

mp3_afh: Kill FOR_EACH_FIELD().

The macro has only one user. Open-code it to shorten the code and improve
readability.

mp3_afh: Document id3_field_init() and id3_field_finish().

These functions are somewhat obscure because they are not part of the
libid3tag API. They are not part of the internal paraslash API either,
so their documentation should not be shown on the API page. Exclude the
documentation with the doxygen \cond and \endcond markers.

aft.c: Remove unused enum touch_flags.

This enum became unused ten years ago when the touch command learned to use
the lopsub library.

Fixes: fdf416e9af730a1df9eec8d7acb108d7ca881926

server: Add missing non-opts name to help text.

blob: Get rid of the two dummy event handlers.

The four blob operation structures defined in blob.c are created by
a macro which initializes the function pointer for the event handler
to ${name}_event_handler, where $name is the blob type, i.e. one of
images, lyrics, moods, playlists.

Only two of the four, moods and playlists, need an event handler
because the images and lyrics tables ignore events. Currently we
have to define dummy functions {images,lyrics}_event_handler() to
avoid link errors. This extra code can easily be avoided by making
the macros a little smarter.

Check return value of lsu_com_help().

This function fails if an invalid command name is passed as the argument, yet
all callers ignore the error. Modify the callers to print the strerror text as
appropriate and no longer do that in lsu_lopsub_error(). Rename this function
and introduce the error type argument to print more meaningful error messages.

One visible consequence is that

para_client help does-not-exist

used to succeed while it now exits with status 1.

afs.c: Improve documentation.

Add an overview of the file and expand the description of
open_next_audio_file() and afs_init().

client: Fix completion for the select subcommand.

We missed to complete the -v option that was added recently.

Fixes: 1f31fcdd74ab1aab01cbc70942f9d69bb779156a

i9e: Rename i9e_completer() -> attempt_completion().

The old name is confusing since we also have struct i9e_completer,
which is a completely different beast. Rewrite the documentation
of the function while at it.

i9e: Improve documentation of i9e_completion_info().

Emphasize that ->word is *not* the same as ->argv[i], where i is the index of
the current word.

Add missing newline in mp_init() error string.

Because callers expect this. Also print the message to the server log.

com_check(): Report inconsistencies consistently.

Currently the various checkers report the inconsistencies they detect
in one of the osl tables to either stdout via the pbout para_buffer
or to stderr by calling afs_error(), Unify this by replacing all
calls to afs_error().

aft: Simplify print_list_item().

The function performs no cleanup, so we don't need to jump to "out"
just to return ret.

vss_init(): Adjust loglevel.

These messages are not that interesting, so decrease their log level
by one.

manual: s/pipe/socket in the section on AFS.

The AFS process passes an open file descriptor to the server process,
which is only possible with sockets but not with pipes.

base64: Document PAD64.

This fixes another warning when doxygen is run with EXTRACT_ALL=NO.

Doxify version functions.

The two auto-generated public functions come undoxified, so document
their declarations in string.h.

Fixes: 69bace22205b4bb01673f7c9873f57a43bd6a0f7

Doxify OV_EXCLUDE_STATIC_CALLBACKS #define.

That's useful information that should make it into the generated web
pages.

Makefile: Fix braino in tarball target.

$(RM) implies -f, but not -r.

Fixes: 35a7569b2a7c66e40246aeaa135224f469584209

build: Remove superfluous dependency in Makefile.real.

This dependency is also covered by the CC_PREREQUISITES variable.

build: Remove the .PRECIOUS target.

Instruct make(1) to never remove any intermediate files by defining
.SECONDARY. This way we don't need to maintain the list of precious
targets.

build: Improve clean targets.

In a "fresh build" (e.g. after a make clean) we create the .d and the
.o file in one go to speed up this common case. However, if one runs
"make clean" followed by e.g. "make para_audioc", this will create
*all* object and dependency files, not just the ones needed to build
para_audioc. This behaviour is unfortunate because most dependencies
are irrelevant for a single target, and even the few which do matter
are ignored as well in this case because the object file does not
exist and needs to be recreated anyway,

Work around this shortcoming by shuffling the commands of the four
rules a little so that the clean target only removes object files
but keeps the dependency files.

Also remove the calls to SAY in the recipe of the clean targets because
with the rm commands spelled out it is clear what is being removed.

build: Get rid of directory order-only dependencies.

They only clutter the Makefile for no good reason. Just create all
build directories beforehand when running ./version-gen.sh.

One order-only dependency remains: We want to invoke the compiler
only after all generated .h files have been created. Otherwise the
.d files may be created incorrectly.

build: Compile with -Wunused -Wall also on BSD.

The new #define in oggdec_filter.c gets rid of the warnings such as

'OV_CALLBACKS_STREAMONLY_NOCLOSE' defined but not used [-Wunused-variable]

on NetBSD. With the patch applied, the code still compiles without
warnings. Tested on Linux, FreeBSD and NetBSD.

build: Revamp git versioning.

This rewrites GIT-VERSION-GEN and renames it to version-gen.sh. The
main difference is that the script now generates version.c rather
than version.h, speeding up the build because switching branches
or transitioning from a clean to a dirty work-tree (or vice versa)
changes the version string. Before the patch, all files which included
version.h were recompiled. With the patch applied, only the short
version.c needs to be recompiled.

The generated version,c defines one function which returns the
single-line version string and a second function which returns
the multi-line version information (author, copyright, git URL
etc). This information is now passed to version-gen.sh via environment
variables. The CPP macros we had before are removed.

build: Merge version.{c,h} into string.{c,h}.

This is a preparatory patch for the upcoming revamp of the git
version script. The revamped script generates version.c, a file
which is currently tracked by git. We can easily get rid of it (and
of version.h) since all paraslash executables link in both string.o
and version.o. So let's move the three small functions of version.c
to string.c and their declarations from version.h to string.h.

Teach the mood parser to not leak on errors.

Attempting to load an incomplete mood definition such as "1 &&"
currently causes memory leaks because the memory for the partial
syntax tree is never freed.

Employ bison's %destructor directive to call mp_free_ast() whenever
a syntax error happens.

mp.y: Fix some trivialities.

Some lines were indented with spaces rather than tabs, and the file
contained a few stray semicolons with no effect.

string.c: Remove an unused local variable in for_each_line().

This set but not used variable existed for a long time, but only now
the first compiler, clang-19 on FreeBSD, started to complain.

Streamline the documentation a bit while at it.

Fix memory leak in mood parser.

If a mood definition contains an invalid regular expression, we leak
one ast node structure per yyparse() call.

gui: Switch to white foreground for command output.

The new color scheme is easier to read, and is more pleasant on the eye.

gui: Improve "closing command fd" log message.

Make the EOF case silent because this is no real error, but print the
log message with a high severity level if the read operation failed
for any other reason.

Kill BINDIR.

When executing para_client or para_audioc from para_mixer or para_gui
we currently pass an absolute path whose directory part is BINDIR
to execvp(2). This is unnecessary because execvp(2) honors $PATH.
This commit modifies gui.c and mixer.c to pass only the basename of
the executable instead, allowing us to remove the BINDIR preprocessor
define. We still need the bindir make variable, though, because it
is referenced in the recipe of the two install targets.

paraslash 0.7.4

configure: Suggest to install liblopsub-dev.

exec: Improve documentation.

Clarify the documentation of the public para_exec_cmdline_pid()
and dedox the static para_exec().

Update copyright year.

Happy new year!

gui: Kill also child processes of external commands.

When a command is executed as a display command from para_gui, and
the command is interrupted from within para_gui by pressing any key,
para_gui only kills the spawned process but leaves alone its child
processes.

Address this problem by putting the spawned process into a separate
process group so that we can easily kill all processes of the group
by passing the negated PID of the child to kill(2).

In theory, the change in exec.c also affects para_mixer, which executes
para_client and para_audioc. However, para_mixer never kills any of
its child processes.

Fix memory leak in playlist.c.

If the result pointer is NULL. we currently leak one playlist instance
structure (12 bytes on 32 bit, 20 bytes on 64 bit) each time a playlist
is loaded.

Found by valgrind.

Fixes: 2d2637cb4c9ab76fea6bc336b9af88fd00bf5e08

Remove the documentation of the maint branch.

paraslash-0.6.5 was the last maintenance release. As of today,
the "maint" branch no longer exists in the git repo, so adjust the
documentation at two places: the user manual and the download page.
Streamline the text a bit, while at it.

Merge branch 'maint'

The merge conflicted in NEWS.md because both branches modified the
top of this file.

* maint:
  paraslash 0.6.5

paraslash 0.6.5

Merge topic branch t/sf_float into master

A single patch which adds two new sample formats for 32 bit IEEE
float waveform data. Cooking for two months.

* refs/heads/t/sf_float:
  New audio formats: 32 bit float (little and big endian).

manual: Streamline lopsub install instructions.

These days one can install the distribution's lopsub package, so
suggest getting it with apt-get(8) rather than by compiling from
source.

Switch the protocol in the URL for the lopsub web page from http to
https while at it.

Merge topic branch t/openssl-3 into master

The series starts with a few cleanups and crypto-backend tweaks to
beat the openssl specific code into shape for the main objective:
the switch of the RSA encryption and decryption routines to the
high-level EVP API. This has become necessary because the old RSA
API functions have been deprecated in openssl-3.

This merge conflicted against commit a18458cff51c (No longer check
for CRYPTO_cleanup_all_ex_data()). The resolution is to remove the
checks which that commit removed and to add the checks which commit
0485079436ad (openssl: Use the EVP library for RSA public encryption)
of this series introduced.

Cooking for four months.

* refs/heads/t/openssl-3:
  openssl: Reactivate openssl warnings.
  openssl: Use the EVP library for RSA private decryption.
  openssl: Use the EVP library for RSA public encryption.
  apc_priv_decrypt: Let the callee allocate the buffer.
  apc_pub_encrypt: Let the callee allocate the buffer.
  openssl: Assume that openssl allocation functions functions succeed.
  openssl: Introduce openssl_perror().
  openssl: Don't pass pointers to RSA structures around.
  openssl: Kill rsa coefficient computations.
  client: Check buffer size returned by apc_priv_decrypt().

aac_afh: Remove noisy debug message.

This may be printed thousands of times. which is a bit over the top,
even for the debug loglevel.

New audio formats: 32 bit float (little and big endian).

At least the little endian version seems to be popular these days. It
is only supported by ALSA, however. To check whether a given wave
file employs one of the two SF_FLOAT formats (aka IEEE float) we have
to consult the format code, a 16 bit integer stored at offset 20 of
the wave header which describes the waveform data according to the
table below.

0x0001 PCM
0x0003 IEEE float
0x0006 8-bit ITU-T G.711 A-law
0x0007 8-bit ITU-T G.711 MU-law
0xFFFE Determined by SubFormat

Additional checks are added to check_wav_post_select() which make
sure that the format code is either 1 or 3, and that the number is
compatible with the bits per sample value.

Merge topic branch t/ls-l into master

A single commit which deprecates the chunk table and mbox listing
modes. The chunk table can still be listed with para_afh(1), and the
mbox format was never really useful to begin with. The idea is to
remove support after 0.8.0 has been released.

Cooking for three months.

* refs/heads/t/ls-l:
  server: Deprecate -l=c and -l=m of com_ls().

gui: Fix formatting of amp value.

It was observed on a 178 column wide xterm window that for the colorful
blackness theme the amp value shown in the top window of para_gui
wrapped into the subsequent line under some circumstances. Adjust
the corresponding value in gui_theme.c to fix this.

Also add the missing space character to the prefix and fix a whitespace
issue while at it.

Merge topic branch t/btr into master

Some helpers such as btr_get_input_queue_size() are very expensive
if the buffer tree contains many buffers, which is the case for mp3
and aac streams. This is noticeable in particular with para_play,
which spends more time in the btr subsystem than in the mp3 decoder
if the file is large enough. This branch contains a few patches to
improve that.

Cooking for four months.

* refs/heads/t/btr:
  btr: Streamline the documentation of buffer_tree.h.
  Constify buffer tree API.
  btr: Merge buffers on insertion.
  btr: Speed up btr_node_status().
  Speed up mp3dec filter.

Merge topic branch t/play into master

This small series contains a few minor tweaks for para_play. The most
obvious change is that para_play is no longer built on systems which
lack libreadline.

The merge conflicted badly in configure.ac due to the changes
introduced by the earlier merge of the "built" topic branch. The
resolution needs to modify the non-conflicting Makefile.real to exclude
para_play from the list of executables if libreadline is not present
while the corresponding commit of the "play" topic branch implemented
the logic in configure.ac.

Cooking for a month.

* refs/heads/t/play:
  play: Shut down alsa on input EOF.
  play: Simplify and improve get_key_map_seq().
  play: Remove pointless goto in play_post_monitor().
  Return from filter_setup() so callers can reset the terminal.
  Let para_play depend on libreadline.

play: Shut down alsa on input EOF.

para_play leaks a lot of memory on exit because we didn't bother
to shut down the alsa subsystem. While this is harmless from the
correctness point of view, it does make it harder to spot real
memory leaks.

Rework the error handling to always shut down alsa via kill_stream().
Combine play_post_monitor() and session_post_monitor() because they
are small enough and the latter was badly named anyway.

play: Simplify and improve get_key_map_seq().

Combine it with get_user_key_map_seq() and replace the NULL check
with an assertion since the condition can never be true here. This
makes gcc's static analyzer happy, which complained about a possible
NULL pointer dereference.

play: Remove pointless goto in play_post_monitor().

We may as well return directly.

manual: Replace FTP link to libgcrypt.

Apparently, this FTP server has been switched off and checklink is
right to complain about it. Use the https link to the web page instead.

i9e: Clear history on close.

This frees each history entry and the history itself, reducing the
amount of memory leaked by readline applications on exit. Normally,
this should not be used since it leaks the memory associated with the
user defined history data pointer of each entry. However, that's OK
here because the i9e subsystem ignores this feature of the history
library.

Merge topic branch t/build into master

This series simplifies the build system quite a bit. The bulk of the
series consists of the commits which move the logic to construct
the object list of the paraslash executables from configure.ac to
Makefile.real.

Started on 2023-06-21, was cooking for five months.

* refs/heads/t/build:
  build: Rename all_objs -> dep_objs.
  build: No longer check for CRYPTO_cleanup_all_ex_data().
  build: Construct list of executables in Makefile.
  build: Construct audioc object list in Makefile.
  build: Construct write object list in Makefile.
  build: Construct play object list in Makefile.
  build: Construct afh object list in Makefile.
  build: Construct filter object list in Makefile.
  build: Construct recv object list in Makefile.
  build: Construct gui object list in Makefile.
  build: Construct mixer object list in Makefile.
  build: Construct audiod and client object list in Makefile.
  build: Construct server and upgrade_db object list in Makefile.
  build: Simplify condition for building para_server.
  build: Simplify ogg helpers of configure.ac.
  build: Remove AUDIOD_AUDIO_FORMATS_ENUM.
  build: Remove _errlist in shell variables of configure.ac.
  build: yy_src_dir and yy_build_dir can be simply expanded.
  build: Remove info about ucred from configure output.

exec: Simplify fd handling.

The new code is equivalent, but a bit shorter.

Merge branch 'maint'

The merge conflicted due to an integer overflow fix in com_jmp().

* maint:
  play: Fix some integer overflows().

Return from filter_setup() so callers can reset the terminal.

This function of filter_common.c calls exit(3) on errors. This is OK
for para_filter and para_audiod, but not for para_play because there
the function is called after readline has initialized the terminal for
its own use. If the function calls exit(3), the terminal settings are
not reset as they should have been. This can be observed for example
on the attempt to open an mp3 file with an para_play executable that
lacks mp3 support.

This commit changes the function to return an error code instead and
deals with the fallout in the three callers. Although play.c already
had error checking for calls to filter_setup(), it still needs a minor
tweak because we now have to deal with the fact that the filter and
writer node don't exist in eof_cleanup().

Let para_play depend on libreadline.

While para_client and para_audioc are suitable for non-interactive
use, e.g. in scripts, para_play can only be used interactively,
and its non-readline version is barely usable.

Rather than building a crippled version, teach the build and test
systems to skip para_play if the readline library is not installed.

server: Deprecate -l=c and -l=m of com_ls().

These are not very useful. The implementation will be removed after
0.8.0.

play.c: Replace NULL check by assertion.

If p is NULL, kma contains no colon, and we should not be here in the
first place. Instead, we should have errored out much earlier in the
command line parser.

Suggested-by: gcc(1)

filter_common: Annotate possible NULL pointer confusion.

We know at this point that filter_num is good, so filter_get()
returns non-NULL. But gcc-13's static analyzer does not see this and
warns. The added assertion makes the warning go away and tells the
reader that f == NULL is impossible here.

play: Fix some integer overflows().

If one factor of a product is a chunk number, we need to be careful
with respect to integer overflows. This patch adds casts which force
64 bit arithmetics to avoid that.

The overflows were observed while navigating a ~4 hour mp3 file.

openssl: Reactivate openssl warnings.

Now that we use the EVP API for RSA if openssl-3 was detected, the
openssl code no longer calls deprecated functions, so turn back on
the warnings for uses of openssl library functions which are marked
as deprecated.

openssl: Use the EVP library for RSA private decryption.

This is the counterpart of the previous commit which converted the
public RSA encryption. We employ the HAVE_OSSL_PARAM macro again to
distinguish between the openssl-1 and openssl-3 cases.

openssl: Use the EVP library for RSA public encryption.

Many functions related to RSA have been deprecated in openssl-3. Users
of the deprecated API are expected to switch to the high-level
cryptographic functions of the EVP library which ships together
with openssl.

Since openssl-1.0 is still supported and even openssl-1.1 lacks some
of the features we need for EVP, for example OSSL_PARAM_construct_BN(),
we check for this symbol at configure time and use #ifdefs in openssl.c
to compile the code conditionally depending on the value of the new
HAVE_OSSL_PARAM preprocessor macro. The code should work with both
old and new openssl versions.

apc_get_pubkey() used to call RSA_size() to obtain the key size in
bytes for the return value, but RSA_size() is one of the functions
that got deprecated in openssl-3. So modify read_public_key() to
return the number of bits of the modulus (rather than the constant
one), and use 1/8 of this number as the return value.

apc_priv_decrypt: Let the callee allocate the buffer.

This complements the previous commit which made the analogous
change for public encryption. Passing char ** instead of char * to
apc_priv_decrypt() allows us to get rid of the magic 1024 constant
in client_common.c.

apc_pub_encrypt: Let the callee allocate the buffer.

Change the encryption routine of the apc API to allocate a suitably
sized buffer itself. Currently, the caller has to guess the size of the
buffer to pass to the function and we reuse our 4k handshake buffer for
that. While 4k is is plenty at the moment, that may change, and it's
always better to use the exact size if it is readily available. This
is the case here because the required buffer size is just the number
of bits of the modulus of the key.

openssl: Assume that openssl allocation functions functions succeed.

We do the same thing with malloc() and friends, so replace error
checking by assertions whenever OOM is the only possible error reason.
Also add assertions for EVP_MD_CTX_new(), whose return value was not
checked at all.

openssl: Introduce openssl_perror().

Openssl has a decent error reporting framework, but we only employ
it if get_random_bytes_or_die() fails. This patch abstracts out a
new helper which prints the error string of the earliest error code
from the thread's error queue. We make the helper return -E_OPENSSL
unconditionally as this simplifies callers a bit.

Only get_random_bytes_or_die() calls the new helper for now but
additional callers will be added in subsequent commits.

openssl: Don't pass pointers to RSA structures around.

The RSA structure has been made opaque in openssl-3. As a preparation
for not using this structure any more, pass pointers to the containing
asymmetric key structure instead.

openssl: Kill rsa coefficient computations.

There's no need to pre-compute the two exponents for the Chinese
Remainder Theorem calculations as openssl will do that for us.

client: Check buffer size returned by apc_priv_decrypt().

The decoded challenge buffer contains the challenge and the two session
keys but nothing else. So we know its size up-front and should fail
the handshake if the size of the rsa-decrypted buffer differs.

web: Generate left- and right-justified text.

Larger pages such as the manual page look much nicer after this patch.

Change color of signature and tar icons.

These icons are currently black, which looks nice on the white
background of the releases page. However, all other pages use a black
background, and it would be nice to extend this to the releases page
page as well (by teaching it to honor our para.css file). As a first
step, switch to grey icon colors as these look nice on both a black
and a white background.

Prevent doxygen from generating invalid html.

Doxygen is too stupid to grok the preprocessor tricks we are playing
here, so don't generate documentation for these parts.

Prefer https:// for web pages and git URLs.

The tuebingen.mpg.de git server now supports https, and so does the
people.tuebingen.mpg.de page. Update all these links accordingly.

This still leaves a lot of http:// links to external pages, but those
can be adjusted in separate patches.

manual: Avoid duplicate section headings.

There exist two "Examples" and two "Troubleshooting"
sections. Unfortunately the discount markdown converter is
unable to create a working table of contents section in this
situation: both links of the table of contents jump to the first
Examples/Troubleshooting section.

Fix this by renaming the sections.

manual: Replace http:// links with https://

All of these return 301 -> 200 OK.