Sure, I’ll see through my calendar asap, and suggest timeslots that could suit us both. (Having all day booked for meetings today.)
It might be that I do not have answers to all your questions, so we may need to book a follow-up after I talk to the developers. A list of main questions beforehand might help, so that
I can check the details before our chat.
Thanks,
Ullakaisa
From:
dita-lightweight-dita@lists.oasis-open.org [mailto:
dita-lightweight-dita@lists.oasis-open.org]
On Behalf Of Carlos Evia
Sent: 09 January 2017 16:00
To: Ullakaisa Kalander <
Ullakaisa.Kalander@citec.com>
Cc:
dita-lightweight-dita@lists.oasis-open.org Subject: Re: [dita-lightweight-dita] Response to Deb Bi(ssantz's review (Was "Re: Fwd: LwDITA Draft document")
Dear Ullakaisa,
Thank you for the feedback. I wonder if we should have a chat/interview so I can report back to the subcommittee.
Our introductory LwDITA committee note sure can use scenarios like yours.
Best,
Carlos
On Jan 9, 2017, at 7:44 AM, Ullakaisa Kalander <
Ullakaisa.Kalander@citec.com > wrote:
Hi Kris and all,
We gathered some questions and observations about the LwDITA Draft document, and the available LW DITA documentation in general, seen from the implementation point of view.
--
p. 9, section 3.1– note is not included in the list
p. 10, section 3.2
> In XDITA
and HDITA
(the LwDITA authoring formats based on XML and HTML5, respectively), all text must be within paragraph ( <p> ) elements.
An exception is the short description <shortdesc>
element.
To avoid confusion, should all the exceptions be named here (according to the DTD files, at least <title> and <desc> should be similar cases)?
Do you think that we need to add here information about what block elements are part of Lightweight DITA? </kje>
For clarity, yes.
p. 10, section 3.3
> Content reference
The @conref
attribute is available only on the following elements:
Feedback from tool development: it is not clear why these decisions have been made, so further argumentation would be in place, as already suggested. Our question included:
·
Why is conref not available for all block-level content?
·
If <ul> and <ol>, why not <dl>?
·
Note is not mentioned, but is a very common use case for @conref?
·
(Current users of DITA may expect to see <ph> in this list as well - it may not be self-evident why the mechanism is now @keyref)
p. 21, Appendix A.1
typo: "Footnore"
<fnref> not included (NB. the aimed reference model is not yet documented clearly, so the implementation will follow)
p. 22
Appendix A.3
The type attribute (used in the note element) is not included in the attribute list
type (caution warning danger trouble notice note) "note"
These were our comments based on XDITA implementation (no specializations so far).
BR,
Ullakaisa
From:
dita-lightweight-dita@lists.oasis-open.org [ mailto:
dita-lightweight-dita@lists.oasis-open.org ]
On Behalf Of Kristen James Eberlein
Sent: 30 December 2016 18:40
To:
dita-lightweight-dita@lists.oasis-open.org Cc: DITA TC <
dita@lists.oasis-open.org >; Debra Bissantz <
dbissantz@healthwise.org >
Subject: [dita-lightweight-dita] Response to Deb Bissantz's review (Was "Re: Fwd: LwDITA Draft document")
Deb, thanks so very much for your thoughtful review. Please see my comments below.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype)
On 12/30/2016 11:04 AM, Kristen James Eberlein wrote:
FYI
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype)
-------- Forwarded Message --------
Subject:
LwDITA Draft document
Date:
Fri, 30 Dec 2016 15:42:51 +0000
From:
Debra Bissantz <
dbissantz@healthwise.org>
To:
Kristen James Eberlein
<
kris@eberleinconsulting.com>
Kris,
I looked over the document and have the following comments.
1.
Throughout the document, there is inconsistent use of LwDITA and Lightweight DITA.
<kje>Yes, Carlos Evia and I -- so far the only authors/editors -- have different preferences. Carlos likes to use the abbreviation, whereas I prefer to
spell it out. Obviously we'll need to settle this style point.</kje>
2.
Is LwDITA considered a stepping stone to full DITA? The document mentions that LwDITA is an entry point, but I don’t see any mention of how or when to move from LwDITA to
full DITA.
<kje>I would imagine that some folks will start and stay with Lightweight DITA. Others will start with Lightweight DITA and later move to full DITA in order
to have a wider range of elements and authoring options. Do you think that we need to address " how or when to move from LwDITA to full DITA" in this committee note? As
a voting TC member, would you like to know what the plan is for that regardless of whether it is content for the final committee note? </kje>
3.
P7, Section 2.1 – I agree with changing the title of section 2.1 to Simplified Structure.
<kje>Done.</kje>
4.
P10, Section 3.2 – The list of inline elements does not include underline or preformatted text. Is preformatted text a block element?
<kje>Have added underline to the list of inline elements. Yes, preformatted text (<pre>) is a block element; it is the specialization basis for <codeblock>.
Do you think that we need to add here information about what block elements are part of Lightweight DITA?</kje>
5.
P10, Section 3.3 – The list of element where @conref is supported include <li>. I wonder why if all <li> must have a <p> and @conref is supported on <p>.
<kje>I wasn't not involved in this decision, but I certainly see a use case for reusing a <li> element, especially as it might include multiple paragraphs
or a paragraph and a list or so forth.</kje>
6.
P12, Section 3.5 – If I am a new to DITA, I would find this section confusing or overwhelming. I understand the need for specialization, but as a beginner, I’m not sure that
I want to know about that at this point in the document. I think this section belongs in Section 5, where the information seems to be duplicated. You could include a reference to Section 5 from 3.
<kje>We might well want to reconsider the structure at a later date, but for now there are solid reasons for the organization:
The current audience is very much the voting members of the DITA TC and other experienced DITA users. Obviously, that will change at a later point in the development of the
committee note, but right now the committee note is serving to lead us towards a formal proposal for Lightweight DITA.
All the topics in section 3 are intended to touch on the fundamental design points of Lightweight DITA, which certainly includes a different specialization model than full DITA.
The plan for section 5 is to include the following items (not the current content, which is a simple cut-and-paste from Lightweight DITA GitHub repo):
Brief description of the template-based specialization model
Example of a simple Lightweight DITA topic that would be input to a tool
Example of the generated grammar file
General description of the algorithm that a tool would use to construct the grammar file for a specialization</kje>
7.
P16, Section 4.2.1 – Typo in 3 rd bullet, I think (MS) should be (LMS).
<kje>Done</kje>
8.
P19, Section 5 – This section duplicates section 3.5. I think all of the specialization information should be in one place.
9.
P24, Section A.3 – Does LwDITA rely on the @class attribute? It is not in the table of attributes.
Let me know if you have any questions or need further explanations.
Deb Bissantz
Technical Communication Architect/Writer
dbissantz@healthwise.org www.healthwise.org 208.331.8729 office
Healthwise helps people make better health decisions
--------------------------------------------------------------------- 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 --------------------------------------------------------------------- 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