<Swing Dev> [14] RFR JDK-8227607: Broken external links in java.desktop
Philip Race
philip.race at oracle.com
Sat Dec 7 20:17:08 UTC 2019
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/20191207/c295d746/attachment.htm>
More information about the swing-dev
mailing list