Hi Scott,
I've got a few initial comments. Sorry to have missed the call today, I assume this was discussed - apologies if I'm bringing things up that have already been settled.
First, the biggest issue - I'm very nervous at an element named <key>. There are two reasons it scares me: 1. It's an extremely general term, with a wide variety of meanings. If the spec says "<key> specifies a keyboard key", it would be sort of like saying "<address> specifies a location in RAM" - it reserves a common word with lots of meanings and locks it into a narrow one. 2. The term "key" is extremely overloaded in DITA already, to put it mildly. I suspect anybody encountering an element called <key> would reasonably assume it's related to @keyref, <keydef>, or one of the many key-related attributes.
For both of those reasons, a longer / more explicit name like <keyboard> or <keyboardKey> seems better.
Second - all three of the elements in this schema are specialized from <ph>, but they break specialization by adding new attributes you don't find on <ph>: - <keycombo> adds @action, which doesn't exist anywhere in DITA - <systemitem> adds @type, which doesn't exist on <ph> and is hugely overloaded on other elements
Technically, with DITA 1.3 rules, you could define @action separately as an attribute specialization, and then add a constraint that means it's only valid on <keycombo>. I really hope to loosen up those rules in 2.0 but it would still be unusual and require an attribute specialization. You couldn't do this with @type because it already exists in a lot of places, so wouldn't be legal as a specialized attribute.
Given that both of these are enumerations, and optional, I've seen similar specializations use nested <data> elements to store the information. Not sure if that's of interest here.
Last - the <keycombo> element explicitly nests the <uicontrol> element from the UI domain. Technically, this gives the hardware domain a dependency on the UI domain (the hardware domain is invalid unless UI domain is also available). This might be just as intended, but it surprised me so I wanted to make sure it's noted.
Scott Hudson ---04/03/2017 09:44:03 AM---Slow going, but here is the first of my proposals. (schema, not docs yet) Thanks and best regards,
From: Scott Hudson <scott.hudson@jeppesen.com> To: "dita-techcomm@lists.oasis-open.org" <dita-techcomm@lists.oasis-open.org> Date: 04/03/2017 09:44 AM Subject: [dita-techcomm] Hardware domain proposal Sent by: <dita-techcomm@lists.oasis-open.org>
Slow going, but here is the first of my proposals. (schema, not docs yet) Thanks and best regards, --Scott Scott Hudson Content Strategist Digital Aviation Learning & Development Voting member: OASIS DocBook TC, Publishers SC OASIS DITA TC, Tech Comm SC, LW DITA SC, Learning Content SC OASIS Augmented Reality in Information Products (ARIP) TC
Jeppesen | Digital Aviation | Boeing
55 Inverness Drive East | Englewood, CO 80112 | www.jeppesen.com This document contains only administrative, uncontrolled data under U.S. International Traffic in Arms Regulations.[attachment "hardwareDomain.rnc" deleted by Robert D Anderson/Rochester/IBM] --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
|