dita-ot 2.x: discover what's new in toolkit two

©2016 IBM Corporation

DITA-OT 2.x:

Discover What’s New in Toolkit TwoRobert D. Anderson, IBM April 4, 2016@robander

Content CoE and eSupport Services | ©2016 IBM CorporationDigital Services Group

Agenda

• Why are we here?

• Quick history lesson: DITA-OT 1.0 to 1.8.5

• DITA-OT 2.0: a vision for the future

• So, what’s different?

• DITA-OT 2.0, 2.1, 2.2

• Compatibility with older versions

• Why to upgrade

• What’s next?

2


What I expect you are expecting…

• From the conference agenda:

• What is new in DITA-OT 2.0, 2.1, and 2.2?

• I’ve heard some parts of 2.x are not backwards compatible –

should I be concerned?

• How should I prepare for a toolkit upgrade, and what resources

are available to help?

• What kind of support is available for older or current releases?

• What is planned for release 2.3 and beyond?

What am I missing?

3


What should I expect…?

• In the audience…

• Never used DITA-OT?

• Using 1.7 or earlier?

• Using 1.8.x?

• Using 2.0 or later?

• I expect you to ask questions when you have them

4


Why am I the one up here?

1. I’ve been working with the toolkit for a long time.

2. Jarno Elovirta is (most likely) at home coding.

• I also do a lot of DITA-based writing and programming

at IBM, with OASIS, with my kids**, and so on.

** “Daddy, why do you always put <child rev=“1”> </child> around my name?”

5


DITA-OT Development Process (Early days)

OK, yes, this is exaggerated.

There were a few of us.

6

Digital Services Group

Quick history lessonRelease timeline Highlights

Early 2005: DITA-OT 1.0

October 2006: DITA-OT 1.3

2007-2009: DITA-OT 1.4.x

2009-2011: DITA-OT 1.5.x

2012: DITA-OT 1.6

2014: DITA-OT 1.8

First official release, from IBM. “Just the scripts, please.”

Approximate introduction of PDF2, startcmd.bat

Excited about those major point releases!

Rollout of DITA 1.2 support

From now on, 3rd number = patch release

Last release to intentionally preserve most 1.0 legacy***

7


*** So what’s wrong with supporting legacy?

It represents a growing stack of Technical Debt

8


The hidden costs of technical debt

• Increased maintenance costs for

outdated functions

• Reduction in code quality over time

• Innovation is more difficult, if not impossible

• How do you build a jet pack if compatibility rules

mandate use of an existing coal based fuel system?

9


Which brings us to DITA-OT 1.8.x

10


So why create 2.0?

Image Courtesy NASA/JPL-Caltech

http://www.jpl.nasa.gov/visions-of-the-future/

11

We want jet packs.


You were not just promised a jet pack

• If you’d like to request one, please open an issue at

https://issues.dita-ot.org

12

https://issues.dita-ot.org/




To the futureDITA Open Toolkit 2.X


Even quicker history: DITA-OT 2.X

• DITA-OT 2.0 released at 1st DITA-OT Day,

November 2014

• DITA-OT 2.1 released June 2015

• DITA-OT 2.2 released at 2nd DITA-OT Day,

November 2015 (see photo of ACTUAL RELEASE)

Obviously if you miss DITA-OT Day this year, you will MISS SOMETHING BIG

14


Highlights: DITA-OT 2.0

• New dita command

• Preview support for DITA 1.3

• Increased processing speed,

particularly with PDF or with keys

• Bring code up to date (XSLT 2.0!)

• Clean out obsolete code

• This is what clears the way for our jet packs

Image Courtesy NASA/JPL-Caltech

15


But wait! There’s more!

See the release notes for complete list of 45 new features, including

• New HTML5 transform type

• Support for indexing in PDF using FOP

• Improved usability and error checking

• Parameters for common style preferences

• Better support for custom PDF back covers

• ….

16



• Mostly under-the-covers work

• Many smaller usability enhancements

• Remove the deprecated “Java command

line” interface

• Continued work on DITA 1.3

17



• Defaults to DITA 1.3 grammar files

• Support for DITA 1.3 features based

on the final standard

• Additional work on HTML5

• Updates to dita command

• Accepts URI for input file

• Install multiple plugins

• Plugins can specify new parameters

18


More highlights for 2.2

• Is anybody still using PDF?

• Not that it’s a steam engine or anything

• Many PDF updates, including

• Support for many new languages

(indexing, generated text)

• Support for args.artlbl (art label,

previously only used with HTML)

• Code refactoring for easier customization

• Removed default <note> finger

• Flagging now based on common pre-

process routine

19


It’s software, so there are some bug fixes

Release notes at dita-ot.org include any fix releases.

Release notes for 2.2 cover 2.2, 2.2.1, 2.2.2, …

20


Audience poll

• Would you trade a guarantee of compatibility for a promise of new function?

21


Cue the horror music…

Yes.

The rumors are true.

DITA-OT 2.0 is not backwards compatible

with all aspects of DITA-OT 1.X.

22


Cue the happy music…

• Your content will not break.

• Yes, your extensions could break. **

