best practice for including images in the javadoc headers of module descriptors

[Jonathan Gibbons]

Rick,

I found your Derby documentation online with the module diagrams. Very nice!

I don't know how much you have looked at how we insert the module 
diagrams into the JDK API documentation, but we do it with a custom 
taglet, which gives us the flexibility to vary the output. For example, 
if the images are not available, we don't generate references to them. 
Using that sort of technique would be another way to address your 
original question.

-- Jon


On 01/15/2019 04:10 PM, Jonathan Gibbons wrote:
> Rick,
>
> There is, temporarily, an option to javadoc called 
> --no-module-directories, which in JDK 11 will give you the same 
> directory layout as in JDK 9.
>
> However, the layout in JDK 9 is bad insofar as like-named packages in 
> different modules will overwrite each other, and so, in time, the 
> layout in JDK 11, with an extra level of directory for the module 
> name, will be the only supported layout.
>
> So, to answer your question ...
>
> ... short term answer, use --no-module-directories
>
> ... long term answer, put content for a module in the module-specific 
> directory ... or at least, create references appropriate to that layout
>
>
> Separately, FYI. I notice you are using the "border" attribute in your 
> <img> tag, which probably implies you are using HTML 4.  If you are 
> using the -html4 option, you should be getting a warning that support 
> for HTML4 will be going away at some point. If you are not using the 
> -html4 option, and are using the default (-html5), then you're 
> probably generating bad HTML which may not pass a conformance checker 
> and/or may not display correctly in all browsers.
>
> -- Jon
>
>
> On 01/12/2019 09:23 AM, Rick Hillegas wrote:
>>
>> I would appreciate your advice about the best practice for handling 
>> the following problem.
>>
>> The structure of the generated javadoc tree appears to have changed 
>> substantially between Java 9 and Java 11. I noticed this because my 
>> module descriptors include <img> tags, which pull corresponding 
>> module diagrams into the module overview pages generated by javadoc. 
>> The <img> tags have src attributes with relative file references. 
>> Here, for instance, is the <img> tag from the javadoc header in the 
>> Derby engine's module descriptor:
>>
>>   * <div style="text-align:center;">
>>   *   <img
>>   *     src="resources/engine.svg"
>>   *     alt="module diagram for org.apache.derby.engine"
>>   *     border="2"
>>   *   />
>>   * </div>
>>
>>
>> When I build the javadoc using Java 9, browsers correctly display the 
>> module diagrams because the module overview pages are in the same 
>> directory as the top-level index.html. However, when I build the 
>> javadoc using Java 11, the module overview pages live in 
>> subdirectories of that top-level root--in this case, in the 
>> org.apache.derby.engine subdirectory.
>>
>> What is the best practice for including images in module descriptor 
>> headers so that the resulting javadoc displays correctly regardless 
>> of whether one builds it using JDK 9 or JDK 11?
>>
>> Thanks,
>> -Rick
>>
>