id       = "calibre"
name     = "calibre"
homepage = "https://calibre-ebook.com"
description = "calibre is the one stop solution to all your e-book needs."
icon     = "theSVG:calibre"
executables   = ["calibre", "calibredb", "ebook-convert", "ebook-meta", "calibre-server", "calibre-smtp"]

[dotfiles]

# src/calibre/constants.py, the config_dir block: $CALIBRE_CONFIG_DIRECTORY wins
# outright; failing that it is
#
#   iswindows -> CSIDL_APPDATA joined with "calibre"
#   ismacos   -> os.path.expanduser('~/Library/Preferences/calibre')
#   else      -> os.getenv('XDG_CONFIG_HOME', '~/.config') joined with "calibre"
#
# The manual points at the same place from the other end: Preferences ->
# Advanced -> Miscellaneous, "Open calibre configuration folder", and its macOS
# example for setting environment variables is a file inside
# ~/Library/Preferences/calibre (https://manual.calibre-ebook.com/customize.html).
#
# macOS lands on ~/Library/Preferences rather than Application Support, which is
# the [preferences] base directory; Linux reads $XDG_CONFIG_HOME, which is
# [configHome]; Windows is %APPDATA%, a place of its own. Three roots for three
# platforms, the way glow's are.
paths = [
  "[configHome]/calibre/",
  "[preferences]/calibre/",
  "%APPDATA%/calibre/",
]

# constants.py, _get_cache_dir(): `confcache = os.path.join(config_dir,
# 'caches')` and it is created on every start, whether or not the platform
# cache directory is used instead. It is a cache inside the config directory, so
# it is carved out of all three spellings — one missing copy and the Windows
# tree syncs what the Unix tree drops.
exclude = [
  "[configHome]/calibre/caches/",
  "[preferences]/calibre/caches/",
  "%APPDATA%/calibre/caches/",
]

# src/calibre/utils/smtp.py builds its settings with `Config('smtp', desc)` and
# `c.add_opt('relay_password')` alongside the relay host, port and username.
# src/calibre/utils/config_base.py, Config.config_file_path:
# `os.path.join(config_dir, self.filename_base + '.py.json')`, with the
# extensionless `smtp.py` read as the pre-migration spelling of the same file.
# So calibre's e-mail account, password included, is a small file inside the
# config directory whose whole purpose is that account — a credential rather
# than a setting with a credential in it. Both spellings are listed for each
# platform, since a machine that has not been migrated still has the old one.
secret = [
  "[configHome]/calibre/smtp.py.json",
  "[preferences]/calibre/smtp.py.json",
  "%APPDATA%/calibre/smtp.py.json",
  "[configHome]/calibre/smtp.py",
  "[preferences]/calibre/smtp.py",
  "%APPDATA%/calibre/smtp.py",
]

# No machine_lines. The directory is column layouts, saved searches, conversion
# defaults, tweaks and plugin settings — the things a user wants on their other
# machine — and the paths inside it that are machine-local (the library
# location) sit in JSON files a rule would have to name one by one, which is
# more guessing than this entry should do.