[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Broken links for repair in the CMIS errata document
Tangential/orthogonal to the notes of Patrick [1a]
on link errors in the CMIS Version 1.0 OASIS Standard,
for which an Approved Errata is being developed [2a]:
If this is an opportunity to fix this OASIS Standard
by eliminating non-substantive errors, it would be a
great time IMO to fix the broken links. I identified
over fifty (50) link errors in the CMIS spec before it
was ratified, and as far as I know, they were never
repaired. These errors, or almost all of them, are
in the Authoritative editable source, from which PDF
and HTML were generated.
1. In November 2009 I pointed out some 31 errors just
with the links for HTTP scheme namespaces names
identified by URIs (all 404) [3a]
2. In April 2010, I again reported the link errors, in
detail, but no action was taken to repair the document [4a]
3. I think an OASIS Standard deserves to be relatively
free of link errors, even if one or two are almost
avoidable (link breakage between check-time and
publication)
4. The TC Handbook also includes link-checking in the
checklist of items that will be scanned for quality:
"Hypertext Links
Any references to information resources using HTTP
scheme URIs (http:// or https://) must be active
hypertext links: a reader with Internet connectivity
should be able to click on the link and retrieve
the content stored at that location. Hypertext links
must dereference to the target location specified
in the prose text - that is, a reader with internet
connectivity should be able to to click on the link
and retrieve the content expected. The document's
Table of Contents (TOC) must support active hypertext
links to the named sections and subsections."
http://docs.oasis-open.org/TChandbook/Reference/WPQualityChecklist.html
So, without further argumentation or evidence, I'll repeat
my concern about this, and add my request that the TC
make the repairs. I am willing to do more to identify
the 50+ link errors, by line number (with the action to
be taken for repair), if that would help.
Kindest regards and best wishes,
- Robin
[1a] http://lists.oasis-open.org/archives/cmis-comment/201106/msg00002.html
http://lists.oasis-open.org/archives/cmis-comment/201106/msg00000.html
[2a] http://lists.oasis-open.org/archives/tc-announce/201106/msg00002.html
http://docs.oasis-open.org/cmis/CMIS/v1.0/errata-01/csprd01/cmis-spec-v1.0-errata-01-csprd01-complete.html
[3a] 5 Nov 2009
http://lists.oasis-open.org/archives/cmis-comment/200911/msg00000.html
test:
$ grep -c 200901 cmis-spec-v1.0.html
31
Actually, this appears not to be a root HTML problem, but a defect in
the editable source (.doc) from which HTML and PDF were apparently
generated.
[4a] http://lists.oasis-open.org/archives/cmis/201004/msg00001.html
http://lists.oasis-open.org/archives/cmis/201004/msg00003.html
Subject: Link errors in latest CMIS 1.0 specification (CS 01)
* From: Robin Cover <robin@oasis-open.org>
* To: CMIS TC Discussion List <cmis@lists.oasis-open.org>
* Date: Mon, 5 Apr 2010 11:30:11 -0400 (EDT)
Congratulations to members of the CMIS TC for a milestone
publication of CS 01. To judge from the number of prototype
implementations and references in the trade press, this CMIS
V1.0 Standard will be very popular (in relative terms). It
promises to be a very significant and widely read Standard.
For that reason, it's disconcerting to see a large number of
link errors in the published CS 01 version. I document some
of these link errors below. After examining this report (and noting
similar errors I've not reported): does the TC want to send
*this* version up for OASIS member ballot -- with these errors?
The 30(some) errors for link relation identifiers were
already reported to the TC in November 2009 but have not
been fixed.
Fixing the link errors would require (I think) multiple dozens
of textual edits to the specification. I'm not sure that
level of editing is allowed at CS stage once the document
has been submitted. It might depend upon the interpretation
of these assertions in the TC Process [#3]:
* "No part"
* "changed"
* "altered"
* "in any way"
"No part of the submission may be changed or altered
in any way after being submitted to the TC Administrator,.."
I see two general classes of link errors in CS 01:
* some 30 broken links involving URIs for link relation identifiers (I)
* links to [inner-document] locations incorrectly formed because
they have the wrong target - destination in a putative anchor (II)
If there's a TC resolve to fix these link errors in a subsequent
CS revision, I'll be happy to proof-read the text before TC approval.
Cheers,
- Robin Cover (OASIS)
Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/who/staff.php#cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783
========= I. Links involving URIs for link relation identifiers ========
The CMIS 1.0 specification CS-01 still contains some 30 link
(Link Relation URI) errors that were reported on the CMIS TC
Comment List [cmis-comment@lists.oasis-open.org] on 5 Nov 2009
when they were spotted in CD-04.
It appears that the Comment Resolution Log document "Summary of
Public Comments and TC's Responses for CMIS Public Review,
October 23rd, 2009 - December 22nd, 2009" conflates and confuses
two separate issues:
1) incorrect link construction: links (HTTP scheme URI references)
which use the string '200901' in error for the intended '200908'
2) the early question of how best to handle the CMIS specific link
relations, viz., whether a new style of a namespace document
should be created for each of the named CMIS link relation
identifiers
These two topics are referenced in list messages copied out below,
respectively at [#1] and [#2]. In the former [#1], I identified
the 30-some URI/link errors. In the latter case [#2], I presented
a proposal for handling the CMIS link relation identifiers in a
manner analogous to HTTP scheme namespace URIs; this proposal was
later adopted by the TC, per the explanation in the Comment
Resolution log.
At the risk of being tedious and overly pedantic, here's the
problem with incorrect link construction, which encodes the
URI (substring) element '200901' in error for the intended '200908'.
All 30+ occurrences are in these URIs used for the link relation
identifiers:
http://docs.oasis-open.org/ns/cmis/link/200901/acl
http://docs.oasis-open.org/ns/cmis/link/200901/allowableactions
http://docs.oasis-open.org/ns/cmis/link/200901/changes
http://docs.oasis-open.org/ns/cmis/link/200901/foldertree
http://docs.oasis-open.org/ns/cmis/link/200901/policies
http://docs.oasis-open.org/ns/cmis/link/200901/relationships
http://docs.oasis-open.org/ns/cmis/link/200901/rootdescendants
http://docs.oasis-open.org/ns/cmis/link/200901/source
http://docs.oasis-open.org/ns/cmis/link/200901/target
The link errors occur in each of the Word (.doc) format, PDF
format, and HTML format documents. The errors appear on different
line numbers (perhaps pages) because the Word and PDF format
documents (apparently) have different numbers of pages and line
numbers.
In all three document formats, the URIs are formatted as hyperlinks,
so there is considerable risk that readers using any of the
"copy link" gestures in common software tools will select/copy and
propagate the URI (string) errors found in the link text (e.g.,
"Copy Link Location" in Adobe Acrobat Reader, "Copy Hyperlink" in
MS Word, "Copy Shortcut" / "Copy Link Location" / "Copy Link Address"
in Web browsers). Using "rightClick-copy" is faster than using the
gesture "mouseDown-drag-mouseUp-copy" so we can expect readers
to propagate the errors in the link text.
Note that these incorrect links do *not* resolve under DNS+HTTP to
anything (HTTP status code 404 Not Found), whereas the corresponding
correct URI references (each with '/200908/' for '/200901/ )
will resolve meaningfully to the namespace document at the
root ( http://docs.oasis-open.org/ns/cmis/link/200908/ ), where
these "Link Relations:" are briefly explained. Viz., these
correct URIs behave as designed when dereferenced, per the proposal
in [#2] and our common OASIS Library practice for such identifiers:
http://docs.oasis-open.org/ns/cmis/link/200908/acl
http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions
http://docs.oasis-open.org/ns/cmis/link/200908/changes
http://docs.oasis-open.org/ns/cmis/link/200908/foldertree
http://docs.oasis-open.org/ns/cmis/link/200908/policies
http://docs.oasis-open.org/ns/cmis/link/200908/relationships
http://docs.oasis-open.org/ns/cmis/link/200908/rootdescendants
http://docs.oasis-open.org/ns/cmis/link/200908/source
http://docs.oasis-open.org/ns/cmis/link/200908/target
http://docs.oasis-open.org/ns/cmis/link/200908/typedescendants
Example errors: on my system, for the following Word/PDF format documents:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.doc
MD5: 499283d5bb718532273ba64f32d7962c
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.pdf
MD5: 981c601307e84ca3e46b4232a819b03d
I see examples like these:
Line 5040 (Word) and line 5042 (PDF)
Link text: http://docs.oasis-open.org/ns/cmis/link/200901/allowableactions
Display text: http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions
Line 5047 (Word) and line 5049 (PDF)
Link text: http://docs.oasis-open.org/ns/cmis/link/200901/relationships
Display text: http://docs.oasis-open.org/ns/cmis/link/200908/relationships
Line 5053 (Word) and line 5055 (PDF)
Link text: http://docs.oasis-open.org/ns/cmis/link/200901/source
Display text: http://docs.oasis-open.org/ns/cmis/link/200908/source
[... etc]
Grep (though perhaps imprecise) reports thirty (30) of these
kinds of link errors in CMIS v1.0 CS 01. Other examples appear in
(Word) at lines 5060, 5067, 5073, 5085, 5322, 6412, 7219-1720, 7561,
8849, 8851, 8853, 8854, 8991, 8993, 8995, 8996, 9136, 9138, 9140,
9141, 9142... (etc)
========= II. Links with incorrect/malformed link targets ========
I here identity 15 or so; there are others.
A) Line 2423 (Word) contains a link associated with the phrase
"Optional Capability" where the link target is a location on
an editor's local machine:
http://docs.oasis-open.org/cmis/Documents%20and%20Settings/
rmcveigh/My%20Documents/Draft%2061/Content-streams%20are%20NOT%20exposed%20
through%20this%20relational%20view.%20However,%20a%20
Repository%20MAY%20support%20full-text%20indexing%20of%20Content%20St
B) Line 75 [73-75] in Word has an incorrect link for
"See section: 2.2.3.1 getFolderTree". The section labeled
"getFolderTree" is actually 2.2.3.3, and the link on line
75 actually takes the reader to the wrong location (i.e., to
Section '2.2.3.2 getDescendants').
C) Line 2108 (Word) in Section '2.1.9.4.1 Checkout' -- The text
reads "A new version of a versionable Document object is created
when the LINK:[checkIn] service is invoked on the Private
Working copy". The link for "checkIn" terminates at Line 3988,
Section '2.2.7.1 checkOut'. See for comparison the HTML format
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_checkOut
But it seems clear that the link for "checkIn" should terminate at
Section '2.2.7.3 checkIn' (Checks-in the Private Working Copy document)
(i.e., in the HTML version
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_checkIn
D) Line 2276 (Word) on page Page 65, the text reads "In this
relational view a Virtual Table is implicitly defined for
each queryable Object-Type defined in..." The text has a link for
"queryable". Clicking this link [#_Attributes_common_to] takes
the reader to line 2064 -- where no information about "queryable"
is provided. The HTML version suggests a badly placed anchor:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Attributes_common_to
E) Line 280 (Word), in Section '2.1.3 Object-Type', page 16, the text
reads "While a repository MAY define additional object-types
beyond the CMIS Base Object-Types, these..." where we have a link
to 'CMIS Base Object-Types'. Following this link leads to a blank
portion of the document on page 59, just following line 2064, at
the end of the Section '2.1.8.3.2 AllowableActions & Permission
Mapping', preceding Section '2.1.9 Versioning'. Why? Nothing
in Section 2.1.8.3.2 seems to explain 'CMIS Base Object-Types',
which are however, explained in Section '2.1.2 Object'. The HTML:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_CMIS_Base_Object-Type
F) Line 298 (Word) on page 17, similar to the link error in "E)" --
the text says "An object-type definition includes a set of
object-type attributes (e.g. Fileable, Queryable, etc.)" and
there's a link for 'object-type attributes' that leads to line
2064 (page 59) at the end of Section '2.1.8.3.2
AllowableActions & Permission Mapping'. This link destination
isn't particularly useful in understanding 'object-type attributes'.
The intended destination is apparently Section '2.1.3.2 Object-Type
Attributes' at line 316. See the corresponding HTML
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Object-Type_Attributes
G) Line 178 (Word) the text reads "Whether or not an object is
file-able is specified in its object-type definition." with a
link for "object-type definition." The link sends the reader
to line 1695 in the Section '2.1.8 Access Control'. See the HTML:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Object-Type
H) Lines 446-447 (Word) on page 20, the text reads: 'whencheckedout:
The property value MUST only be update-able using a "private
working copy" Document.' The link for "private working copy"
leads to a destination [#_Versioning], which appears as an anchor
in the document just preceding Section "2.1.9 Versioning".
One expects the link for "private working copy" to terminate at
(e.g.,) Section "3.10.3 Document Private Working Copy (PWC) Entry"
(Line 8965, page 204). See the HTML link expression:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Versioning
I) Lines 9794-9795 (Word) in Section '5.1.5 CMIS ACL': the mailto:
link (URI) appears to be malformed [it says: "mailto:OASIS";;],
and the candidate addressee nominated in the visible display text
("cmis@lists.oasis-open.org") would fail in the general case
because someone sending email to that email address would need
to be authorized as a TC member to post to the member-only mailing
list. Any such mailing list is deactivated when the TC closes.
A better candidate would be: tc-admin@oasis-open.org. Similarly
in (Word) lines 9761, 9726, 9693, 9660.
J) Line 3133 (Word) the text reads: "<Array> Object-Types: The
hierarchy of Object-Types defined for the Repository." For the
link 'Object-Types', a reader is led to the location in
Section '2.1.8 Access Control', line 1695. See the HTML link:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Object-Type
K) Lines 3971-3972 (Word) the text has "<Array> changeEvents: A
collection of CMIS objects that MUST include the information
as specified in 2.1.11.3." Following the link for "as specified in"
seems to lead the reader to the top of the document rather than
to Section 2.1.11.3. See the HTML:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Schema_Elements_1
L) Line 3109 (Word) text reads: "Description: Returns the set
of descendant Object-Types defined for the Repository" where the
link for "Object-Types" leads to Section '2.1.8 Access Control'.
M) Line 2990 (Word) at the text "The operation is attempting to
perform an action on a non-current version of a..." we have a link
for "a non-current version". This link leads to a destination
in a blank document region following line 2064. HTML link:
http://docs.oasis-open.org/cmis/CMIS/v1.0/cs01/cmis-spec-v1.0.html#_Versioning
------ / stopped checking ------
Also (misc):
NS Documents: it appears that the document titles are incorrect
for two of the five XML namespace documents (messaging, link):
Content Management Interoperability Services Core
http://docs.oasis-open.org/ns/cmis/core/200908/
Content Management Interoperability Services RestAtom
http://docs.oasis-open.org/ns/cmis/restatom/200908/
*(sic!) Content Management Interoperability Services Core
-->> Content Management Interoperability Services Messaging
http://docs.oasis-open.org/ns/cmis/messaging/200908/
Content Management Interoperability Services WS
http://docs.oasis-open.org/ns/cmis/ws/200908/
*(sic!) Content Management Interoperability Services Core
-->> Content Management Interoperability Services Link Relations
http://docs.oasis-open.org/ns/cmis/link/200908/
================================= Notes:
[#1] Incorrect link construction: '200901' error for '200908'
Archived at:
http://lists.oasis-open.org/archives/cmis-comment/200911/msg00000.html
Date: Thu, 5 Nov 2009 17:05:19 -0500 (EST)
From: Robin Cover <robin@oasis-open.org>
To: CMIS Comment List <cmis-comment@lists.oasis-open.org>
Subject: HREF values in Link Relation URIs, etc
Message-ID: <Pine.LNX.4.64.0911051655470.2357@fs00.ma0.oasis-open.net>
In the CMIS Public Review draft (CD 04) at
http://docs.oasis-open.org/cmis/CMIS/v1.0/cd04/cmis-spec-v1.0.html
I noted several HTML links where the anchor HREF attribute values are
different than the anchor element content, viz., the underlying
HTML code in the HREF value appears to be incorrect, while the
display text is apparently correct.
Actually, this appears not to be a root HTML problem, but a defect in
the editable source (.doc) from which HTML and PDF were apparently
generated.
Perhaps 30 or more of these, for example, in the section
"CMIS Specific Link Relations":
[a href="
http://docs.oasis-open.org/ns/cmis/link/200901/allowableactions
"]
http://docs.oasis-open.org/ns/cmis/link/200908/allowableactions
etc.
test:
$ grep -c 200901 cmis-spec-v1.0.html
31
-rcc
======================================================================
[#2] How best to handle the CMIS specific link relation identifiers
Archived at:
http://lists.oasis-open.org/archives/cmis/200911/msg00011.html
http://lists.oasis-open.org/archives/cmis/200911/msg00012.html
Date: Fri, 6 Nov 2009 11:36:54 -0500 (EST)
From: Robin Cover <robin@oasis-open.org>
To: Al Brown <albertcbrown@us.ibm.com>
Cc: Mary McRae <mary.mcrae@oasis-open.org>, cmis@lists.oasis-open.org,
Robin Cover <robin@oasis-open.org>
Subject: Re: Fw: [cmis-comment] HREF values in Link Relation URIs, etc
Message-ID: <Pine.LNX.4.64.0911061111120.2357@fs00.ma0.oasis-open.net>
[Al Brown said]
> How should we handle the CMIS specific link relations [...]
> Should a new style of a namespace document be created for each [...]
At Mary's request, I have formulated for Al Brown a proposal for
handling of the ten (eleven/twelve) URIs at the DNS+HTTP level
so that the URIs:
a) have some meaningful representation returned to an HTML agent
when they are dereferenced, as we expect for HTTP scheme URIs
b) are handled as non-information resources (viz., distinguished
in processing from typical 'information resources' [1]; thanks
to the CMIS TC, a key feature enabling server-level support
has already been accounted for by the decision to utilize the
CMIS TC's /ns/ path element, which allows URI rewrites using
existing machinery
Al's suggestion to use something like a "new style of a namespace
document" is precisely what I thought of as a solution with
I created a news story for the CMIS public review draft, and
realized (yikes!) that the link relation URIs don't resolve [2].
If we understand a namespace to be fundamentally a "space of
names", then it's not too difficult to see the analogy to XML
namespaces and namespace documents. The root URI for the
collection of CMIS link relation identifiers is:
http://docs.oasis-open.org/ns/cmis/link/200908/
and each of the CMIS-specific link relations matching a
string identifier (URI) is a name in the hierarchical space
below /ns/cmis/link/200908/.
If a namespace document documents a namespace, then, by
analogy, a similar informative document (as an information
resource) can live at the end of the CMIS-specific link
relation URIs. Similar to the use of a single namespace
document to document several related URIs [3], a single
document could be used to document the key facts about
the CMIS-specific link relation URIs (associated
specification, spec owner(s), date, purpose, etc).
This analogy is (I think) consistent with an update I
made in August to the OASIS Naming Guidelines [4], clarifying
that use of the /ns/ path element seems like a reasonable
solution for "namespace related" URIs for collections of
named properties, functions, dialects, faults, actions,
and other message types as non-information resources.
Cheers,
- Robin Cover
--
Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/people/staff/robin-cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]