search

sc34wg4 / opcRevision

Revision of ISO/IEC 29500-2 (Open Packaging Conventions)
1 stars 0 forks source link

4. Notational conventions #25

Closed RexJaeschke closed 3 years ago

RexJaeschke commented 4 years ago

GB-027 |   | 4 |   | ed | In the PDF document circulated for ballot the typographic conventions do not appear to have been applied here or indeed elsewhere in the document. For example, in item (d) the term “auto” is not styled any differently to surrounding text, so not in a constant-width style as indicated that it should be.

Either apply the typographic convention as specified or change the typographic convention according to the constraints of the publishing process.

US-075 |   | 4 |   |   | Includes the following indications that different styles will be used for elements, attributes, etc. ===

b) The tag name of an XML element is written using a distinct style and typeface, as in “The bookmarkStart and bookmarkEnd elements specify …”

c) The name of an XML attribute is written using a distinct style and typeface, as in “The dropCap attribute specifies …”

d) The value of an XML attribute is written using a constant-width style, as in “The attribute value of auto specifies …”

e) The qualified or unqualified name of a simple type, complex type, or base datatype is written using a distinct style and typeface, as in “The possible values for this attribute are defined by the ST_HexColor simple type.”

The different styles are not reflected in this clause, or anywhere in the document.  This makes some parts of the document awkward to interpret.  [Note: the source document used named styles to indicate when the special styling was used.]

ISO-028 |   | 4 | d) | ed | The term "auto" is in Consolas. Please note that only the font Courier New is preserved in the PDF output for code.

Please change the font to Courier New.

ISO-036 |   | 7.5.3.3 |   | ed | In the description for TargetMode and Target, "internal" and "external" are in Consolas.

ISO-044 |   | 9.3.3.3 | 3 | ed | "dcterms:W3CDTF" and "dcterms" are in Consolas.

ISO-045 |   | 9.3.3.4.3, 9.3.3.4.4 | 2 | ed | "xml:lang" is in Consolas.

ISO-048 |   | 11.5.11, 11.7 |   | ed | "idPackageObject" and "idOfficeObject" are in Consolas.

ISO-049 |   | 11.5.13 |   | ed | "idSignatureTime" is in Consolas.

ISO-051 |   | 11.6 | Step 3, b) | ed | "internal" is in Consolas.

RexJaeschke commented 4 years ago

On yesterday's WG4 call we agreed we want to be able to distinguish these elements from ordinary text. We also agreed to use the same font for element, attribute, attribute value, and XSD type name. We can change those styles to be Courier New (which I think none of us likes), and while our styles will be ignored, we think the resulting font info will be preserved if the corrected file is passed through ISO tooling. Get confirmation from ISO.

RexJaeschke commented 4 years ago

2020-07-08 Teleconference

We reconfirmed that we want to be able to distinguish these textual elements from ordinary text. This led to a discussion of the use of styles in general.

Action: Rex will start work on a list of issues to raise with ISO. Once he’s drafted something, he’ll work with Francis to refine it before distributing it to WG4. The result will be at least two documents to be submitted to ISO:

RexJaeschke commented 3 years ago

On the call of 2020-09-16, we agreed to use Courier New for the element/attribute/type styles.

All four styles described by list items b–e have been changed to “Courier New”. And as list item a has been deleted, the whole of Clause 4 has been deleted. All hard-coded clause references in the Foreword have been made relative, so they track the removal of Clause 4 automatically.

Note that removing this clause from Parts 1 and 2 will not be an option, as various (important) third-party resources hard-code clause spec numbers, in which case, we'll need to come up with some sort of replacement for this clause in those Parts.