Integrate metadata guide

[mattgarrish]

This pull request moves the metadata requirements into the main specification.

I'm opening this pull request a bit early to start getting feedback. I've tried to fill in some of the sections as best I can with some more details from how epub defines/handles them, but I may have some things wrong (especially whether some properties can be repeated). We also discussed some additional changes in the last meeting that I haven't tried to go back and integrate yet. Let me know whatever you spot that needs fixing or needs more detail.

• Preview
• Diff

[wfree-aph]

Line 713 shows >well-formed. I wasn't sure if that greater than symbol was necessary or a typo.

Only other thing is that at line 1090 with Optional properties. I think we decided as a group to just have required and recommended with the idea being that we just wouldn't define "optional" and people could add what they wanted as long as they followed the required properties.

[bertfrees]

There is something wrong in the sentence "The value SHOULD include any code-specific information needed to fully its formatting".

Shouldn't dc:language always include the "Brai" subtag, since the content is, per definition, in braille script? Perhaps it should not be required, since it can be assumed. But regardless, wouldn't it be more accurate if the examples in the spec were changed?

Then there's one other thing. I know this is probably not the right place and time to discuss it, but I only found out about the brl:dotNumber field now. Can someone fill me in on why exactly it was requested? This is typically information that I would expect in the brl:code field. I could imagine an additional field could be useful for a user agent to quickly test whether a publication may be rendered (if it depends on whether 8-dot cells are present or not), but then I don't get why it should be allowed to have "6, 8" or "8, 6". Sorry if I'm bringing up things that have been discussed before. If someone can please just briefly fill me in. If I have more questions I will take it up in a separate issue :-)

[mattgarrish]

There is something wrong in the sentence "The value SHOULD include any code-specific information needed to fully its formatting".

Ya, something weird happened there. I've fixed that to:

The value SHOULD include all relevant code-specific information (e.g., "contracted", "uncontracted", "bar by bar" etc.).

[mattgarrish]

Perhaps it should not be required, since it can be assumed.

Ya, I don't know about requiring it when we have multiple renditions. The text rendition wouldn't be braille.

I'm okay with adding -Brai to the examples, though, since we're focused on the default braille rendition.

[mattgarrish]

Line 713 shows >well-formed. I wasn't sure if that greater than symbol was necessary or a typo.

Necessary. It's just the line formatting from the editor I use. It broke the closing angle bracket for the tag onto a new line because of the length of the URL on the previous plus the word after the tag wouldn't fit any other way.

[mattgarrish]

the idea being that we just wouldn't define "optional" and people could add what they wanted as long as they followed the required properties

Yes, and I don't plan to add any optional property definitions there. But I think we should still explain that all the DC elements are available because we are using epub and you can add prefixes for other vocabularies. Otherwise, I think people not familiar with the epub package document might get confused that we don't allow anything but the required and recommended properties.

[mattgarrish]

I could imagine an additional field could be useful for a user agent to quickly test whether a publication may be rendered ... but then I don't get why it should be allowed to have "6, 8" or "8, 6"

I'm probably not the right person to answer this, but wouldn't it allow the reading system to attempt to render the publication (if it's predominantly in a cell type it supports) rather than rejecting it outright because it can't render any of it?

In any case, I've made the name change to cellType that was request in the last call and logged in #194 .

[egli]

Can someone fill me in on why exactly it was requested? This is typically information that I would expect in the brl:code field. I could imagine an additional field could be useful for a user agent to quickly test whether a publication may be rendered (if it depends on whether 8-dot cells are present or not), but then I don't get why it should be allowed to have "6, 8" or "8, 6". Sorry if I'm bringing up things that have been discussed before. If someone can please just briefly fill me in. If I have more questions I will take it up in a separate issue :-)

I think the motivation was as you mention so that a user agent can quickly test whether it can support a publication.

As far as I understand the reason for allowing both values is so you can publication that contain both kinds of braille cells.

[mattgarrish]

I'm going to merge this pull request before it becomes any bigger and then we can take up individual issues in separate pull requests.