Figures in APT require extension

[Trevor Harmon]

I'm running into bug DOXIA-99:

   http://jira.codehaus.org/browse/DOXIA-99

If I don't specify an extension, then the HTML is generated without  
one, causing the image to fail to load.

If I do specify an extension, then the HTML has the extension, and the  
image loads properly. However, this prevents the image format auto-
selection feature from working described in the APT format  
documentation.

The issue was resolved as "Won't Fix" but I don't understand why. I'm  
guessing that the APT format documentation is now incorrect.  
Specifically, this line is wrong: "An APT processor will first try to  
load /home/joe/docs/mylogo.eps . When the desired format is not found,  
a APT processor tries to convert one of the existing formats."

Should I file an issue to have the documentation corrected?

Trevor

[Lukas Theussl-4]

It's already documented in SVN [1], we just can't publish the site until 1.1 is
released.

-Lukas

[1]
https://svn.apache.org/repos/asf/maven/doxia/site/src/site/apt/references/doxia-apt.apt


Trevor Harmon wrote:

> I'm running into bug DOXIA-99:
>
>   http://jira.codehaus.org/browse/DOXIA-99
>
> If I don't specify an extension, then the HTML is generated without  
> one, causing the image to fail to load.
>
> If I do specify an extension, then the HTML has the extension, and the  
> image loads properly. However, this prevents the image format auto-
> selection feature from working described in the APT format  documentation.
>
> The issue was resolved as "Won't Fix" but I don't understand why. I'm  
> guessing that the APT format documentation is now incorrect.  
> Specifically, this line is wrong: "An APT processor will first try to  
> load /home/joe/docs/mylogo.eps . When the desired format is not found,  
> a APT processor tries to convert one of the existing formats."
>
> Should I file an issue to have the documentation corrected?
>
> Trevor
>
>

[Trevor Harmon]

Okay, so Doxia now requires figure references to specify an extension.  
Is there a particular reason why this change was necessary?

I really like the old way because it allowed me to have two versions  
of the same figure, one PNG and one PDF, that would be selected  
automatically depending on the output format. Now I have to force  
everything to be PNG.

Trevor

On Jan 13, 2009, at 5:14 AM, Lukas Theussl wrote:

>
> It's already documented in SVN [1], we just can't publish the site  
> until 1.1 is released.
>
> -Lukas
>
> [1] https://svn.apache.org/repos/asf/maven/doxia/site/src/site/apt/references/doxia-apt.apt
>
>
> Trevor Harmon wrote:
>> I'm running into bug DOXIA-99:
>>  http://jira.codehaus.org/browse/DOXIA-99
>> If I don't specify an extension, then the HTML is generated  
>> without  one, causing the image to fail to load.
>> If I do specify an extension, then the HTML has the extension, and  
>> the  image loads properly. However, this prevents the image format  
>> auto- selection feature from working described in the APT format  
>> documentation.
>> The issue was resolved as "Won't Fix" but I don't understand why.  
>> I'm  guessing that the APT format documentation is now incorrect.  
>> Specifically, this line is wrong: "An APT processor will first try  
>> to  load /home/joe/docs/mylogo.eps . When the desired format is not  
>> found,  a APT processor tries to convert one of the existing  
>> formats."
>> Should I file an issue to have the documentation corrected?
>> Trevor

[Lukas Theussl-4]

This is not really a change as it was always de facto like that (at least for
apt). The reason is basically given in the discussion of DOXIA-99. Figures are
just links, and so should be valid and unique in a source document. Imagine for
some obscure reason you would want to use doxia to transform a document from xdoc
to latex to xhtml and back to xdoc. The final result should be identical to the
original, which would not be possible if doxia changed some input on the way.

Another argument is that the automatic selection of format only works if the
output format supports only one figure extension (eg latex only supports eps), but
  how do you choose the image in html, where you can have jpg, png, gif... ?

Doxia-1.1 outputs a WARNING level message if figure extensions are encountered
that are not compatible with the current sink. For cases like latex I could
imagine to change that since anything except eps doesn't make sense and we don't
have a latex parser anyway. But this is on the Sink-level, you would still have to
specify the extension in your apt source.

-Lukas


Trevor Harmon wrote:

> Okay, so Doxia now requires figure references to specify an extension.  
> Is there a particular reason why this change was necessary?
>
> I really like the old way because it allowed me to have two versions  of
> the same figure, one PNG and one PDF, that would be selected  
> automatically depending on the output format. Now I have to force  
> everything to be PNG.
>
> Trevor
>
> On Jan 13, 2009, at 5:14 AM, Lukas Theussl wrote:
>
>>
>> It's already documented in SVN [1], we just can't publish the site  
>> until 1.1 is released.
>>
>> -Lukas
>>
>> [1]
>> https://svn.apache.org/repos/asf/maven/doxia/site/src/site/apt/references/doxia-apt.apt 
>>
>>
>>
>> Trevor Harmon wrote:
>>
>>> I'm running into bug DOXIA-99:
>>>  http://jira.codehaus.org/browse/DOXIA-99
>>> If I don't specify an extension, then the HTML is generated  without  
>>> one, causing the image to fail to load.
>>> If I do specify an extension, then the HTML has the extension, and  
>>> the  image loads properly. However, this prevents the image format  
>>> auto- selection feature from working described in the APT format  
>>> documentation.
>>> The issue was resolved as "Won't Fix" but I don't understand why.  
>>> I'm  guessing that the APT format documentation is now incorrect.  
>>> Specifically, this line is wrong: "An APT processor will first try  
>>> to  load /home/joe/docs/mylogo.eps . When the desired format is not  
>>> found,  a APT processor tries to convert one of the existing  formats."
>>> Should I file an issue to have the documentation corrected?
>>> Trevor
>
>
>

[Trevor Harmon]

On Jan 21, 2009, at 11:34 AM, Lukas Theussl wrote:

> Imagine for some obscure reason you would want to use doxia to  
> transform a document from xdoc to latex to xhtml and back to xdoc.  
> The final result should be identical to the original, which would  
> not be possible if doxia changed some input on the way.

I have trouble imaging a situation where I'd need to convert a file to  
the format it's already in. Even if there were, it's virtually  
impossible to guarantee that all information will be preserved in a  
round-trip conversion. There will always be a case where something  
simply can't be expressed the same way (or at all) in some other format.

> Another argument is that the automatic selection of format only  
> works if the output format supports only one figure extension (eg  
> latex only supports eps), but  how do you choose the image in html,  
> where you can have jpg, png, gif... ?

The automatic selection is normally used to choose between a raster  
format and a vector format, and JPG, PNG, and GIF are all raster, so  
the author would only create one of them.

The issues you raise are valid, but in practice, I don't think they're  
a big concern, at least not compared to the problem of choosing the  
appropriate raster vs. vector figures to match the output format,  
which apparently is impossible now.

Trevor