Expand pdf-tools coverage

This merge request expands coverage for pdf-tools, a PDF reader. No, that's a euphemism. This merge request tries and fails to expand coverage for pdf-tools. That's more honest. I've hit some snags and could use an expert's opinion. Don't feel pressured to merge this, only my mother knows how to bruise my ego.

Link hints

First up, hints. These might remind you of avy and link-hint, hence why I styled them like avy. Before:

After:

Ignore the lowercase hint characters, they're specific to my Emacs. What incantations were required? I'm glad you ask!

The back-foreground

Hints are drawn by ImageMagick. The colors are determined by the face pdf-links-read-link. :foreground is used to, you guessed it, draw the undercolor and :background, obviously, the text. Now that I know how to make merge requests, I even created a topic branch, I proposed a radical change. How does it look? Terrible! Almost no undercolor, it's hard to read.

Not on the same page

Hints are drawn directly onto the page, they're not composed, i.e., one needs to be careful what flags one passes to the ImageMagick command. The command is determined by the variable pdf-links-read-link-convert-commands. pdf-tools places some constraints on this command, e.g. no %[fx:]-constructs to position the hints (not that it matters, bounding boxes for links are wild).

A bold statement

Mapping :width and :slant was rather straightforward:

# narrow to wide, Emacs to ImageMagick
ultra-condensed -                     FC_WIDTH_ULTRACONDENSED 50  UltraCondensed
extra-condensed -                     FC_WIDTH_EXTRACONDENSED 63  ExtraCondensed
condensed       "compressed","narrow" FC_WIDTH_CONDENSED      75  Condensed
semi-condensed  -                     FC_WIDTH_SEMICONDENSED  87  SemiCondensed
normal          "medium","regular"    FC_WIDTH_NORMAL         100 Normal
semi-expanded   "demiexpanded"        FC_WIDTH_SEMIEXPANDED   113 SemiExpanded
expanded        -                     FC_WIDTH_EXPANDED       125 Expanded
extra-expanded  "wide"                FC_WIDTH_EXTRAEXPANDED  150 ExtraExpanded
ultra-expanded  -                     FC_WIDTH_ULTRAEXPANDED  200 UltraExpanded

# Emacs to ImageMagick
italic          ItalicStyle  Italic
oblique         ObliqueStyle Oblique
normal          NormalStyle  Normal
roman           -            -
reverse-italic  -            -
reverse-oblique -            -

Mapping :weight was less so:

# thin to thick, Emacs to ImageMagick
ultra-light -                  FC_WEIGHT_THIN       0                    Thin       100
extra-light -                  FC_WEIGHT_EXTRALIGHT 40                   ExtraLight 200
-           -                  FC_WEIGHT_ULTRALIGHT FC_WEIGHT_EXTRALIGHT UltraLight 200
light       -                  FC_WEIGHT_LIGHT      50                   Light (?)  300
thin        -                  -                    -                    -          -
semi-light  "book"             FC_WEIGHT_BOOK       75                   -          300
-           -                  FC_WEIGHT_REGULAR    80                   Regular    400
normal      "regular","medium" FC_WEIGHT_NORMAL     FC_WEIGHT_REGULAR    Normal     400
-           -                  FC_WEIGHT_MEDIUM     100                  Medium     500
-           -                  FC_WEIGHT_DEMIBOLD   180                  DemiBold   600
semi-bold   "demibold"         FC_WEIGHT_SEMIBOLD   FC_WEIGHT_DEMIBOLD   SemiBold   600
bold        -                  FC_WEIGHT_BOLD       200                  Bold       700
extra-bold  "heavy"            FC_WEIGHT_EXTRABOLD  205                  ExtraBold  800
-           -                  FC_WEIGHT_ULTRABOLD  FC_WEIGHT_EXTRABOLD  UltraBold  800
ultra-bold  "black"            FC_WEIGHT_BLACK      210                  Black      900
-           -                  FC_WEIGHT_HEAVY      FC_WEIGHT_BLACK      Heavy      900

Passing a numeric weight doesn't do anything, i.e., you're stuck with the named weights. Also, Light is listed in the manual but it isn't when I run magick convert -list weight.

Occult literature

Dark documents, not the kind that summon Hastur, could make the region, isearch, hints etc. invisible. This is not the case:

This made me think of our past discussion on :distant-foreground. The minor mode pdf-view-dark-minor-mode causes the face spec of terminal with characteristic background dark to match. I didn't find any clarifying information. I assume it's "global" and not relevant to our past discussion.

A letdown

Why tell you this? What am I trying to do? Pass more face attributes to ImageMagick! What I came up with:

(with-eval-after-load 'pdf-links
  (let ((spec
         (apply #'append
                (mapcar
                 (lambda (name)
                   (list name
                         (face-attribute 'pdf-links-read-link
                                         name nil 'default)))
                 '(:family :width :weight :slant)))))
    (setq pdf-links-read-link-convert-commands
          `("-density"    "96"
            "-family"     ,(plist-get spec :family)
            "-stretch"    ,(let* ((width (plist-get spec :width))
                                  (name (symbol-name width)))
                             (replace-regexp-in-string "-" ""
                                                       (capitalize name)))
            "-weight"     ,(pcase (plist-get spec :weight)
                             ('ultra-light "Thin")
                             ('extra-light "ExtraLight")
                             ('light       "Light")
                             ('semi-bold   "SemiBold")
                             ('bold        "Bold")
                             ('extra-bold  "ExtraBold")
                             ('ultra-bold  "Black")
                             (_weight      "Normal"))
            "-style"      ,(pcase (plist-get spec :slant)
                             ('italic  "Italic")
                             ('oblique "Oblique")
                             (_slant   "Normal"))
            "-pointsize"  "%P"
            "-fill"       "%f"
            "-undercolor" "%b"
            "-draw"       "text %X,%Y '%c'"))))

It needs to rerun when the default, bold or pdf-links-read-link face changes, it's clunky, it's terrible.

I'm not a writer

I've added the above to the org manual but didn't dare to change the info one. The description is incomplete.

Occur

Next up, occur. Like occur but for PDF files. The file name or page number aren't that interesting, hence why I styled them like the shadow face:

Should I duplicate the attributes or inherit?

Annotations

I tried but got nowhere. The variable pdf-annot-default-annotation-properties is used for more than just appearance.

Other faces

All other faces seem fine.

A warning

This is unfinished and I'm stuck.