I have discovered that PyPI is way more sensitive to RST warnings than
other platforms: warnings and errors will make the document not show
up correctly, which is currently the case here:
https://pypi.python.org/pypi/borgbackup/
the suggested changes remove Sphinx-specific markup from the output,
namely the badges and `|replacement|` patterns, but also the
`higlight` directive. this also requires adding tags to the README to
mark the badges to remove and removal of the `none` argument for the
`.. code-block::` element which was not having any significant in
Sphinx anyways.
the rationale is to simplify the README file to the bare
minimum. security researchers will be able to find the contact
information if they look minimally and people installing the software
will find a link where relevant (in binary releases only, since all
the others have other trust paths)
without those changes, all of the toctree document headings do not
show up. they are considered to be "below" the last heading of the
README file.
we also remove the "Notes" section from the readme as there is only
one note, regarding the fork.
we introduce a stub "introduction" element in the toctree, otherwise
it is impossible for the PDF rendered to render the README correctly.
this is to workaround a bug in the PDF renderer.
it seems now that the fork is more of historical value than a current
thing. people interested in the differences between borg and attic can
look in the FAQ, but I do not see why this is present in the README.
a new section regarding compatibility is created to keep that warning
in place.
/mnt/backup was confusing as people like to mount their backup disk on /mnt/backup,
but borg init /mnt/backup does not work if that directory already exists because it is
the mountpoint. it would work, if /mnt was the mountpoint, but that is not obvious
and also unusual.
also: remove mailing list and irc channel address from development docs,
it is enough to have this information on the main page and on the support page.
This is what attic used by default, but borgbackup defaults to "no compression".
I just adjusted the command invocation, so we can keep the example output
(which shows that stuff was compressed).
Also: add FAQ item about compression.
