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

Prasanta Sadhukhan prasanta.sadhukhan at oracle.com
Tue Dec 10 10:12:57 UTC 2019 

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/20191210/2dd6ecf8/attachment-0001.htm>

More information about the swing-dev mailing list