W3C home > Mailing lists > Public > www-xml-xinclude-comments@w3.org > July 2015

Re: CR: XML Inclusions (XInclude) Version 1.1

From: timeless <timeless@gmail.com>
Date: Thu, 2 Jul 2015 15:01:09 -0400
Message-ID: <CACsW8eHApj3fdWYiuz=ojzKRWUhcJ3Qd6XF=Ams+oa8XMhBW4Q@mail.gmail.com>
To: www-xml-xinclude-comments@w3.org

Note: the first set of comments applied to:
(and were in my review queue from Re: RfC: Last Call: XML Inclusions
(XInclude) Version 1.1; deadline: 17-Jan-2015)

Given that the first comment here indicates that no one ran the
document through a basic spell checker, I'd argue that this document
failed simple "wide review":

>    A key feature of XInclude is that it allows a resource to be cast to a user-specifed [sic] type for inclusion.

> The syntax for an internal subset is cumbersome to many authors of simple well-formed XML documents.

About 249 results (0.61 seconds)

> Resources that contain non-well-formed XML result in a fatal error.

> Another processor with no such heuristics might attempt to parse the non-XML resource as XML and encounter a well-formedness (fatal) error.

wellformedness --
About 108 results (0.62 seconds)

note that formedness isn't a word.

> Declaration of external entities requires a DTD or internal subset.

or => or an

> If the href attribute is absent when XML processing is specified, the xpointer or fragid attribute must be present.

, the => , one of the ; attribute => attributes ??

(Can both be present?) apparently "sort of"

I think you want:

, the => , an ; or => or a

> Fragment identifiers must not be used; their appearance is a fatal error.

appearance => presence

> A value of “text”, “text/plain”, or a value in the “text” family indicates that the resource must be included as the character information items.

awkward; possibly:
as the => as ??

> (i.e., media types registered per [IETF RFC 4288])

here, the []s aren't read, so humans read it as:
media types registered per IETF RFC 4288

reading this:
> for text processing, it is interpreted as a [IETF RFC 5147] fragment identifier.
... the same way yields:
it is interpreted as a IETF RFC 5147 fragment identifier.

a => an

> Other content (text, processing instructions, comments, elements not in the XInclude namespace, descendants of child elements)

this list is missing a conjunction (and/or) or a tail (ellipsis/etc.)

> is not constrained by this specification and is ignored by the XInclude processor, that is, it has no effect on include processing, and does not appear in the children properties of the result infoset.

> If both xpointer and fragid are specified, they should be the same.
> It is a recoverable error if they are not the same; to recover, if the parse attribute specifies XML processing, then the xpointer attribute is used; otherwise the fragid attribute is used.

So, I can include distinct xpointer and fragid values, and if the
parse attribute isn't xml, then fragid will be used (recoverable
error). great.

> The xpointer attribute must not be present when text processing is specified. It is a fatal error to specify the xpointer attribute when text processing is specified.

But if parse is text, then it's fatal?

This is nearly a contradiction. I'd encourage you to explicitly
exclude text in the first section, or drop this second section/make it
a recoverable error -- depending on what you're trying to do.

> It is a fatal error if neither the xpointer nor fragid attributes are present and the href attribute is not present.

this could be written as `none of the xpointer, fragid, and href
attributes are present`

> Neither the xpointer nor fragid attributes contain a URI reference, and %-escaping is not done in XPointers, so '%' is an ordinary character in the value of the xpointer and fragid attributes.

This feels non normative and should probably be prefixed by `note:`

> It is a fatal error for an xi:fallback element that is not being ignored to appear in a document anywhere other than as the direct child of the xi:include (before inclusion processing on the contents of the element.) It is a fatal error for an xi:fallback element that is not being ignored to contain any elements from the XInclude namespace other than xi:include.

The `.` belongs outside the `)`

> It is a fatal error for an xi:fallback element that is not being ignored to contain any elements from the XInclude namespace other than xi:include.

<xi:include ...>
  <xi:include ...>

I believe that this is a fatal error according to the first part of
this ruleset....

> [Definition: The input for the inclusion transformation consists of a source infoset.] [Definition: The output, called the result infoset, is a new infoset which merges the source infoset with the infosets of resources identified by URI references or IRI references appearing in xi:include elements.]

These have no trailing space before `]`

> [Definition: The information items located by the xi:include element are called the top-level included items ]. [Definition: The top-level included items together with their attributes, namespaces, and descendants, are called the included items ].

These have trailing spaces, and they also have randomly placed `.`s --
The `.`s belong where the spaces are (before the `]`s).

> The value of this attribute is an XML resource identifier as defined in [XML 1.1] section 4.2.2 "External Entities", which is interpreted as [Definition: an IRI Reference as defined in RFC 3987 [IETF RFC 3987]], after the escaping procedure described in [XML 1.1] section 4.2.2 is applied.

So far, [Definition: ... .] has always appeared as a standalone
sentence in this document. Here, it's inlined, which is weird.

Here you just do [X]:
> XPointers of the forms described in [XPointer Framework] and [XPointer element() scheme] must be supported.

Here you do Y [Y]:
> For example, a single URI or IRI may variously return a raw XML representation of the resource, an XSL-FO [XSL-FO] representation, or an XHTML [XHTML] representation, as well as versions in different character encodings or languages.

> The inclusion target might be a document information item (for instance, no specified xpointer attribute, or an XPointer specifically locating the document root.) In this case,

The `.` belongs outside the `)`

> The XML Information Set specification does not provide for preservation of white space outside the document element. XInclude makes no further provision to preserve this white space.

this document also uses `whitespace`

> it is a fatal error to process another xi:include element with an include location and xpointer attribute value that have already been processed in the inclusion chain.

have => has

> When the first character is U+FEFF and is interpreted as a Byte-Order Mark, it should be discarded. It is interpreted as a BOM in UTF-8, UTF-16, and UTF-32 encodings; it is not interpreted as a BOM in the UTF-16LE, UTF-16BE, UTF-32LE, and UTF-32BE encodings.

Assuming a document is UTF-16LE, and a U+FEFF is the first character,
it apparently shouldn't be discarded. What should happen to it??

> It is a fatal error if there is zero or more than one xi:fallback element.

are ... elements

>  <p>120 Mz [sic] is adequate for an average home user.</p>

Mz => Mhz

> <?xml version='1.0'?>
> <document xmlns:xi="http://www.w3.org/2001/XInclude">
>  <p>120 Mz is adequate for an average home user.</p>
>  <disclaimer xml:base="http://www.example.org/disclaimer.xml">
for readability, if possible, the next 4 lines should be indented by
two additional spaces:
>  <p>The opinions represented herein represent those of the individual
>  and should not be interpreted as official policy endorsed by this
>  organization.</p>
> </disclaimer>
> </document>


[Standard disclaimer: this isn't an endorsement of the document/technology.]
Received on Thursday, 2 July 2015 19:01:38 UTC

This archive was generated by hypermail 2.3.1 : Thursday, 2 July 2015 19:01:39 UTC