<Swing Dev> RFR: JDK-8235818: Inline information from broken external links in java.desktop

Prasanta Sadhukhan prasanta.sadhukhan at oracle.com
Thu Dec 12 10:40:06 UTC 2019 

It seems jdk/jdk has introduced stricter check for img tag to have "alt" 
subtag.

Modified webrev to add alt subtag to img tag like this

201  * <p style="text-align:center"><img src="doc-files/plain1.gif"
  202  * alt="The preceding text describes this graphic.">

No visible change to the spec for this modification. mach5 is green

Bug: https://bugs.openjdk.java.net/browse/JDK-8235818

webrev: http://cr.openjdk.java.net/~psadhukhan/8235818/webrev.0/

Regards

Prasanta

On 12-Dec-19 12:06 AM, Phil Race wrote:
> +1
>
> -phil.
>
> On 12/10/19 2:12 AM, Prasanta Sadhukhan wrote:
>>
>> Modified webrev: http://cr.openjdk.java.net/~psadhukhan/8227607/webrev.3/
>>
>> with updated spec 
>> http://cr.openjdk.java.net/~psadhukhan/8227607/docs1/api/java.desktop/javax/swing/text/Document.html
>>
>> Regards
>>
>> Prasanta
>>
>> On 09-Dec-19 11:00 PM, Philip Race wrote:
>>> >
>>>
>>>   * ||
>>>     <http://cr.openjdk.java.net/%7Epsadhukhan/8227607/docs/api/java.desktop/javax/swing/text/Document.html#putProperty%28java.lang.Object,java.lang.Object%29>
>>>
>>>
>>> For more information on the |Document| class, see The Swing 
>>> Connection 
>>> <http://www.oracle.com/technetwork/java/javase/tech/articles-jsp-139072.html> 
>>>
>>>
>>>
>>> This link above  seems to be obsolete as well. I think it should 
>>> just be removed
>>>
>>> > If an element is a a leaf,isLeaf() returns true.
>>>
>>> add a space after the comma.
>>>
>>> Also can we wrap all  - or at least the ones that make sense -  API 
>>> references in {@code ... }  ?
>>>
>>> Method calls for sure.
>>>
>>> interrface -> interface.
>>>
>>> -phil.
>>>
>>> On 12/9/19, 3:16 AM, Prasanta Sadhukhan wrote:
>>>>
>>>> Modified version with new subtitle ""Overview and Programming Tips" 
>>>> and graphical_schema
>>>>
>>>> http://cr.openjdk.java.net/~psadhukhan/8227607/webrev.2/
>>>>
>>>> spec change will look like 
>>>> http://cr.openjdk.java.net/~psadhukhan/8227607/docs/api/java.desktop/javax/swing/text/Document.html
>>>>
>>>> Regards
>>>> Prasanta
>>>> On 08-Dec-19 1:47 AM, Philip Race wrote:
>>>>> I got very confused as to whether there was even an updated 
>>>>> version here.
>>>>> This conversation became too complex for the inline diff.
>>>>> I think that it would be best to first generate a webrev put it on cr.
>>>>>
>>>>>
>>>>> I do think we need to have a subtitle that prefaces this new 
>>>>> content rather
>>>>> than just appending it to "Properties" ..
>>>>>
>>>>> I suggest "Overview and Programming Tips" which makes it clearer 
>>>>> it is not (so much) specification as developer guide.
>>>>>
>>>>> > Swing has a interesting interface, called the _|Element| 
>>>>> <http://cr.openjdk.java.net/%7Epsadhukhan/docs/api/java.desktop/javax/swing/text/Element.html>_,
>>>>>
>>>>> I do think this needs rephrasing.
>>>>>
>>>>> "Element is an important interface used in constructing a Document.
>>>>> It has the power ...."
>>>>>
>>>>> And each time it says "In Swing" I think, why does it bother 
>>>>> saying that ...
>>>>> confusion with an SGML Element ?
>>>>> Maybe it would read better written as "In the Swing text API's 
>>>>> document model"
>>>>>
>>>>> -phil.
>>>>>
>>>>> On 12/6/19, 7:22 PM, Prasanta Sadhukhan wrote:
>>>>>> Anything more needs to be added?!!! Can it be committed?
>>>>>>
>>>>>> On 06-Dec-19 9:49 AM, Prasanta Sadhukhan wrote:
>>>>>>> I guess I already shared... 
>>>>>>> http://cr.openjdk.java.net/~psadhukhan/docs/api/java.desktop/javax/swing/text/Document.html
>>>>>>>
>>>>>>> Regards
>>>>>>>
>>>>>>> Prasanta
>>>>>>>
>>>>>>> On 06-Dec-19 4:44 AM, Sergey Bylokhov wrote:
>>>>>>>> Hi, Prasanta.
>>>>>>>>
>>>>>>>> Can you please share the final generated JavaDoc, it is hard to 
>>>>>>>> read the diff below.
>>>>>>>>
>>>>>>>> On 12/4/19 10:09 am, Prasanta Sadhukhan wrote:
>>>>>>>>> Inlined information from element_interface page into Document 
>>>>>>>>> class <spec will look like 
>>>>>>>>> http://cr.openjdk.java.net/~psadhukhan/docs/api/java.desktop/javax/swing/text/Document.html]
>>>>>>>>>
>>>>>>>>> /diff -r 53eff6c5da11 
>>>>>>>>> src/java.desktop/share/classes/javax/swing/Timer.java/
>>>>>>>>>
>>>>>>>>> --- a/src/java.desktop/share/classes/javax/swing/Timer.java 
>>>>>>>>> Sun Oct 06 21:42:50 2019 -0700
>>>>>>>>> +++ b/src/java.desktop/share/classes/javax/swing/Timer.java 
>>>>>>>>> Wed Dec 04 22:07:48 2019 +0530
>>>>>>>>> @@ -124,13 +124,6 @@
>>>>>>>>>    * <a 
>>>>>>>>> href="https://docs.oracle.com/javase/tutorial/uiswing/misc/timer.html" 
>>>>>>>>>
>>>>>>>>>    * target = "_top">How to Use Timers</a>,
>>>>>>>>>    * a section in <em>The Java Tutorial.</em>
>>>>>>>>> *- * For more examples and help in choosing between**
>>>>>>>>> **- * this <code>Timer</code> class and**
>>>>>>>>> **- * <code>java.util.Timer</code>,**
>>>>>>>>> **- * see**
>>>>>>>>> **- * <a 
>>>>>>>>> href="http://java.sun.com/products/jfc/tsc/articles/timer/"**
>>>>>>>>> **- * target="_top">Using Timers in Swing Applications</a>,**
>>>>>>>>> **- * an article in <em>The Swing Connection.</em>**
>>>>>>>>> *  * <p>
>>>>>>>>>    * <strong>Warning:</strong>
>>>>>>>>>    * Serialized objects of this class will not be compatible with
>>>>>>>>>
>>>>>>>>> /diff -r 53eff6c5da11 
>>>>>>>>> src/java.desktop/share/classes/javax/swing/text/Document.java/
>>>>>>>>>
>>>>>>>>> --- 
>>>>>>>>> a/src/java.desktop/share/classes/javax/swing/text/Document.java 
>>>>>>>>> Sun Oct 06 21:42:50 2019 -0700
>>>>>>>>> +++ 
>>>>>>>>> b/src/java.desktop/share/classes/javax/swing/text/Document.java 
>>>>>>>>> Wed Dec 04 22:07:48 2019 +0530
>>>>>>>>> @@ -167,9 +167,38 @@
>>>>>>>>>    *
>>>>>>>>>    * <p>For more information on the <code>Document</code> 
>>>>>>>>> class, see
>>>>>>>>>    * <a 
>>>>>>>>> href="http://www.oracle.com/technetwork/java/javase/tech/articles-jsp-139072.html">The 
>>>>>>>>> Swing Connection</a>
>>>>>>>>> *- * and most particularly the article,**
>>>>>>>>> **- * <a 
>>>>>>>>> href="http://java.sun.com/products/jfc/tsc/articles/text/element_interface">**
>>>>>>>>> **- * The Element Interface</a>.**
>>>>>>>>> **+ * <p>Swing has a interesting interface, called the 
>>>>>>>>> <u>{@link javax.swing.text.Element}</u>, **
>>>>>>>>> **+ * which has the power to describe various structural parts 
>>>>>>>>> of a document, **
>>>>>>>>> **+ * such as paragraphs, lines of text, or even (in HTML 
>>>>>>>>> documents) items in lists. **
>>>>>>>>> **+ * Conceptually, the Element interface captures some of the 
>>>>>>>>> spirit of an SGML document. **
>>>>>>>>> **+ * So if you know SGML, you may already have some 
>>>>>>>>> understanding of Swing's Element interface.**
>>>>>>>>> **+ * <p>In Swing, the interface Element defines a structural 
>>>>>>>>> piece of a Document, **
>>>>>>>>> **+ * like a paragraph, a line of text, or a list item in an 
>>>>>>>>> HTML document.**
>>>>>>>>> **+ * <p>Every Element is either a branch or a leaf. If an 
>>>>>>>>> element is a branch, **
>>>>>>>>> **+ * the isLeaf() method returns false. If an element is a a 
>>>>>>>>> leaf,isLeaf() returns true.**
>>>>>>>>> **+ * <p>Branches can have any number of children. Leaves do 
>>>>>>>>> not have children. **
>>>>>>>>> **+ * To determine how many children a branch has, you can 
>>>>>>>>> call getElementCount(). **
>>>>>>>>> **+ * To determine the parent of an Element, you can call 
>>>>>>>>> getParentElement(). **
>>>>>>>>> **+ * Root elements don't have parents, so calling 
>>>>>>>>> getParentElement() on a root returns null.**
>>>>>>>>> **+ * <p>An Element represents a specific region in a Document 
>>>>>>>>> that begins with startOffset **
>>>>>>>>> **+ * and ends just before endOffset. **
>>>>>>>>> **+ * The start offset of a branch Element is usually the 
>>>>>>>>> start offset of its first child. **
>>>>>>>>> **+ * Similarly, the end offset of a branch Element is usually 
>>>>>>>>> the end offset of its last child.**
>>>>>>>>> **+ * <p>Every Element is associated with an AttributeSet that 
>>>>>>>>> you can access by calling getAttributes(). **
>>>>>>>>> **+ * In an Element, and AttributeSet is essentially a set of 
>>>>>>>>> key/value pairs. **
>>>>>>>>> **+ * These pairs are generally used for markup -- such as 
>>>>>>>>> determining the Element's **
>>>>>>>>> *
>>>>>>>>>
>>>>>>>>> *+ * foreground color, font size, and so on. But it is up to 
>>>>>>>>> the model, and the developer, **
>>>>>>>>> **+ * to determine what is stored in the AttributeSet.**
>>>>>>>>> **+ * <p>You can obtain the root Element (or Elements) of a 
>>>>>>>>> Document by calling the **
>>>>>>>>> **+ * methods getDefaultRootElement() and getRootElements(), 
>>>>>>>>> which are defined in the Document interface.**
>>>>>>>>> **+ * <p>The Document interrface is responsible for 
>>>>>>>>> translating a linear view of the **
>>>>>>>>> **+ * characters into Element operations. It is up to each 
>>>>>>>>> Document implementation **
>>>>>>>>> **+ * to define what the Element structure is.**
>>>>>>>>> **+ * <p>It is recommended to look into {@link 
>>>>>>>>> javax.swing.text.EditorKit} and **
>>>>>>>>> **+ * {@link javax.swing.text.View}.**
>>>>>>>>> **+ * View is responsible for rendering a particular Element, 
>>>>>>>>> and **
>>>>>>>>> **+ * EditorKit is responsible for a ViewFactory that is able 
>>>>>>>>> to decide what **
>>>>>>>>> **+ * View should be created based on an Element.*
>>>>>>>>>
>>>>>>>>> Regards
>>>>>>>>>
>>>>>>>>> Prasanta
>>>>>>>>>
>>>>>>>>> On 04-Dec-19 10:45 AM, Sergey Bylokhov wrote:
>>>>>>>>>> On 12/3/19 9:08 pm, Prasanta Sadhukhan wrote:
>>>>>>>>>>> Hi Sergey,
>>>>>>>>>>>
>>>>>>>>>>> I could not find the page for element_interface itself so 
>>>>>>>>>>> how to get the information from there?
>>>>>>>>>>
>>>>>>>>>> I guess it is the same as you posted before:
>>>>>>>>>> https://web.archive.org/web/20120418045506/http://java.sun.com/products/jfc/tsc/articles/text/element_interface/ 
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> Regards
>>>>>>>>>>>
>>>>>>>>>>> Prasanta
>>>>>>>>>>>
>>>>>>>>>>> On 04-Dec-19 7:31 AM, Sergey Bylokhov wrote:
>>>>>>>>>>>> Hi, Prasanta.
>>>>>>>>>>>> Probably we can inline some information from the 
>>>>>>>>>>>> element_interface.html to the JavaDoc itself? The JavaDoc 
>>>>>>>>>>>> already has some similar schemes.
>>>>>>>>>>>>
>>>>>>>>>>>> On 12/2/19 2:37 am, Prasanta Sadhukhan wrote:
>>>>>>>>>>>>> Hi All,
>>>>>>>>>>>>>
>>>>>>>>>>>>> Please review a doc-fix for removing some dead links from 
>>>>>>>>>>>>> the specifications. These links were part of java.sun.com 
>>>>>>>>>>>>> but has not been migrated to docs.oracle.com so it's 
>>>>>>>>>>>>> better to remove them
>>>>>>>>>>>>>
>>>>>>>>>>>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8227607
>>>>>>>>>>>>>
>>>>>>>>>>>>> diff -r 7637e77c4c8a 
>>>>>>>>>>>>> src/java.desktop/share/classes/javax/swing/Timer.java
>>>>>>>>>>>>> --- 
>>>>>>>>>>>>> a/src/java.desktop/share/classes/javax/swing/Timer.java 
>>>>>>>>>>>>> Mon Dec 02 11:58:14 2019 +0530
>>>>>>>>>>>>> +++ 
>>>>>>>>>>>>> b/src/java.desktop/share/classes/javax/swing/Timer.java 
>>>>>>>>>>>>> Mon Dec 02 16:02:08 2019 +0530
>>>>>>>>>>>>> @@ -124,13 +124,6 @@
>>>>>>>>>>>>>    * <a 
>>>>>>>>>>>>> href="https://docs.oracle.com/javase/tutorial/uiswing/misc/timer.html" 
>>>>>>>>>>>>>
>>>>>>>>>>>>>    * target = "_top">How to Use Timers</a>,
>>>>>>>>>>>>>    * a section in <em>The Java Tutorial.</em>
>>>>>>>>>>>>> *- * For more examples and help in choosing between**
>>>>>>>>>>>>> **- * this <code>Timer</code> class and**
>>>>>>>>>>>>> **- * <code>java.util.Timer</code>,**
>>>>>>>>>>>>> **- * see**
>>>>>>>>>>>>> **- * <a 
>>>>>>>>>>>>> href="http://java.sun.com/products/jfc/tsc/articles/timer/"**
>>>>>>>>>>>>> **- * target="_top">Using Timers in Swing Applications</a>,**
>>>>>>>>>>>>> **- * an article in <em>The Swing Connection.</em>*
>>>>>>>>>>>>>    * <p>
>>>>>>>>>>>>>    * <strong>Warning:</strong>
>>>>>>>>>>>>>    * Serialized objects of this class will not be 
>>>>>>>>>>>>> compatible with
>>>>>>>>>>>>> diff -r 7637e77c4c8a 
>>>>>>>>>>>>> src/java.desktop/share/classes/javax/swing/text/Document.java
>>>>>>>>>>>>> --- 
>>>>>>>>>>>>> a/src/java.desktop/share/classes/javax/swing/text/Document.java 
>>>>>>>>>>>>> Mon Dec 02 11:58:14 2019 +0530
>>>>>>>>>>>>> +++ 
>>>>>>>>>>>>> b/src/java.desktop/share/classes/javax/swing/text/Document.java 
>>>>>>>>>>>>> Mon Dec 02 16:02:08 2019 +0530
>>>>>>>>>>>>> @@ -167,9 +167,6 @@
>>>>>>>>>>>>>    *
>>>>>>>>>>>>>    * <p>For more information on the <code>Document</code> 
>>>>>>>>>>>>> class, see
>>>>>>>>>>>>>    * <a 
>>>>>>>>>>>>> href="http://www.oracle.com/technetwork/java/javase/tech/articles-jsp-139072.html">The 
>>>>>>>>>>>>> Swing Connection</a>
>>>>>>>>>>>>> *- * and most particularly the article,**
>>>>>>>>>>>>> **- * <a 
>>>>>>>>>>>>> href="http://java.sun.com/products/jfc/tsc/articles/text/element_interface">**
>>>>>>>>>>>>> **- * The Element Interface</a>.*
>>>>>>>>>>>>>    *
>>>>>>>>>>>>>    * @author  Timothy Prinzing
>>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>> Regards
>>>>>>>>>>>>>
>>>>>>>>>>>>> Prasanta
>>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>
>>>>>>>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/swing-dev/attachments/20191212/41f3a58d/attachment-0001.htm>

More information about the swing-dev mailing list