From e036ebc340fac8b4cac21f17fe9cbbd98619eee0 Mon Sep 17 00:00:00 2001
From: Marian Beermann <public@enkore.de>
Date: Fri, 28 Apr 2017 10:40:21 +0200
Subject: [PATCH] docs: installation: pre-install considerations, fix crossrefs

posix_fadvise -> only used when available; not part of the filesystem.
sync -> fsync
---
 docs/installation.rst              | 9 +++++----
 docs/internals/data-structures.rst | 4 ++++
 docs/usage_general.rst.inc         | 2 ++
 3 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/docs/installation.rst b/docs/installation.rst
index 1cb715562..3ae5bc8c7 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -27,7 +27,7 @@ Pre-Installation Considerations
 
 Repository File System
 ~~~~~~~~~~~~~~~~~~~~~~
-:ref:`data-structures-and-file-formats`
+
 - |project_name| stores data only 3 directory levels deep and uses short file and
   directory names.
 - |project_name| requires read and write permissions on the repository file system.
@@ -42,13 +42,14 @@ Repository File System
 - A journaling file system is strongly recommended. More information can be
   found in :ref:`file-systems`.
 - |project_name| requires the following file system operations:
+
   - create, open, read, write, seek, close, rename, delete
   - link - when upgrading an Attic repo in-place
   - listdir, stat
-  - posix_fadvise - to not flood the operating system's cache
-  - sync on files and directories to ensure data is written onto storage media
+  - fsync on files and directories to ensure data is written onto storage media
+    (some file systems do not support fsync on directories, which Borg accomodates for)
 
-:ref:`data-structures-and-file-formats` contains additional information about how |project_name|
+:ref:`data-structures` contains additional information about how |project_name|
 manages data.
 
 .. _locking: https://en.wikipedia.org/wiki/File_locking#Lock_files
diff --git a/docs/internals/data-structures.rst b/docs/internals/data-structures.rst
index a76f14e1b..cc7f0f1b2 100644
--- a/docs/internals/data-structures.rst
+++ b/docs/internals/data-structures.rst
@@ -1,6 +1,8 @@
 .. include:: ../global.rst.inc
 .. highlight:: none
 
+.. _data-structures:
+
 Data structures and file formats
 ================================
 
@@ -40,6 +42,8 @@ called segments_. Each segment is a series of log entries. The segment number to
 entry relative to its segment start establishes an ordering of the log entries. This is the "definition" of
 time for the purposes of the log.
 
+.. _config-file:
+
 Config file
 ~~~~~~~~~~~
 
diff --git a/docs/usage_general.rst.inc b/docs/usage_general.rst.inc
index addadc5b0..2b8c630e1 100644
--- a/docs/usage_general.rst.inc
+++ b/docs/usage_general.rst.inc
@@ -207,6 +207,8 @@ Please note:
 
 .. _INI: https://docs.python.org/3.4/library/logging.config.html#configuration-file-format
 
+.. _file-systems:
+
 File systems
 ~~~~~~~~~~~~