Support multiple library folders. Follow up to mixxxdj/mixxx#21

source/chapters/djing_with_mixxx.rst

@@ -74,20 +74,14 @@ Importing your audio files
   <Operating System>`. :term:`DRM` protected files, such as m4p
   files purchased in the iTunes Store, are not supported.
 
-  AAC (M4A) is supported on Windows Vista and Mac OSX 10.5 onwards. The 
+  AAC (M4A) is supported on Windows Vista and Mac OSX 10.5 onwards. The
   `Platform Update Supplement <http://support.microsoft.com/kb/2117917>`_ is
   required for Windows Vista.
 
   On Linux, AAC playback is disabled by default due to licensing restrictions.
   To enable the playback of AAC files, `build Mixxx from source with m4a files support
   <http://www.mixxx.org/wiki/doku.php/compiling_on_linux#build_with_m4a_file_support>`_.
 
-**Changing the music directory**
-  The Mixxx music directory can always be changed at a later time in
-  :menuselection:`Preferences --> Library`. You might want to run a library
-  rescan afterwards, select :menuselection:`Library --> Rescan Library` in the
-  menu.
-
 **Import external libraries**
   If you have iTunes, Traktor, Rhythmbox, or Banshee installed, Mixxx allows you
   to access your tracks and playlists in the Mixxx library,
@@ -103,14 +97,62 @@ Importing your audio files
              Mixxx can not recursively scan folders for compatible music files.
 
 **Import playlists**
-  You can import existing :file:`m3u`, :file:`pls` , :file:`m3u8`, :file:`pls` 
+  You can import existing :file:`m3u`, :file:`pls` , :file:`m3u8`, :file:`pls`
   playlist files from products other than Mixxx, see :ref:`library-playlists`.
 
 **Import music from CDs**
   Mixxx can not play music from Audio CDs. Convert the content to compatible
   files in good quality and add them to the Mixxx library. See
   `<https://en.wikipedia.org/wiki/Ripping>`_
 
+.. _djing-changing-music-directories:
+
+Changing music directories
+==========================
+
+.. versionadded:: 1.12
+   Handles multiple music library folders and adds an option to move them to
+   another location without data loss.
+
+You can manually add, relink, and remove Mixxx music directories in
+:menuselection:`Preferences --> Library`.
+
+**Add a new music directory**
+  Mixxx handles multiple music library folders. Click :guilabel:`Add` to
+  browse to a directory where your music is stored. Mixxx will watch this
+  directory and its subdirectories for new tracks.
+
+  Directories can also be added from the :ref:`Browse <library-browse>` sidebar
+  item inside the library.
+
+**Relink a existing music directory**
+  If an existing music directory is moved, Mixxx doesn't know where to find the
+  audio files in it. Click :guilabel:`Relink` to select the music directory
+  in its new location. This will re-establish the links to the audio files in
+  the Mixxx library.
+
+**Remove a music directory**
+  Click :guilabel:`Remove`, and Mixxx will no longer watch a directory and
+  its subdirectories for new tracks, and asks what would you like to do with the
+  tracks from these directories.
+
+  * Select :guilabel:`Hide Tracks` to hide all tracks from this directory and
+    subdirectories.
+  * Select :guilabel:`Delete Track Metadata` to delete all metadata for these
+    tracks from Mixxx permanently
+  * Select :guilabel:`Leave Tracks Unchanged` to leave the tracks unchanged in
+    your library.
+
+  Hiding tracks saves their metadata in case you re-add them in the future.
+
+  Metadata means all track details (artist, title, playcount, etc.) as well as
+  beatgrids, hotcues, and loops. This choice only affects the Mixxx library.
+  No files on disk will be changed or deleted.
+
+.. hint:: When changing music directories, you might want to run a library
+          rescan afterwards. Select :menuselection:`Library --> Rescan Library`
+          in the menu.
+
 .. _djing-loading-tracks:
 
 Loading Tracks

source/chapters/library.rst

@@ -394,6 +394,9 @@ Browse - Loading remote tracks
 |ic_lib_browse| Browse mode works like a file-manager and allows you to load
 tracks that are not necessarily already in your Mixxx library.
 
+.. versionadded:: 1.12
+   Add music directories directly from the Browse sidebar item.
+
 Click the :guilabel:`Browse` sidebar item to navigate the computer and find your
 music. Depending on your :term:`operating system`, the music will usually be
 found in the “My Music” or “Music” folder. Drag the files you want to import to
@@ -403,6 +406,12 @@ the |ic_lib_library| :ref:`Library <library-root>` icon or directly to the
 .. note:: Currently you can drag only files but not folders to the Mixxx
           library.
 
+Right-click on a folder and choose :guilabel:`Add to Library` to add the folder
+as new music directory. Mixxx will watch this directory and its subdirectories
+for new tracks.
+
+.. seealso:: For more informations, go to :ref:`djing-changing-music-directories`.
+
 Quick Links - Bookmark your favorite folders
 --------------------------------------------