Hi Robert,
Thanks for your feedback. Indeed, the concern about “key” was echoed in the meeting. We did not arrive on an agreed name, but one suggestion was to use hwKey or keyboard. DocBook uses keycap.
It is agreed that we need something other than “key”
Also, good point about the specializations. This will require further thought.
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.
From:
Robert D Anderson <robander@us.ibm.com>
Date: Monday, April 3, 2017 at 2:31 PM
To: Scott Hudson <scott.hudson@jeppesen.com>
Cc: "dita-techcomm@lists.oasis-open.org" <dita-techcomm@lists.oasis-open.org>
Subject: Re: [dita-techcomm] Hardware domain proposal
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.
|
Regards,
Robert D. Anderson
|
|
|
|
|
|
|
|
|
11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA
|
|
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