Please review: JDK-8178725: provide way to link to external documentation

[Roger Riggs]

Hi,

An idea that might make it more flexible would be if the settable 
property used as the link used
one of the familiar formatting substitution mechanisms so the id can be
inserted in the link wherever it is needed.   For example, the 
PrintStream formatting like %s.
Alternatively, the {0} form of MessageFormat might clash less with the 
URL encoding syntax.

$.02, Roger


On 4/19/2017 4:47 PM, Kumar Srinivasan wrote:
>
> On 4/19/2017 1:37 PM, David Holmes wrote:
>> On 20/04/2017 3:50 AM, Kumar Srinivasan wrote:
>>>
>>> We could potentially make the default URL to be "some" cgi url,
>>> and have the build system specify the  URL all the time, in our
>>> case it would be the Oracle documentation URL.
>>>
>>> Would this be an acceptable approach ?
>>
>> I'm not sure what you mean. I have a hard time seeing how a simple 
>> identifier (that will be fixed in the file using the taglet) can be 
>> attached to an arbitrary URL to yield a valid result. As Magnus said, 
>> being able to change the URL is good, but it still requires the same 
>> "kind" of URL where the identifier is used as a key.
>>
>> Imagine you have all the documentation locally on your machine then 
>> try to figure out how you could link to other local documentation 
>> using this scheme.
>
>
> Ok I see, I am going to defer this to Jon Gibbons.
>
> Kumar
>
>>
>> David
>>
>>> Kumar
>>>
>>>> On 19/04/2017 9:26 PM, Magnus Ihse Bursie wrote:
>>>>> On 2017-04-18 19:44, Kumar Srinivasan wrote:
>>>>>> Hello,
>>>>>>
>>>>>> As explained in the JBS issue [1], this new taglet enables API
>>>>>> documents
>>>>>> to contain the extLink tag to link external sources.
>>>>>>
>>>>>> Please review the webrev [2].
>>>>> Changes looks good.
>>>>>
>>>>> Just a reflection: This is heavily biased to Oracle documentation. 
>>>>> Even
>>>>> if it's possible to override the URL via a system property, it 
>>>>> assumes
>>>>> the Oracle URL format and id name. Just wondering a bit how that fits
>>>>> with the OpenJDK philosophy.
>>>>
>>>> I have to agree, this is not at all general purpose but totally Oracle
>>>> documentation centric.
>>>>
>>>> David
>>>> -----
>>>>
>>>>
>>>>> /Magnus
>>>>>
>>>>>>
>>>>>> Thanks
>>>>>> Kumar
>>>>>>
>>>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8178725
>>>>>> [2] http://cr.openjdk.java.net/~ksrini/8178725/webrev.00/
>>>>>
>>>
>