tweak graphics conversion stuff

Author: phfaist

doc/selfdocenv.rst

@@ -1,15 +1,15 @@
 Self-Documenting Environments
 =============================
 
-The ``flm.docgen`` module provides a self-documenting environment system
-that lets feature authors write structured documentation for macros,
-environments, and specials directly in FLM markup.
+The ``flm.docgen`` module provides a self-documenting environment system that
+lets feature authors write structured documentation for macros, environments,
+and specials directly in FLM markup.
 
 The system defines special-purpose constructs (``\flmDocArg``,
-``{flmDocArguments}``, etc.) that produce formatted argument documentation
-when rendered.  This is used internally to generate the
-:doc:`standard-syntax` reference from the ``get_flm_doc()`` methods on
-each spec info class.
+``{flmDocArguments}``, etc.) that produce formatted argument documentation when
+rendered.  I'm planning to use this internally to generate the
+:doc:`standard-syntax` reference from the ``get_flm_doc()`` methods on each spec
+info class.
 
 .. automodule:: flm.docgen.docgen
    :members:

flm/main/feature_graphics_collection.py

@@ -150,7 +150,12 @@ class GraphicsFormatConversionRule:
           'via': [..list of converter names..],
           'options': <dict or None> }
 
-    Built-in converter names are: 'cairosvg', 'gs', 'pdftocairo', 'magick'.
+    Built-in converter names are: 'cairosvg', 'gs', 'pdftocairo', 'magick'.  If
+    you specify a list of converter names, these are meant to be acceptable
+    converters to use to perform the transformation.  The rule will pick the
+    first one that can perform the conversion.  (There is currently no way of
+    specifying a conversion chain through multiple converters with intermediate
+    formats.)
 
     Example rule in YAML::
 
@@ -159,7 +164,6 @@ class GraphicsFormatConversionRule:
             to: '.png'
             options:
               dpi: 192
-
     """
 
     def __init__(self, rule):
@@ -220,10 +224,17 @@ def get_converter_or_none(self, ext):
             if len(self.via_list) and converter.name not in self.via_list:
                 continue
 
-            try:
-                can_convert = converter.can_convert(ext, to_ext)
-            except ConverterNotAvailable as e:
-                converter_errors.append(e)
+            can_convert = None
+            if len(self.via_list) == 1 and self.via_list[0] == converter.name:
+                # user requested this converter specifically, don't call
+                # can_convert().
+                can_convert = True
+
+            if can_convert is None:
+                try:
+                    can_convert = converter.can_convert(ext, to_ext)
+                except ConverterNotAvailable as e:
+                    converter_errors.append(e)
 
             if not can_convert:
                 continue
@@ -353,7 +364,7 @@ def convert(self, source_type, src_url, target_path, converter_info, options=Non
         elif target_ext in ('.ps', '.eps'):
             svgconvert = cairosvg.svg2ps
         else:
-            raise ValueError(f"Invalid target ext {target_ext}, shouldn't be here")
+            raise ValueError(f"Invalid target ext {target_ext}")
 
         svgconvert(url=src_url, write_to=target_path, **svgkwargs)
 
@@ -504,6 +515,11 @@ def convert(self, source_type, src_url, target_path, converter_info, options=Non
             xtracmdargs += [ '-transp' ]
 
         input_data = self.read_input(source_type, src_url, binary=True)
+
+        if target_ext not in self._fmts_to_opts:
+            raise ValueError(
+                f"Invalid target extension for PdfToCairoCmdlConverter: ‘{target_ext}’"
+            )
 
         cmdargs = [
             self.pdftocairo_exe,
@@ -545,7 +561,8 @@ def can_convert(cls, ext, to_ext):
             )
         except ExecutableNotFoundError as e:
             raise ConverterNotAvailable(cls.name, e.msg, exc=e)
-
+        # by default, any conversion is possible - magick supports pretty much
+        # everything
         return True
 
     def __init__(self):
@@ -558,7 +575,7 @@ def convert(self, source_type, src_url, target_path, converter_info, options=Non
         else:
             options = dict(options)
 
-        transparent_bg = options.pop('transparent_bg', False)
+        transparent_bg = options.pop('transparent_bg', None)
         dpi = options.pop('dpi', None)
 
         if len(options):
@@ -570,19 +587,27 @@ def convert(self, source_type, src_url, target_path, converter_info, options=Non
         if src_url.endswith( ('.gif', '.mng') ):
             ins = '-[0]'
 
-        extra_args = []
+        extra_settings = []
+        extra_operators = []
+        
         if transparent_bg:
-            extra_args = extra_args + [ '-background', 'none', ]
+            extra_settings = extra_settings + [ '-background', 'none', ]
+        elif transparent_bg is False:
+            extra_operators = extra_operators + [
+                '-background', 'white', '-alpha', 'remove',
+                '-alpha', 'off',
+            ]
+        
         if dpi is not None:
-            extra_args = extra_args + [
+            extra_settings = extra_settings + [
                 '-density', str(dpi),
             ]
 
         cmdargs = [
             self.magick_exe,
-            'convert',
-            *extra_args,
+            *extra_settings,
             ins,
+            *extra_operators,
             target_path
         ]