Linking to docs.sun.com content demystified

Sometimes it is useful to link to content on docs.sun.com, and in large part you can do so without much worry that the link will go away at some point. Almost everything that has ever been published to docs.sun.com is still there, at the same URL that it ever was. However, there are a few things to be aware of when linking, especially to specific content pages inside of books. It is helpful to recognize the type of content being linked to, and the origin of the actual link target identifier.

Types of Content

As stated elsewhere, docs.sun.com has three types of content, even though all of them are linked to from navigational pages that appear to be plain HTML. The three types of content are XML (rendered as HTML), Native HTML, and PDF files pointed to by HTML. Linking to the latter two is as straightforward as any other website with which you might be familiar. Just copy the URL of the page you are interested in, and off you go. You can recognize these types of pages by the format of the URL, which follow the following formats:

Format   Example URL
HTMLhttp://docs.sun.com/source/<identifier>/<filename>...
 A typical HTML document URL always contains the "source" path element. It will remain stable for as long as the document exists and is not modified in such a way as to eliminate the file or anchor referenced.
 
PDFhttp://docs.sun.com/app/docs/doc/<identifier>
 A PDF file "pointer page" URL is not easily distinguished by its format, since XML document TOC pages have the same format, but the actual page contains a prominent PDF icon and instructions for downloading the PDF file. These PDF file "pointer pages" will always remain available at that URL unless the document referenced is deleted, when it is then replaced with a similar page that indicates the date of the deletion. It is preferable to link to these "pointer pages" whenever possible, as opposed to the PDF file itself (usually hosted on dlc.sun.com), since the locations on the download server are not guaranteed to be constant.

The third type of content is XML (styled as HTML), and this is where things can get a little complicated. XML content is generated as HTML on an "as needed" basis by the application, and some forms of the URLs are not stable and should not be used as link targets. In general these unstable "autogenerated" links can be identified by the last element in the path, a nine character string beginning with the number '6' sometimes also preceded by the word "auto". All the other element IDs are actual authored anchor IDs in the content, and they will remain stable and available for the life of that book. Since many authored anchor IDs are rather cryptic the following examples might be of help:

Example URLStable?
http://docs.sun.com/app/docs/<identifier>YES
This is a URL for a book TOC page. Note that this is identical in form to the PDF "pointer page" URLs. They behave in an identical fashion when used as link targets. 
 
http://docs.sun.com/app/docs/<identifier>/chp1-intro?a=viewYES
http://docs.sun.com/app/docs/<identifier>/abprk?a=viewYES
Both if these types of links to XML content are stable, since they both are referring to authored anchor element IDs, even though they are not terribly similar in appearance. Neither has an element ID which is 9 characters long and begins with a '6' nor is prefaced with the word 'auto'. Also note that the "a=view" parameter is another indication of an XML (styled as HTML) page. This is also true of the "a=browse" parameter, which appears when browsing a book TOC. 
 
http://docs.sun.com/app/docs/<identifier>/6jbj505fl?a=viewNO
http://docs.sun.com/app/docs/<identifier>/auto6mgv7i354?a=viewNO
Linking directly to either of these types of links to XML content should be avoided. This section of the book has no authored element IDs, and so when the book was published autogenerated IDs where created for them. However if this book is ever updated these generated IDs are almost guaranteed to change. If the content you need to link to is only available through such a URL form, it is better to link to the book TOC page and give explicit instructions to the reader, such as "See Chapter X of the <link to TOC> book". 

Please Note

All content on docs.sun.com is under the indicated copyrights and remains the intellectual property of the copyright holders. As such, Sun Microsystems, Inc. reserves the right to remove content from docs.sun.com, even so called "stable" links, whenever necessary, without consideration of any third party that might be linking to it.

Comments:

Post a Comment:
Comments are closed for this entry.
About

This is the blog for Sun Microsystems on-line documentation site, http://docs.sun.com.

Search

Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today