dita-techcomm — archive

Hardware domain proposal

From: Robert Anderson <[email protected]>
To: [email protected]
Date: Mon, 03 Apr 2017 20:31:00 -0000

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 DITA-OT lead and Co-editor DITA 1.3 specification , Digital Services Group E-mail: [email protected] Digital Services Group 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 <[email protected]> To: "[email protected]" <[email protected]> Date: 04/03/2017 09:44 AM Subject: [dita-techcomm] Hardware domain proposal Sent by: <[email protected]> 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