dita — archive

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

From: Kristen Eberlein
To: [email protected]
Date: Tue, 24 Jan 2023 15:05:00 -0000

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 [email protected] Skype: kriseberlein; voice: +1 (919) 622-1501 From: [email protected] <[email protected]> On Behalf Of Wegmann, Frank Sent: Tuesday, January 24, 2023 3:48 AM To: Kristen James Eberlein <[email protected]>; DITA Technical Committee ([email protected]) <[email protected]> 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… f. From: [email protected] < [email protected] > On Behalf Of Kristen James Eberlein Sent: Tuesday, 17 January 2023 15:16 To: DITA Technical Committee ( [email protected] ) < [email protected] > 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 [email protected] 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