[Docutils-users] Automatic choosing of filename extension (was: Images in both HTML and LaTeX)

[Felix W. <Fel...@gm...>]

Before I go on, I'd like to clarify the objectives for that new feature.
Spontaneously I see the following points to keep in mind:

1. It should be unobstrusive
2. It should be intuitive.
3. It should work independent of configuration (i.e. settings).
4. It should be independent of the execution environment.

Any agreement, disagreement?

Some ideas on the syntax:

(Presume we want to link to the document foo.html in HTML and foo.pdf in
LaTeX.)

* ``.. _link:: foo.<html:html;latex:pdf>`` is obstrusive (point 1).

* ``.. _link:: foo.html`` with ``.html`` automatically getting replaced
  by ``.pdf`` if LaTeX source is generated -- this is somewhat
  unintuitive (point 2).

  Furthermore, in some cases this behaviour may be unwanted.  The only
  way to deactivate the substitution of filename extensions would be by
  using a directive (which is obstrusive, point 1) or a by passing a
  parameter to Docutils (which makes the document depend on a setting,
  point 3).

* ``.. _link: foo`` with ``.html`` or ``.pdf``, resp., added.

  This is more intuitive than replacing the extension.  However, as in
  the previous example, sometimes it may be unwanted, and esp. for
  images in HTML, it's ambiguous which extension to choose.  (This
  ambiguity could only be resolved with a directive (obstrusive, point
  1) or a setting (setting-dependent, point 3).

  Choosing the right extension by checking for file existence (as
  Engelbert proposed) is a bad idea, because it makes document
  processing context dependent, so that it's impossible to process the
  document when the documents or images which the document is referring
  to are unavailable.

* ``.. _link: foo.*`` is pretty much like the previous one.

  The differences are that it's clear and obvious that extension
  replacement is desired, and that real asterisks in file names will
  have to be escaped.

  The ambiguity problem remains.

------------------------------------------------------------------------

All these ideas have significant disadvantages.

Nevertheless I suggest using automatic replacement of the filename
extension (i.e. the second idea in the list).  I think it isn't needed
so desperately for links (and with links there might be more
difficulties), so I suggest implementing **optional automatic
filename-extension-replacement for images** in the LaTeX writer.  I
don't know of any other format that could need different extensions, so
I think it's best to implement it in the writer.

The LaTeX-writer could have a new setting,
e.g. replace_imagename_extensions, which replaces all extensions in the
filenames of images by .eps.  (This shouldn't be activated by default,
because when using pdflatex, it isn't needed.)

> How to indicate which paths may have their extensions substituted,
> and/or which may not?

Not.  Or maybe automatically leave out anything containing '://' from
the substitution process.

> How to indicate special cases?

I don't think it's necessary.  Keep it simple -- Docutils isn't a macro
language.

-- 
http://www.ososo.de/