Next in thread →
Next in month →
Re: [dita] Stage three: #29 Bookmap update -- Ready for TC consideration
Again, a new publication map is already on our list for DITA
2.0. I'm glad to hear that you would be interested in working on
it.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 12/3/2019 10:33 AM, Gershon Joseph
wrote:
If bookmap
is fundamentally flawed (which I cannot deny!), I strongly
suggest we develop a parallel new publication map in DITA
2.0, with documentation that the legacy bookmap will be
deprecated in DITA 3.0. Iâm happy to lead the effort on
the next-gen publication map, assuming I can gather
everyoneâs input and ideas.
Â
Kris, feel
free to add this item to a future agenda. If there is any
documentation on the known flaws of bookmap and ideas that
have been suggested for the new publication map, please
point me to them.
Â
Gershon
Â
From:
<>
on behalf of Kristen James Eberlein <>
Date: Tuesday, 3 December 2019 at 17:22
To: "Wegmann, Frank" <>,
""
<>
Subject: Re: [dita] Stage three: #29 Bookmap
update -- Ready for TC consideration
Â
Two other considerations here:
The TC hoped to include a new publication
map for DITA 2.0. Whether or not we will manage to do this
is an open question ...
Because we considered the design of bookmap
to be fundamentally flawed, we did not want to redesign
it. But because we know bookmap is used heavily, we wanted
to add some critical functionality. This is the rationale
for updating bookmap without breaking backwards
compatibility.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 12/3/2019 9:21 AM, Wegmann, Frank
wrote:
Hi
Kris et al.
Â
This
bookmap update is the first proposal Iâve read now.
Being new to the committee, I also wondered home some
decisions have been made, but then Kris confirmed my
suspicionsin her replies that it would be appropriate to
study the previous stage proposals before raising my
voice.
Â
What
I can say is that I generally appreciate the careful
stance on breaking backward compatibility. The less hard
the migration path, the less work it means to adapt
production and reeducate authors, if you have dozens of
them spread globally with hundreds of bookmaps, like we
do. Iâm sure Robert is very much aware of a
practitionerâs position like this.
Â
Of
course, progress needs to be made, and I especially
welcome the addition of ditavalref to the bookmap as
well as the introduction of the mapresources element.
And, furthermore, the improved specification text by
adding âProcessing expectationsâ.
Â
Thank
you for this extension of the bookmap!
Â
Frank
From:
<> On
Behalf Of Kristen James Eberlein
Sent: Monday, December 2, 2019 4:35 PM
To:
Subject: Re: [dita] Stage three: #29 Bookmap
update -- Ready for TC consideration
Â
Hi, Gershon.
Please see my comments below.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 12/2/2019 9:17 AM, Gershon Joseph
wrote:
Hi all,
Â
I have reviewed this proposal and
have a few comments (they are general comments not
specifically related to this proposal. Excuse me if any
of these things have been discussed in my absence from
the TC, in which case just refer me to the minutes or
other documentation.
Â
Point #1
This proposal does not state why the
change is being done. Whatâs the motivation for this
change? Whatâs the business case? I can think of a
couple, but I think the proposal should mention the
business or technical need driving the change. Then this
text could be lifted as-is to the documentation of the
standard, which should make life easier for the authors
of the eventual standard.
<kje>This is covered
in the stage two proposal. It would be good if you
familiarized yourself with the stage 1, stage 2, and
stage processes. We put considerable time in
implementing this new process for DITA 1.3 and
revising it for DITA 2.0; we are pretty satisfied with
it.
I'm very glad to see you
back participating on the TC, Gershon, but you will
have some catching up to do! We've changed a lot of
processes since I became chair.
See:
Stage two
proposal for #29:
https://lists.oasis-open.org/archives/dita/201910/msg00097.html
DITA 2.0
process:
https://wiki.oasis-open.org/dita/DITA_2.0_Proposal_Process_DRAFT
(ignore fact that URL contains the word DRAFT)
</kje>
Â
Point #2
Why are we concerned about keeping
backward compatibility in a major release? The TC has a
huge, once-in-a-lifetime opportunity to fix and improve
things that we could not do with any minor release of
the standard. If there is a better way to achieve the
desired outcome, I suggest we do it now and document any
backward incompatibility we introduce. Iâm concerned
about making the DTD files more complex simply for the
sake of backwards compatibility when weâre doing a major
release.
<kje>DITA 2.0 is our
very first backwards INCOMPATIBLE release. This has
scared many people in the committee. Accordingly, we
are committed to documenting backwards-incompatible
stuff carefully. We also consider how big of an impact
a change would have and whether it's worth it.
In general, we're doing a
whole lot of clean up and implementing a lot of
changes to previous design decisions that ended up
being less than optimal.</kje>
Â
Point #3
Point #2 is a good Segway into this
concern. The standard says the XSDs are the normative
standard, but our proposals talk about DTDs almost
exclusively. All of our content model discussions are
based on how to achieve the outcome via DTDs. If the XSD
schema is normative, letâs focus our discussion on the
XSD implementation and optimize that. At this time, the
XSDs are essentially reverse-engineered DTDs, and donât
take full opportunity of XSD functionality. For DITA 2.0
I feel strongly we should re-architect the XSDs to fully
embrace the schema functionality and best practices.
Many vendors have raised this concern with me, so itâs
not just me. <duck as Robert A throws a large heavy
object in my direction/>
Seriously, Iâm not undermining the
huge effort Robert and others put into the XSDs, I
really do appreciate it. What Iâm suggesting is we take
on an XSD re-architecture at this time before itâs too
late.
Â
<kje>Um ... No. You
are missing facts. RNG is the normative grammar and
has been so since 1.3. We will not be shipping XSDs
for DITA 2.0, unless someone steps forward to create
and test them. Firm decision made already by the
TC.</kje>
Â
Point #4
The formatting of figure titles is
confusing. I keep thinking the figure title is a figure
caption referring to the code sample above, due to the
lack of space above the title and huge space below. The
figure title actually refers to the figure below the
title. I know this is OASIS style, but please, please
letâs fix it!!
<kje>If
you have specific changes to suggest, I'll point you
to the relevant plug-in. It lives in a DITA TC Git
repo.</kje>
Â
Besides these gripes, I really like
this proposal and see how it will make life easier for
many users. I think weâd use it eventually at Mastercard
(my current client at Precision Content).
Â
This is a very well-written proposal.
Job well done!
<kje>Thanks.</kje>
Â
Gershon
Â
Â
From:
<>
on behalf of Kristen James Eberlein <>
Date: Sunday, 1 December 2019 at 16:43
To: DITA TC <>
Subject: [dita] Stage three: #29 Bookmap
update -- Ready for TC consideration
Â
This proposal has been reviewed by:
Nancy Harrison, Individual member
Eliot Kimber, Individual member
Eric Sirois, IXIASOFT
The PDF is attached; the DITA source is available at
http://tools.oasis-open.org/version-control/browse/wsvn/dita/trunk/DITA-2.0/stage-3/Issue-29-bookmap-update.dita
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
---------------------------------------------------------------------
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
Â
Software
AG â Sitz/Registered office: UhlandstraÃe 12,
64297 Darmstadt, Germany â
Registergericht/Commercial register: Darmstadt
HRB 1562 - Vorstand/Management Board: Sanjay
Brahmawar (Vorsitzender/Chairman), Dr. Elke
Frank, John Schweitzer, Dr. Stefan Sigg, Arnd
Zinnhardt; -
Aufsichtsratsvorsitzender/Chairman of the
Supervisory Board: Dr. Andreas Bereczky - http://www.softwareag.com
---------------------------------------------------------------------
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
Next in thread →
Next in month →