Meeting minutes 2015 02 03

Attendance: Radu, Jarno, Robert, Roger

Item 1: Any updates about prior releases?

Any concerns about 1.x, 2.0?

Robert unable to build fixpack 2.0.1, due to failures during doc build (jar and jar-plugins built fine). Jarno thinks Roger had similar errors. Jarno suggest maybe: when you run build, it runs integrator, that messes with JAR file. If you remove integrator path from one spot in build, it may work. Roger uncertain, it was a month ago. Roger remembers issues with CLASSPATH.

Assuming 2.0.1 is built properly, we will post to github. Radu asks about SourceForge downloads - at this point it is really an archive for older releases.

Radu asks why we have to rely on Windows machines - it's because we ship a CHM version of the docs in the Windows package. Popular if outdated format for help on Windows.

Jarno has a Windows machine that is very rarely turned on - may try it out and see if it reproduces the issues.

Jarno questions about 1.8: have a few requests for fixes, for items fixed in 2.0. Don't really want to close the issues, but Jarno not interested in fixing that older release. How do we feel about handling them? For feature requests they want in 1.8: we may likely do it in 2.0 but it's not what they asked for. We do have a tag "obsolete" that is used for things fixed in newer version. But, that sounds sort of off-putting to some people. Maybe a tag like "FixedInNewRelease"?

Jarno also thinking about a tag - "Unverified" - to indicate that we have not checked yet if it worked. Roger and Robert are OK with trying this out.

Item 2: DITA-OT 2.1 status and updates

DITA 1.3: still pushing forward at OASIS. Trying to finish subject scheme section this week. Branch filtering coming soon. Conditional processing was last week.

Jarno hasn't done too much new code for 2.1 in January - focus has been on Markdown plug-in. Still needs lot of work, but it's nice for reading in simple markdown and treating as DITA input. Thinking about putting this into core for 2.1 and releasing as first milestone. While working on this, found that classpath management is difficult, particularly with plugins. Would really like to keep classpath management out of DITA-OT. Command line tool will work out-of-the-box, but for running some other way, need to handle classpath manually. Don't like how it is done today, but it works.

Another update - changed plug-in parser to be DOM based instead of SAX based. So, code that reads plug-in information now has access to everything in plugin.xml. Came out of markdown work, the simple processing wasn't good enough. Also goes with idea that plugin code could just as easily be JSON or something similar in the future.

Item 3: Doc updates and plans

Radu has pull request for plugin parameter info. Once that is done, work on the XSLT that generates doc topics (one for each transform type). Discussed - could use branch filtering when implemented, but for now, not. Note: auto-generated topics should somehow make it clear that they are auto-generated, so that nobody tries to edit them. Putting in subdirectory would make for ugly paths / references. Each topic has a comment. Roger suggests, maybe autogen ones have "xml" extension and others use "dita". DITA also has <source> element in metadata that could be populated, something like <source>Generated by DITA-OT integrator</source>

Roger following up on question that came up in issue 1839, submitter trying to embed DITA-OT in his code. Jarno asked if we should doc how to do it, Roger following up - is that something we want to doc? Idea of taking DITA-OT, embedding in Java code? Is this something helpful to a lot of users? For Jarno it's normal. Problem is - a lot of people trying this do it wrong and get stuck, so would be at least as helpful to say how NOT to do it. Maybe some sort of small tutorial would be helpful, but we don't have tutorial section. Seems likely anybody doing this is already a developer, putting it in the developer section will probably be a good default.

Minor item: agreed at last call that we wouldn't reference the old devworks articles, but PDF version of user guide still has link. Topic: "Other DITA-OT resources" that links to external HTML items, and those IBM URI's are no longer valid. Will remove the links.

Item 4: Other topics

Question about configuration. We have conventions but also rules. Convention - anything with _template is a template to be processed; but we also make people list them. If we rely on convention - everything with that is processed, and you don't need to list it. But if we rely on convention, we really need to do a good job documenting it. Preference? Radu: could do both. Jarno: sort of like, if we have lib/ subdirectory, do we pick everything up? Today we have to list everything that gets added. So general question, when we add new features like these, have to decide whether to implement with configuration (update plugin.xml) or convention - which is preferred?

Right now almost everything is configuration. Don't even have a convention for naming Ant variables. [Discussed back in 1.6 timeframe, but didn't go forward]. Robert likes conventions - harder to mess up, easier to follow. But if we change to convention for (for example) _template files, probably need that to go in DITA-OT 3.0, as it's a pretty big shift - existing plugins that have unreferenced _template files would suddenly have them edited.