[Docutils-users] Re: Automatic choosing of filename extension

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

Aahz wrote:

> Felix Wiemann wrote:
>
>> * ``.. _link:: foo.html`` with ``.html`` automatically getting replaced
>>   by ``.pdf`` if LaTeX source is generated -- this is somewhat
>>   unintuitive (point 2).
>
> -1
>
> I'm in favor of .*

I see, I'll have to elaborate more detailedly why I do not like .* at
all.

1. First of all, we need to examine when extension replacement is needed
   at all:

   1. Images in LaTeX when using standard latex (not pdflatex).
   
   2. Linking to other text documents.

      As the only format whose linking capability is frequently being
      used is HTML, replacement of extensions in links to text documents
      is bound to be needed rather seldom.

   So obviously, the feature is not needed *that* urgently.  It would
   only cover few cases.

2. The next point to examine is the cost of the .* syntax:

   1. There is a lot of complexity because of ambiguous file extensions.

      Presume we have a document which contains the following
      reference::
      
          .. image:: someimage.*

      When this document is being processed to HTML by Docutils in a
      foreign environment where the image files are not available, there
      is no reliable way of determining which extension to use
      (i.e. PNG, JPG, JPEG or GIF).

      Either we live with it, which means that in some situations it is
      simply impossible to reasonably process a document, or we add even
      more syntax to tell Docutils which extension to use, which again
      adds complexity.

   2. At the time we introduce the .* syntax, many people will start
      using it, because 'it doesn't hurt and at some time it might come
      in handy, even if I don't need it right now.'

      This means that any further change on the syntax will cause *many*
      incompatibilities and broken documents.  And there will be
      changes, because of the complexity I pointed out above.  There
      will even be design changes, because I don't think we are able to
      properly design that feature at the first catch.

Thus, introducing the .* syntax would cause very much trouble just in
order to fix a problem which appears only sporadically.

I'd even prefer leaving the extension problem unresolved to adding a
.*-syntax.


In case it's really needed, I'd suggest simply adding a quick hack which
replaces existing extensions.  For example, for LaTeX documents, one
could add a switch which makes the LaTeX writer replace any extension in
image filenames by 'eps'.  That way, there is no ambiguity (for LaTeX,
we only have EPS, whereas for HTML there are PNG, JPEG and GIF), we
avoid extending the reST syntax and we avoid introducing a feature which
many people might rely upon.

Furthermore, those who need more sophisticated filename extension
tweaking can simply use regular expressions, which isn't too difficult
due to the determinability of the writers.  So there is no need to add a
complex filename-extension-handling feature to Docutils.

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