Merge branch 'dompdf-font' into 'master'

Update docs for adding fonts to dompdf now that it's possible to do it and survive upgrade

See merge request documentation/docs/installation!35

docs/general/unicode_pdf.md

 # Using non-latin characters in PDF output
 
-(This does not apply to Drupal 8/9.)
+There are certain places in CiviCRM where PDF output will contain `?` instead of the appropriate character because the DejaVu unicode font files have been removed from the DOMPDF library. For example CiviCRM uses DOMPDF when producing PDF copies of CiviReports, but it uses a different library (TCPDF) for Mailing Labels, which does have the DejaVu fonts.
 
-By default there are certain places in CiviCRM where PDF output does not handle non-latin characters because the unicode font files have been removed from the DOMPDF library. For example CiviCRM uses it when producing PDF copies of CiviReports, but by comparison it uses a different library for Mailing Labels.
+In Drupal 8/9, the entire DOMPDF library is downloaded during install, so it will work with most unicode characters as-is. But if you need CJK characters DejaVu does not contain those, so you will need to install another font file such as SimSun using the steps below.
 
-Note when testing to see if you've succeeded, use letters that are entirely outside the latin alphabet, e.g. use cyrillic letters. Several letters like `ü` will work either way so aren't a good test.
+Note when testing to see if you've succeeded, use letters that are entirely outside the character set included in the basic font files, e.g. use cyrillic letters such as `д`. Several letters like `ü` will work either way so aren't a good test.
 
 ??? example "Option A: Install the unicode font files for DOMPDF"
 
-    You will need to repeat these steps after each CiviCRM upgrade.
-
-    1. Get the dompdf download zip file from the github repository, e.g. at https://github.com/dompdf/dompdf/releases/tag/v0.8.6.
-      * You might want to use the exact same release (github tag) that core uses. For the font it shouldn't matter, but you can find this number by looking in composer.lock in your civicrm root folder and searching for "dompdf" and look at the "version" field.
-    1. Extract the files and look in the dompdf/lib/fonts folder.
-    1. Copy all the DejaVuSans files over to your `<civicrm_root>/vendor/dompdf/dompdf/lib/fonts` folder.
-    1. Edit the `dompdf_font_family_cache.dist.php` file in the same folder and add these lines:
-    ```php
-    'dejavu sans' =>
-        [
-            'bold' => DOMPDF_DIR . '/lib/fonts/DejaVuSans-Bold',
-            'bold_italic' => DOMPDF_DIR . '/lib/fonts/DejaVuSans-BoldOblique',
-            'italic' => DOMPDF_DIR . '/lib/fonts/DejaVuSans-Oblique',
-            'normal' => DOMPDF_DIR . '/lib/fonts/DejaVuSans'
-        ],
-    'dejavu sans mono' =>
-        [
-            'bold' => DOMPDF_DIR . '/lib/fonts/DejaVuSansMono-Bold',
-            'bold_italic' => DOMPDF_DIR . '/lib/fonts/DejaVuSansMono-BoldOblique',
-            'italic' => DOMPDF_DIR . '/lib/fonts/DejaVuSansMono-Oblique',
-            'normal' => DOMPDF_DIR . '/lib/fonts/DejaVuSansMono'
-        ],
-    'dejavu serif' =>
-        [
-            'bold' => DOMPDF_DIR . '/lib/fonts/DejaVuSerif-Bold',
-            'bold_italic' => DOMPDF_DIR . '/lib/fonts/DejaVuSerif-BoldItalic',
-            'italic' => DOMPDF_DIR . '/lib/fonts/DejaVuSerif-Italic',
-            'normal' => DOMPDF_DIR . '/lib/fonts/DejaVuSerif'
-        ],
+    1. Download the dompdf zip file from the [github repository](https://github.com/dompdf/dompdf/releases).
+    1. Create a folder in a location that won't get overwritten when you upgrade, e.g. sites/default/fonts for Drupal.
+    1. Extract all the DejaVu files, including the DejaVu-XXX.ufm files as well as the .ttf files, from the lib/fonts subfolder in the zip file into the folder you created.
+    1. In the folder you created, create a file called `dompdf_font_family_cache.php` and put this in it. Don't replace `$fontDir` with anything leave it as that variable.
     ```
+    <?php return [
+      'dejavu sans' => [
+        'bold' => $fontDir . '/DejaVuSans-Bold',
+        'bold_italic' => $fontDir . '/DejaVuSans-BoldOblique',
+        'italic' => $fontDir . '/DejaVuSans-Oblique',
+        'normal' => $fontDir . '/DejaVuSans',
+      ],
+      'dejavu sans mono' => [
+        'bold' => $fontDir . '/DejaVuSansMono-Bold',
+        'bold_italic' => $fontDir . '/DejaVuSansMono-BoldOblique',
+        'italic' => $fontDir . '/DejaVuSansMono-Oblique',
+        'normal' => $fontDir . '/DejaVuSansMono',
+      ],
+      'dejavu serif' => [
+        'bold' => $fontDir . '/DejaVuSerif-Bold',
+        'bold_italic' => $fontDir . '/DejaVuSerif-BoldItalic',
+        'italic' => $fontDir . '/DejaVuSerif-Italic',
+        'normal' => $fontDir . '/DejaVuSerif',
+      ],
+    ];
+    ```
+    1. Visit Administer - System Settings - Misc and in the field for `DOMPDF Font Folder` put the full path to the font folder you created.
+    1. When composing the PDF, if you have pasted from Microsoft Word into CKEditor it might set a specific font and then you will still see `?` in the output. You can click the Source button on the CKEditor toolbar to check - look for e.g. `<p style="font-family: Arial;">`.
+
+    ## Additional steps for CJK or an alternate unicode font
+
+    1. You will need to use the `load_font` utility from https://github.com/dompdf/utils. Download and extract it into some temporary folder.
+    1. Edit [the require line](https://github.com/dompdf/utils/blob/d9049f5b5df23b4e97b332a81205b5bb5ae1fbcc/load_font.php#L3) near the top of the `load_font.php` file and set it to the path to your CiviCRM installation's `vendor/autoload.php`.
+    1. Uncomment and edit [the $fontDir line](https://github.com/dompdf/utils/blob/d9049f5b5df23b4e97b332a81205b5bb5ae1fbcc/load_font.php#L9) near the top of the `load_font.php` file and set it to the fonts folder you created earlier for DejaVu.
+    1. Copy the .ttf font file you want to use into the folder where `load_font.php` is.
+    1. Run `php load_font.php font_name font_file.ttf`, where you replace the last two as appropriate for the font you are installing, e.g. `php load_font.php SimSun simsun.ttf`.
+    1. Note this will overwrite the `dompdf_font_family_cache.php` file you created earlier for DejaVu, so to also have DejaVu you will now need to edit the file and copy the php array from earlier back in.
+    1. Now you no longer need the `load_font` utility or its folder and can delete it.
+    1. Unlike with DejaVu which CiviCRM sets as the default font, you will need to specify the font when composing the PDF in the places where you use the CJK characters. You can use the Source button in CKEditor to do this and type it directly into the HTML: e.g. `<p style="font-family: simsun;">的</p>`
 
 ??? example "Option B: Install wkhtmltopdf instead"