<Swing Dev> [14] RFR JDK-8227607: Broken external links in java.desktop

Prasanta Sadhukhan prasanta.sadhukhan at oracle.com
Mon Dec 9 11:16:11 UTC 2019 

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/20191209/acb1ee4e/attachment-0001.htm>

More information about the swing-dev mailing list