Manual Improvements RE: documenting $DATADIR / --data-dir paths/folders

[0xdevalias]

Describe your proposed improvement and the problem it solves.

Figured I would create a new issue to track this rather than continue in the comments of an old/closed issue:

(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.)

Originally posted by @0xdevalias in #3582 (comment)

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

Originally posted by @jgm in #3582 (comment)

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?

Originally posted by @0xdevalias in #3582 (comment)

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.

Originally posted by @jgm in #3582 (comment)

I think this would only be useful as a form of documentation

Agreed.

And it's not great as a form of documentation

Agreed.

It might be worth documenting this somewhere, though.

At the risk of potentially slightly raising maintenance burden if/when these things change, I definitely would have found it useful the other day. But also not too sure how often this need would arise for people in a 'grand scheme' type way (I wanted to setup the folder structure for my dotfiles), as opposed to just looking for the specific individual thing they need in the moment.

One thing I did notice while skimming the manual was that some entries use the convention of mentioning $DATADIR, and those ones were relatively easy to find even across the different manual entries. But then there were also a bunch that just mentioned something like 'user data directory' or similar, and I think some others that didn't necessarily follow that pattern and/or may not have been documented (or at least found during my skim through the manual) at all.

I also noticed that some mentions of 'user data directory' link back to --data-dir, but not all, often like this:

(see --data-dir)

Like in:

• https://pandoc.org/MANUAL.html#option--reference-doc

For Docx it mentions:

If no reference docx is specified on the command line, pandoc will look for a file reference.docx in the user data directory (see --data-dir).

And similar for ODT:

If no reference ODT is specified on the command line, pandoc will look for a file reference.odt in the user data directory (see --data-dir).

But then PowerPoint doesn't mention that part at all.

Originally posted by @0xdevalias in #3582 (comment)

Describe alternatives you've considered.

Leaving things as they are and leaving it as an exercise to the interested user to find/figure out if/as needed.