Add reporting document for package metadata

[mattgarrish]

This is a palceholder document to use to report on authoring of the various package metadata.

One modification I've made is to ensure these will only ever be two-column tables. The dpub model used a column for each publisher because we knew before making the report document only three publishers were needed to cover the full range of values. Given there will be different uptake of different properties here, and we'll probably need to talk to a lot more people to get sufficient coverage of each property, using the column approach could get ugly to read.

In place of that approach, I've labelled the second column "used by" and added a placeholder list to each row where we can identify who is using each property. I've done the same to the a11y report for consistency.

---

Preview | Diff

[iherman]

This is a general comment, both for this section and the other document: it may be better to put active links to the specification themselves. It helps the reviewers to find their way through the report.

Also, we should discuss whether to set up the two-way links between the specifications and this document the same way as we have done for the functional tests (recognizing that, if we do the latter, it may be better to convert these documents into HTML, which is of course doable but it is a drag). Again, this may help the reviewers to see the completeness (or not...) of our "tests".

Cc @dlazin

[mattgarrish]

we should discuss whether to set up the two-way links

It probably wouldn't be too hard to do this. I assume the script for the test links checks if specStatus=ED before generating?

[iherman]

This is done by respec, not by my script; my stuff just generates the reports.

However. I realize now that it straight out of the box to use the respec trick. Respec uses the testSuiteURI: it sees a data-test value (e.g., #pgk=lang_pkg), concatenates that with the value of testSuiteURI and then creates the small pull-down values (and yes, it does it only for the editors' draft). I do not think it is prepared to use several testSuiteURI values.

That being said, there is already a data-test-display.js script that massages those boxes a bit. It would be possible to find out, somehow, that those links are to be used with a different URI...

But we still have to have the right target fragment. Adding a fragment to a markdown my be a pain.

[mattgarrish]

I've linked all the properties to their definitions in the latest commit. I've also added links to any other references (not just to the specs but also tools).

For completeness, I've also added a paragraph to each section saying where the properties are used. Might help with understanding what the properties do. Worst case it doesn't harm anything.

[mattgarrish]

I haven't tried to link from the specification to the report.

[iherman]

I would think we could leave this one out. There is no specification for it in our document; it is redirected to EPUB 3.0 after all...

[iherman]

Same comments as before (and valid for the two entries below and to xml-signature and xmp-record): I wonder whether listing deprecated properties here makes sense.

This is also a question to @dlazin @wareid @dauwhe

[iherman]

Thinking a bit further, back in the specification proper: maybe regrouping the deprecated records separately in, eg, §D3, may make the situation cleaner...

[mattgarrish]

I put them in for completeness. What I was thinking we would do is add some sort of boilerplate statement in the second column about deprecated properties not needing verification. I can try and figure something out now, but I wouldn't shift them around into a new group. That'll just make it harder to locate them. We should try to parallel the core spec as much as possible.

[mattgarrish]

What I've done for these is strike them through using s tags and dropped "(deprecated)" and instead added the prose:

This property is deprecated and no longer recommended for use in EPUB Publications. It is only listed for completeness of reporting.

[mattgarrish]

@clapierre can you also have a look at this?

I've added the publishers from the GCA certification page to all but the certifier report property.

[mattgarrish]

Here are previews of the markdown docs:

• https://github.com/w3c/epub-specs/blob/reports/add-templates/epub33/reports/epub-properties-use.md
• https://github.com/w3c/epub-specs/blob/reports/add-templates/epub33/reports/a11y-properties-use.md

[iherman]

The issue was discussed in a meeting on 2022-02-25

List of resolutions:

• Resolution No. 1: Merge PR 2002.

View the transcript

2. Add reporting document for package metadata (pr epub-specs#2002)

See github pull request epub-specs#2002.

Matt Garrish: coming out of last meeting, we said we needed to report on all the metadata vocab we define in the authoring spec.
… basically same issue we had with DPUB ARIA vocab.
… I created a table that maps each property to the publishers that use them.
… its just a placeholder so far, needs to be filled out.

Dave Cramer: how would this work? Will we merge this, and then publishers who use the property would add their name via PR?.

Matt Garrish: we ask people to open PR, or they send them lists of which properties they are using, and we can add them.
… also question of if we need to have links from the spec to this table, and how that would work.
… not sure if we need to tackle that now.

Charles LaPierre: if we need to have any properties that are being used, I can go through the completed CGA reports from publishers and find all the accessibility metadata in there if that's helpful.

Matt Garrish: i'm hoping you can take a look at the a11y document.
… you'd just put the name of the publishers in there.
… i've pre-populated some names based on CGA certification.

Ivan Herman: my proposal is to merge this because what mgarrish referred to about linking.

Ben Schroeter: just a word of caution that we're not violating any NDAs when we're pulling stuff from GCA reports.

Charles LaPierre: absolutely, i'll talk to the publishers first.
… mgarrish when you mention the certifier report, I actually spoke with folks at Benetech about creating separate reports for publishers who have passed certification, and creating report pages for each publisher.
… the page could be customized for each publisher, to include their support email address, etc..

Matt Garrish: if you want I can take out the changes to the a11y report and make it a separate PR.
… give you time to talk to publishers.

Charles LaPierre: okay, thanks.

Ivan Herman: we also need the same thing for all the vocab in the package document.
… maybe its already somewhere, but we need to collect that too.

Charles LaPierre: i was just referring the a11y properties.

Dave Cramer: sounds like there is broad consensus about merging these.
… also caution that just because a publisher uses some of these properties, it doesn't mean that it works anywhere.
… e.g. "file as".
… and just because a publisher uses a property, doesn't mean they are using it properly.
… in some cases (e.g. dc:rights), not clear how these are to be used.

Charles LaPierre: not just RS, but libraries and bookstores as well can expose this metadata, as a secondary source for examples of use.

Matt Garrish: we just need to show that these aren't completely fanciful.

Dave Cramer: right, that people want to use these metadata.

Proposed resolution: Merge PR 2002. (Wendy Reid)

Ivan Herman: +1.

Wendy Reid: +1.

Matthew Chan: +1.

Matt Garrish: +1.

Bill Kasdorf: +1.

Ben Schroeter: +1.

Masakazu Kitahara: +1.

Dave Cramer: +1.

Toshiaki Koike: +1.

Resolution #1: Merge PR 2002.

Dave Cramer: mgarrish you were going to split out some of the stuff for CharlesL before you merge it?.

Matt Garrish: yes, i will.