• More likely to be troublesome:

• Customizations to pre-process

• XSLT imports that do not use plugin: syntax

• Creative / unanticipated use of toolkit Java modules

** But many will not.

Editors note: photo at right really is a top result for the

search term “celebration” on the British Library’s public

domain Flickr stream. Really.

23


Audience poll

• Would you trade a guarantee of compatibility for a promise of new function,

when any incompatible changes will very likely go unnoticed?

24


The backwards compatibility trap…

• Why break compatibility?

• Reduce technical debt

• Encourage innovation

• Sometimes you just find a better way to do something

• Where did we not break compatibility (in 2.x)?

• Inconsistent parameter names / values

• Complicated PDF logic

• Still using Ant

• Maybe in 3.0, but compatibility is still a concern.

25


Audience poll

• Would you trade a guarantee of compatibility for a promise of new function?

• How about for a jet pack?

26


How to ease your upgrade

• If it’s all in your tools, let your vendor handle it?

• If you’re a tool vendor, get involved! Come to contributor calls!

• If you’re on your own:

• Always, if you can, isolate extensions to plug-ins.

• Try dropping them into a new version – see if they “just work”

• If they do not, or you get “deprecated” messages:

http://www.dita-ot.org/dev/dev_ref/migration.html

• If that still doesn’t help, find help on dita-ot-users google group

27





Support for published releases

Remember it’s open source, support comes from volunteers. But in general:

• Latest stable release (as of this writing, 2.2)

• No new features; expect patches with accumulated fixes; 2.2.4 out in next couple weeks

• Latest-minus-one (as of this writing, 2.1)

• No new features; patches unlikely, but possible for urgent issues

• Support for older releases

• Forums -- dita-ot-users (Google group), dita-users (Yahoo group)

• No patches planned

28


Support for not-even-published-yet releases

New as of March 2016, see dita-ot.org for the absolute latest and greatest:

http://www.dita-ot.org/download

29

• Follow the latest developments

• Try features before they are released

• Test upcoming versions





Future releases

• 2.3 expected in May

• More under-the-covers optimizations

• More HTML5 work

• More PDF work (indexing, NLS, FOP 2.0)

• 2.4 (or 3.0?) near end of year

• (Jet packs…?)

30


Want to know more?

Monthly DITA-OT Contributor calls: hosted by Syncro Soft, open to anyone

Monthly DITA-OT Docs calls: hosted by Eberlein Consulting, open to anyone

Github project: https://github.com/dita-ot/dita-ot/

Everything else at http://dita-ot.org

Get involved! Please!

** You are encouraged to compare this with the early development process.

31

https://github.com/dita-ot/dita-ot/





http://dita-ot.org/

http://dita-ot.org/

http://dita-ot.org/


Really want to know more?

• Learn what’s new, what’s coming, what everybody else is doing

• Come talk about what you are doing!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

(Submit your proposals! We want to hear from you! Lots of people do!)

• November 13, 2016, in Munich or online

32


Project resources

• Project page: http://dita-ot.org

• Github: https://github.com/dita-ot/dita-ot/

• Slack: https://dita-ot.slack.com/ (requires invite)

33

http://dita-ot.org/

http://dita-ot.org/

http://dita-ot.org/

http://dita-ot.org/







https://dita-ot.slack.com/




Useful external resources

• Recorded DITA-OT day sessions:

https://www.oxygenxml.com/events/2014/dita-ot_day.html


• Register for DITA-OT Day 2016:


• Migrating to new releases (latest in-progress docs):


• Migrating from startcmd to dita command:

http://metadita.org/toolkit/startcmd.html

34














http://metadita.org/toolkit/startcmd.html


Brand new super secret shortcut resources!

Maybe these are useful? If so, tell your friends!

If you’d like to keep your friends, just tell your co-workers!

• http://code.dita-ot.org redirects to http://github.com/dita-ot/dita-ot/

• http://issues.dita-ot.org redirects to http://github.com/dita-ot/dita-ot/issues/

• http://wiki.dita-ot.org redirects to http://github.com/dita-ot/dita-ot/wiki

(Used for contributor meeting minutes)

35

http://code.dita-ot.org/









http://issues.dita-ot.org/



http://github.com/dita-ot/dita-ot/issues/





http://wiki.dita-ot.org/



http://github.com/dita-ot/dita-ot/wiki






Image credits

Jetpack Image Courtesy NASA/JPL-Caltech


Old-time images from British Library Flickr stream

www.flickr.com/photos/britishlibrary/

36








http://www.flickr.com/photos/britishlibrary/


Conclusion: say thanks to this guy

DITA-OT owes its current success to Jarno Elovirta (from Wunderdog.fi)

Say thanks, or leave a Paypal tip:

https://github.com/jelovirt/dita-ot-markdown#donating

37

Wunderdog.fi

https://github.com/jelovirt/dita-ot-markdown







Question time…

• Unable or unwilling to migrate? What’s holding you back?

• Hopes and dreams for 2.X or 3.X?

• Other DITA-OT issues?

38

Thank you

Digital Services Group

dita-ot 2.x: discover what's new in toolkit two

Technology