Further deconstruct the epub publications section #1609
Conversation
… requirements are stated in their respective sections. Remaining requirements are restructured as sections.
|
I like it. A lot. It makes the whole document so much clearer (what a journey since 3.2!). I have only one specific comment and this is related to #1601 or, more specifically, to your remark in #1601 (comment). It may be a good idea to add a general i18n section in (the new) §2, much like we have a section on Data URLs. The section would say (this is just a rough text, should be wordsmithed):
I am not sure whether §3.3 should remain, or should be folded into this (except maybe specifying the At the moment, there is nothing about language in the spec, except for the section mentioned in #1601. One could of course argue that the XHML conformance covers that, and that is of course correct, but @dlazin's comment shows that there is a possible source of confusion. |
|
(B.t.w., once this gets to an equilibrium point, I am happy to try to draft such a section, unless you beat me into it!) |
Yes, I had to hold myself back from trying to solve some of the other issues at the same time. I figure there are enough moving parts in this PR as it is, so better to focus on one thing. Once this is done -- which should be shortly as I only want to check some of the lead-in sentences after the highlighted requirements -- feel free to jump on #1601 or the others. |
|
Okay, I think what's in the PR now is reasonably good to go. The last commit was mostly minor editorial stuff: standardizing some language, making sure all the requirements link across to their respective sections in the core and not just definitions, etc. The only mildly notable change I had to do was in the xml processing section. Three of the four bullets described the type of processor a reading system has to be, so I separated the bullet about not resolving external identifiers. Still not sure about the colour scheme for the top-level requirements. All the colour shadings that aren't too offensive are in use (blue for definitions, green for notes, etc.). I settled on yellow as it's not too hard on the eyes and there aren't many examples in the reading system specification to collide with. Suggested improvements welcome. Given that this is less of a change than the last pass, it might be good to also get this out in tomorrow's release. I don't mind putting a new snapshot together. |
Opening this PR for review from anyone who has an opinion -- it's not finished or ready to be integrated yet, so not asking for formal reviews.
These edits are another pass at trying to improve the support statements that reference out to entire sections. Instead of grouping at the top, I've moved the requirements to the beginning of their respective sections so it's obvious when you reach each section what the expectation is (the boxes I've formatted can no doubt be improved on, but are there to add extra emphasis to the top-level support nature of the statements).
This is mostly an exercise in shuffling, as unlike the last PR none of the requirements were redundant and could be removed.
One thing this did highlight was that we were missing specific requirements for some sections. In particular, there wasn't a top-level requirement to process the navigation document. The vocabulary sections also tended to lack any clear support statements, so I've added those as best I understand them (epub:type is optional but the vocabulary handling mechanisms in the package document are required).
I had to make up a "must process publication resources" requirement for the group of resource sections that were embedded in the old section 2. I'm not sure this is the best phrasing, but I can't think of a better statement (saying RSes must support them is misleading, and saying they must handle them seems to make less sense than process).
Anyway, before I do any more clean up on this PR, I want to make sure it's going in the right direction, so any general comments welcome.