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

[Rick Hillegas]

Thanks for that advice, Jon.

On 1/15/19 4:22 PM, Jonathan Gibbons wrote:
> 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
>>>
>>
>
>