RE: (Updated) Comments from the current review that we need to discuss

Hi, Frank.

Robert and I have an action item from last week to discuss this. I’ll put your e-mail on the agenda at the same time that Robert and I report back about our action item.

Best,

Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Owner, Eberlein Consulting LLC
kris@eberleinconsulting.com

Skype: kriseberlein; voice: +1 (919) 622-1501

From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> On Behalf Of Wegmann, Frank
Sent: Tuesday, January 24, 2023 3:48 AM
To: Kristen James Eberlein <kris@eberleinconsulting.com>; DITA Technical Committee (dita@lists.oasis-open.org) <dita@lists.oasis-open.org>
Subject: [dita] RE: (Updated) Comments from the current review that we need to discuss

I think, the discussion regarding option/paramname was not finished.

It might help just once glancing over what has been defined in DocBook, because its roots are in software documentation. For <option>, DocBook states in its short description: “An option for a software command.” And: “An option idenfities an argument to a software command or instruction. Options may or may not be required.” (https://tdg.docbook.org/tdg/5.1/option.html)

That reflects my understanding: Options are always tied to a command, and, curiously enough, may be optional, but could also be mandatory.

Parameters are used in a different context: They are variables in the declaration of a function, and I would use <paramname> accordingly. Actual values passed on to a function are called arguments, but we don’t have that. You don’t define options in a function, you don’t pass options around.

Of course, “parameter’ also has another, much broader, general meaning, but not if we’re talking software.

Now, whatever people use, is of course their decision. But in the spec we should stick to what people familiar with a computer science/programming background would expect here.

Admittedly, I wasn’t aware of <option> either, but I haven’t done so much software documentation in DITA…

From: dita@lists.oasis-open.org <dita@lists.oasis-open.org> On Behalf Of Kristen James Eberlein
Sent: Tuesday, 17 January 2023 15:16
To: DITA Technical Committee (dita@lists.oasis-open.org) <dita@lists.oasis-open.org>
Subject: [dita] (Updated) Comments from the current review that we need to discuss

Hi, folks.

There are several comments from the current review that we need to discuss. The links below go to the topic in the Content Fusion review, so if you have not yet used Content Fusion, you’ll need to decide on how you want to log in. You can log in using your GitHub or Google credentials, or you can set up a Content Fusion user ID and password.

<codeblock>

Font conventions and RFC-2119 terminology (page 3 in PDF
Where do we want to cover font and other formatting conventions? Currently they are in a non-normative appendix topic: Formatting conventions. Should they be in the “Rendering expectations” sections of individual topics instead? Or in both places?

<option>: What is the semantic distinction between <option> and <parmname>? Can we be more precise in the DITA 2.0 spec? (pages 5-6 in PDF)
<userinput>: Appropriate tagging for code samples in the “Example” section of element-reference topics (page 12 in PDF)

A PDF of the Content Fusion review is attached.

Best,

Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Owner, Eberlein Consulting LLC
kris@eberleinconsulting.com

Skype: kriseberlein; voice: +1 (919) 622-1501

Software AG – Sitz/Registered office: Uhlandstraße 12, 64297 Darmstadt, Germany – Registergericht/Commercial register: Darmstadt HRB 1562 - Vorstand/Management Board: Sanjay Brahmawar (Vorsitzender/Chairman), Daniela Bünger, Joshua Husk, Dr. Benno Quade, Dr. Stefan Sigg - Aufsichtsratsvorsitzender/Chairman of the Supervisory Board: Christian Lucas - https://www.softwareag.com

dita message