Support XDG Base directory specification

[afranke]

The manual currently says that if --data-dir is not specified the default value is ~/.pandoc/.

The XDG Base directory spec defines $XDG_DATA_HOME (~/.local/share by default) and Pandoc should take this into account.

For compatibility all three locations could be searched: first $XDG_DATA_HOME/pandoc/, then ~/.local/share/pandoc/ and finally ~/.pandoc/.

[Wandmalfarbe]

I would like to add that the Arch Linux Wiki provides an excellent resource for implementation examples and a list of programs that support the XDG Base Directory Specification.

[jgm]

We currently use the standard Haskell function getAppUserDataDirectory to get this.

http://hackage.haskell.org/package/directory-1.3.3.2/docs/System-Directory.html#v:getAppUserDataDirectory

Looking at the docs, I see that in directory >= 1.2.3.0, they also have getXdgDirectory and getXdgDirectoryList.

I'd have to think carefully about what would be necessary to make the change. It might be quite easy, but we should do it in a backwards-compatible way (searching ~/.pandoc too).

[barskern]

Perhaps the easiest way of resolving this would be to firstly check the XDG directory, and if it does not exist, it will fall back to the old solution? As I understand it, pandoc will not write to that directory, but the user can specify custom templates there, hence as long as pandoc doesn't need to chose where to write, it shouldn't be backwards incompatible.

[jgm]

Ole Martin Ruud <notifications@github.com> writes:

Perhaps the easiest way of resolving this would be to firstly check the XDG directory, and if it does not exist, it will fall back to the old solution? As

This is what I've done.

[0xdevalias]

Perhaps the easiest way of resolving this would be to firstly check the XDG directory, and if it does not exist, it will fall back to the old solution? As
This is what I've done.

In case anyone was wondering where this is implemented, it's here:

pandoc/src/Text/Pandoc/Data.hs

Lines 228 to 245 in fd49684

	-- | Return appropriate user data directory for platform. We use
	-- XDG_DATA_HOME (or its default value), but for backwards compatibility,
	-- we fall back to the legacy user data directory ($HOME/.pandoc on *nix)
	-- if the XDG_DATA_HOME is missing and this exists. If neither directory
	-- is present, we return the XDG data directory. If the XDG data directory
	-- is not defined (e.g. because we are in an environment where $HOME is
	-- not defined), we return the empty string.
	defaultUserDataDir :: IO FilePath
	defaultUserDataDir = do
	xdgDir <- E.catch (getXdgDirectory XdgData "pandoc")
	(\(_ :: E.SomeException) -> return mempty)
	xdgExists <- doesDirectoryExist xdgDir
	legacyDir <- E.catch (getAppUserDataDirectory "pandoc")
	(\(_ :: E.SomeException) -> return mempty)
	legacyDirExists <- doesDirectoryExist legacyDir
	if not xdgExists && legacyDirExists
	then return legacyDir
	else return xdgDir

pandoc/src/Text/Pandoc/Data.hs

Lines 68 to 79 in fd49684

	--- | Read file from user data directory or,
	--- if not found there, from the default data files.
	readDataFile :: PandocMonad m => FilePath -> m B.ByteString
	readDataFile fname = do
	datadir <- checkUserDataDir fname
	case datadir of
	Nothing -> readDefaultDataFile fname
	Just userDir -> do
	exists <- fileExists (userDir </> fname)
	if exists
	then readFileStrict (userDir </> fname)
	else readDefaultDataFile fname

(Context: I was trying to find a canonical list of files/paths pandoc uses within XDG_DATA_HOME, beyond what was casually mentioned in the help docs for --data-dir, --defaults, --template, etc. My search attempt; I guess this is probably a good start, but then it still doesn't seem to show all of the directory structure/etc.)

[jgm]

See the data/ directory in the source.
All the subdirectories there should be overridable in XDG_DATA_HOME.

[0xdevalias]

See the data/ directory in the source.

@jgm I did see that, but it doesn't include everything. For example, there is no custom or filters or defaults folders there in the git repo. From my skimming through the docs I suspect there are others too.

eg. From 0xdevalias/dotfiles@1eebd22

[local] pandoc: create placeholder DATADIR folder structure (for at least some of the folders here)
- https://github.com/jgm/pandoc/issues/3582#issuecomment-2586099054
- https://pandoc.org/MANUAL.html#option--data-dir
  - DATADIR
    - $XDG_DATA_HOME/pandoc
    - $HOME/.local/share/pandoc
    - $HOME/.pandoc
- https://pandoc.org/MANUAL.html#option--filter
  - $DATADIR/filters
- https://pandoc.org/MANUAL.html#option--lua-filter
  - $DATADIR/filters
- https://pandoc.org/MANUAL.html#custom-readers-and-writers
  - $DATADIR/custom
- https://pandoc.org/MANUAL.html#option--defaults
  - $DATADIR/defaults
- https://pandoc.org/MANUAL.html#option--metadata-file
  - $DATADIR/metadata
- https://pandoc.org/MANUAL.html#templates
  - $DATADIR/templates/default.*FORMAT*
- https://pandoc.org/MANUAL.html#option--template
  - $DATADIR/templates
- https://pandoc.org/MANUAL.html#option--abbreviations
  - $DATADIR/abbreviations
- https://pandoc.org/MANUAL.html#styling-the-slides
  - $DATADIR/s5
  - $DATADIR/slidy
  - $DATADIR/slideous
- etc

Would it make sense to maintain that structure in the source repo, even for empty folders, and just add a .gitkeep or similar? Or should it be left as a task to the end user to find the appropriate part via the docs JIT as they need it?

[jgm]

Would it make sense to maintain that structure in the source repo, even for empty folders

I think this would only be useful as a form of documentation (since there are no system data files to override in these subdirectories). And it's not great as a form of documentation, since it's a pretty rare user who will be looking at the source code to figure this out. It might be worth documenting this somewhere, though.