Use XDG data directory for user data directory.

Instead of `$HOME/.pandoc`, the default user data directory is
now `$XDG_DATA_HOME/pandoc`, where `XDG_DATA_HOME` defaults to
`$HOME/.local/share` but can be overridden by setting the environment
variable.

If this directory is missing, then `$HOME/.pandoc` is searched
instead, for backwards compatibility.  However, we recommend
moving local pandoc data files from `$HOME/.pandoc` to
`$HOME/.local/share/pandoc`.

On Windows the default user data directory remains the same.

Closes #3582.

MANUAL.txt

@@ -349,18 +349,13 @@ General options {.options}
 
 :   Specify the user data directory to search for pandoc data files.
     If this option is not specified, the default user data directory
-    will be used.  This is, in UNIX:
+    will be used.  On \*nix and macOS systems this will be the `pandoc`
-
+    subdirectory of the XDG data directory (by default,
-        $HOME/.pandoc
+    `$HOME/.local/share`, overridable by setting the `XDG_DATA_HOME`
-
+    environment variable).  If that directory does not exist,
-    in Windows XP:
+    `$HOME/.pandoc` will be used (for backwards compatibility).
-
+    In Windows the default user data directory is
-        C:\Documents And Settings\USERNAME\Application Data\pandoc
+    `C:\Users\USERNAME\AppData\Roaming\pandoc`.
-
-    and in Windows Vista or later:
-
-        C:\Users\USERNAME\AppData\Roaming\pandoc
-
     You can find the default user data directory on your system by
     looking at the output of `pandoc --version`.
     A `reference.odt`, `reference.docx`, `epub.css`, `templates`,

pandoc.cabal

@@ -363,7 +363,7 @@ library
                  exceptions >= 0.8 && < 0.11,
                  filepath >= 1.1 && < 1.5,
                  process >= 1.2.3 && < 1.7,
-                 directory >= 1 && < 1.4,
+                 directory >= 1.2.3 && < 1.4,
                  bytestring >= 0.9 && < 0.11,
                  text >= 1.1.1.0 && < 1.3,
                  time >= 1.5 && < 1.10,
@@ -661,7 +661,7 @@ test-suite test-pandoc
                   base64-bytestring >= 0.1 && < 1.1,
                   text >= 1.1.1.0 && < 1.3,
                   time >= 1.5 && < 1.10,
-                  directory >= 1 && < 1.4,
+                  directory >= 1.2.3 && < 1.4,
                   filepath >= 1.1 && < 1.5,
                   hslua >= 1.0 && < 1.1,
                   process >= 1.2.3 && < 1.7,

src/Text/Pandoc/App.hs

@@ -38,7 +38,7 @@ import qualified Data.Text.Lazy.Encoding as TE
 import qualified Data.Text.Encoding.Error as TE
 import qualified Data.Text.Encoding.Error as TSE
 import Network.URI (URI (..), parseURI)
-import System.Directory (getAppUserDataDirectory)
+import System.Directory (doesDirectoryExist)
 import System.Exit (exitSuccess)
 import System.FilePath
 import System.IO (nativeNewline, stdout)
@@ -55,7 +55,8 @@ import Text.Pandoc.PDF (makePDF)
 import Text.Pandoc.Readers.Markdown (yamlToMeta)
 import Text.Pandoc.SelfContained (makeDataURI, makeSelfContained)
 import Text.Pandoc.Shared (eastAsianLineBreakFilter, stripEmptyParagraphs,
-         headerShift, isURI, tabFilter, uriPathToPath, filterIpynbOutput)
+         headerShift, isURI, tabFilter, uriPathToPath, filterIpynbOutput,
+         defaultUserDataDirs)
 import qualified Text.Pandoc.UTF8 as UTF8
 #ifndef _WINDOWS
 import System.Posix.IO (stdOutput)
@@ -89,10 +90,15 @@ convertWithOpts opts = do
                         | otherwise  -> xs
 
   datadir <- case optDataDir opts of
-                  Nothing   -> E.catch
+                  Nothing   -> do
-                                 (Just <$> getAppUserDataDirectory "pandoc")
+                    ds <- defaultUserDataDirs
-                                 (\e -> let _ = (e :: E.SomeException)
+                    let selectUserDataDir [] = return Nothing
-                                        in  return Nothing)
+                        selectUserDataDir (dir:dirs) = do
+                              exists <- doesDirectoryExist dir
+                              if exists
+                                 then return (Just dir)
+                                 else selectUserDataDir dirs
+                    selectUserDataDir ds
                   Just _    -> return $ optDataDir opts
 
   -- assign reader and writer based on options and filenames

src/Text/Pandoc/App/CommandLineOptions.hs

@@ -46,15 +46,14 @@ import Text.Pandoc.App.Opt (Opt (..), LineEnding (..))
 import Text.Pandoc.Filter (Filter (..))
 import Text.Pandoc.Highlighting (highlightingStyles)
 import Text.Pandoc.Writers.Math (defaultMathJaxURL, defaultKaTeXURL)
-import Text.Pandoc.Shared (ordNub, safeRead)
+import Text.Pandoc.Shared (ordNub, safeRead, defaultUserDataDirs)
 import Text.Printf
 
 #ifdef EMBED_DATA_FILES
 import Text.Pandoc.Data (dataFiles)
-import System.Directory (getAppUserDataDirectory)
 #else
 import Paths_pandoc (getDataDir)
-import System.Directory (getAppUserDataDirectory, getDirectoryContents)
+import System.Directory (getDirectoryContents)
 #endif
 
 import qualified Control.Exception as E
@@ -837,13 +836,11 @@ options =
                  (NoArg
                   (\_ -> do
                      prg <- getProgName
-                     defaultDatadir <- E.catch
+                     defaultDatadirs <- defaultUserDataDirs
-                            (getAppUserDataDirectory "pandoc")
-                            (\e -> let _ = (e :: E.SomeException)
-                                   in  return "")
                      UTF8.hPutStrLn stdout (prg ++ " " ++ pandocVersion ++
                        compileInfo ++ "\nDefault user data directory: " ++
-                       defaultDatadir ++ copyrightMessage)
+                       intercalate " or " defaultDatadirs ++
+                       ('\n':copyrightMessage))
                      exitSuccess ))
                  "" -- "Print version"
 
@@ -872,7 +869,6 @@ usageMessage programName = usageInfo (programName ++ " [OPTIONS] [FILES]")
 
 copyrightMessage :: String
 copyrightMessage = intercalate "\n" [
-  "",
   "Copyright (C) 2006-2019 John MacFarlane",
   "Web:  http://pandoc.org",
   "This is free software; see the source for copying conditions.",

test/command/lua-pandoc-state.md

@@ -1,5 +1,5 @@
 ```
-% pandoc --lua-filter=command/lua-pandoc-state.lua
+% pandoc --lua-filter=command/lua-pandoc-state.lua --data-dir=foo
 Hello
 ^D
    # input files: 0