Re: Spec review request: CSV on the Web

(Admin)

timeless,

thanks for these; I have transferred your comments to the issues list on GitHub:

https://github.com/w3c/csvw/issues/679

Thanks again

Ivan


> On 11 Jul 2015, at 01:51 , timeless <timeless@gmail.com> wrote:
> 
>> W3C Editor's Draft 10 July 2015 [1]
> 
>> We are on Github
> 
> GitHub
> 
>> Data Aggregators can use the indicated metadata, such as descriptions, titles, modification dates, and licences [sic], to enable more intelligent retrieval of relevant data on the web.
> 
>> Implementations may fulfil [sic] one or more of these functions.
> 
>> which are not defined in this specification and MUST generate a warning when they are encoutered [sic].
> 
>> then that string is assumed to be in the default language (or have an undefined language, und, if there is no such property).
> 
> pattern:
> Could you write "und" instead of und (unquoted)? For those of us
> reading the document with a Screen Reader or similar tool (actually a
> plain text serializer in my case), the monospace formatting is lost.
> 
>> Foreign key definitions provide for strong linking between tables that guarantees (through validation) the existance [sic] of a referenced row.
> 
>> For example, if an implementation recognises and displays the value of the dc:description property, it should also recognise and display the value of the http://purl.org/dc/terms/description property in the same way.
> 
> en-US:
> please see point 2 of [2]
> 
>> Note that this format is not the same as the existing text/csv and text/tab-delimited-values mediatypes [sic],
> 
> Google says it's two words.
> 
>> The CSV on the Web Working Group was chartered to produce a
> 
> This is the first instance of the group, but it isn't linked here
> (it's linked in the next paragraph). That feels like putting the cart
> before the horse.
> 
> Also, if you're going to mention the charter, you could do everyone
> the favor of linking to it.
> 
>> Recommendation "Access methods for CSV Metadata" as well as
>> Recommendations for "Metadata vocabulary for CSV data" and "Mapping mechanism to transforming CSV into various Formats (e.g., RDF, JSON, or XML)"
> 
> I object to capitalizing `Formats`.
> 
>> This document aims to primarily satisfy the second of those Recommendations.
> 
> I don't think that word should be capitalized in this context.
> 
> Depending on how you parse the previous lines, this either references
> 2/2 or 2/3.
> 
> I'm not quite sure the value of writing this as you did. I'd suggest
> "This document addresses the charter scope for {}. Additional charter
> scope items include {} and {} which would be covered by other
> documents."
> 
>> As an example, say that the following CSV file were available at http://example.org/tree-ops.csv
> 
> missing `:`
> 
>> For example, say that the following metadata file were available at http://example.org/tree-ops.csv-metadata.json:
> 
>> [reference]
>> A document reference (normative or informative) is enclosed in square brackets and links to the references section.
> 
> Here, the brackets are included in the link, they aren't in the document.
> 
>> compliant applications MUST use that default value and MUST generate a warning.
> 
> => MUST generate a warning and use that default value.
> 
> which parallels this:
> 
>> If no default value is provided for that property, compliant applications MUST generate a warning and behave as if the property had not been specified.
> 
>> including properties (aside from common properties) which are not defined in this specification.
>> having invalid values for a given property.
> 
> these items are not sentences and aren't preceded by a `:`
> 
>> on a [sic] annotated tabular data model.
> 
> "an"
> 
>> A description object is a JSON object that describes a component of the annotated tabular data model (a group of tables, a table or a column) and has one or more properties are mapped into properties on that component.
> 
> `are` => that are | {empty}
> 
>> For example, in the column description
> 
> add `,` or `:` ?
> 
> Offhand, figure 1 [3] was generated at a resolution which is too small
> to read at 100%; text runs together... Also, the gray background is
> unhelpful.
> 
> figure 1 [4] isn't accessible, it's just a bunch of lines / polylines.
> Someone helpfully stripped all the words from the source code.
> 
>> There are different types of properties on description objects:
>> * section 5.1.1 Array Properties.
>> * section 5.1.2 Link Properties.
> 
> these aren't sentences...
> 
>> The variables that are set are:
> 
> ... are ... are <- yuck
> 
> most of these don't end in a period:
>> _sourceRow is set to the source number of the row that is currently being processed; this usually varies from _row by skip rows and header rows
> 
> except this one:
>> _name is set to the URI decoded column name annotation, as defined in [tabular-data-model], for the column that is currently being processed. (Percent-decoding is necessary as name may have been encoded if taken from titles; this prevents double percent-encoding.)
> 
>> The propertyUrl property might be defined as "{#_name}", meaning that it resolves as a fragment identifier relative to the URL of the source of the table. For example, accessing it from a column with the column name GID would look like:
> 
> I couldn't follow this example. Partially, I think you hid the input
> as prose and only showed output in example 11, whereas example 10 was
> the input and the prose held the output.
> 
>> the processor will issue a warning and ignore the value.
> 
> pattern:
> `will` isn't an rfc word
> 
> No Oxford Comma:
>> An atomic property that MUST have a single string value that is one of "rtl", "ltr" or "auto".
> 
> Oxford Comma:
>> Indicates whether the tables in the group should be displayed with the first column on the right, on the left, or based on the first character in the table that has a specific direction.
> 
> please pick a style (I'd recommend Oxford).
> 
>> It is also possible to provide weak linking between tables that are not tested by validations but which may be useful when converting tabular data into other formats, using aboutUrl and valueUrl.
> 
> I think you want to drop the `,`;
> 
> the sentence is too long.
> 
>> This annotation MUST be percent-encoded as necessary to conform to the syntactic requirements defined in [RFC3986]
> 
> missing `.`
> 
>> A boolean atomic property taking a single value
> 
> isn't `taking a single value` redundant for `boolean`?
> 
>> a [sic] inherited property defined in its containing schema description
> 
> an
> 
>> takes precedence of one defined in its containing table description
> 
> pattern:
> of => over
> 
>> This property is irrelevant if the separator is null or undefined, but this is not an error.
> 
> `but this is not an error` doesn't make sense / read well
> 
>> An [sic] URI template property that MAY be used to create a URI for a property if
> 
> pattern:
> A -- note that you use `a URI` elsewhere, including later in this fragment.
> 
>> quoteChar
>> The default is ".
> 
> I'd suggest writing this as: "\"" or '"'
> 
>> An [sic] boolean atomic property
>> An [sic] numeric atomic property
> 
> pattern:
> A --
> 
>> A boolean atomic property that, if true, sets the trim flag to "start".
>> If false, to false.
> 
> This second "sentence" needs more words.
> It probably should be `to "false"` also...
> 
>> No other values are valid.
> 
> Is that an "Error", or just "whatever"?
> 
>> Applications MUST raise an error if length, maxLength, or minLength are specified and the base datatype is not string or one of its subtypes, or a binary type.
> 
> the order of `or`s doesn't work.
> 
> try ... neither string/string subtype nor a binary type.
> 
>> Values MAY be a string, native JSON type (such as number, true, or false.), value object, node object or an array of zero or more of any of these.
> 
> stray `.` inside the parenthetical
> 
> 
> 
> [1] http://w3c.github.io/csvw/metadata/
> [2] https://lists.w3.org/Archives/Public/public-csv-wg-comments/2015Jun/0002.html
> [3] http://w3c.github.io/csvw/metadata/properties.png
> [4] http://w3c.github.io/csvw/metadata/properties.svg
> 


----
Ivan Herman, W3C
Digital Publishing Activity Lead
Home: http://www.w3.org/People/Ivan/
mobile: +31-641044153
ORCID ID: http://orcid.org/0000-0003-0782-2704