Date   

[ANN] Release of XMLmind XML Editor v9.2 #XMLmind

Hussein Shafie
 

Release of XMLmind XML Editor v9.2. Highlights:

* When converting DITA, DocBook or an Ebook to any (X)HTML based format (EPUB, Web Help, etc), the generated HTML pages looks much better than before. Moreover the generated Web Help is now “responsive” by default.

* New add-on "Paste from Word Processor or Browser", now installed by default whatever the platform, supersedes the previous add-on which was called "Paste from Word".

This add-on adds an entry called "Paste from Word Processor or Browser" to the "Paste As" submenu found in the XHTML, DocBook or DITA Topic menus. This menu entry imports the HTML copied to the clipboard by word processors or web browsers and intelligently pastes it into the XML document being edited.

* Updated many software components.

* Now officially supported on Java™ 13 platforms and on macOS Catalina (10.15).

More information in https://www.xmlmind.com/xmleditor/changes.html

---------------------------
What is XMLmind XML Editor?

https://www.xmlmind.com/xmleditor/

Personal Edition is free to use by many persons and organizations

https://www.xmlmind.com/xmleditor/download.shtml


Performance issues after updating to 3.4 from 1.5.4 #DITA-OT

Mario Di Giacomo
 

I recently completed porting our 1.5.4 PDF plugin to use 3.4, and while we have duplicated the functionality (indeed, actually improved it slightly) there has been a serious performance hit.  When building our full documentation set, what used to take 9 hours now takes closer to 24 hours.  When I use a logger to check timing on individual documents, I see things like the gen-list step going from a 1 minute duration in 1.5.4 to 10 minutes in 3.4

My analyses suggest that the problem is with the link-crawl argument.  It appears to not only evaluate conrefs within a given ditamap book, but also links across books.  The desired behavior is to only evaluate the title of these documents, but not the links within.

Is there something I can do to debug this?  I've tracked it as far as the Java call, but no further.


Re: Adding "next topic", "previous topic" throughout an entire map? #HTML #linking

Chris Papademetrious
 

Indeed, that was embarrassingly easy!

However, there might be a bug. When I make the entire map a collection sequence:

<map collection-type="sequence">
  <title>This Book</title>

  <topicref href="t1/topic0.dita">
    <topicref href="t1/topic1.dita"/>
    <topicref href="t1/topic2.dita"/>  <!-- this one has no Next Topic link -->
  </topicref>

  <topicref href="t2/topic0.dita">
    <topicref href="t2/topic1.dita"/>
    <topicref href="t2/topic2.dita"/>
  </topicref>

  <topicref href="t3/topic0.dita">
    <topicref href="t3/topic1.dita"/>
    <topicref href="t3/topic2.dita"/>
  </topicref>

</map>

then the highlighted topic has no "Next Topic" link to the next top-level topic reference. Since all of these top-level topic references fall under the same collection sequence, navigation should continue throughout the sequence.

Is there some special case for top-level topic elements to be excluded from collection-sequence processing? If not, I'll file a DITA-OT issue for this.

Thank you!

 - Chris


Re: Where do YOU go for high-quality information about DITA? #resources

Julio J Vazquez
 

I'll also mention that some of what you're looking for is in Elliot's DITA for Practitioners. Yes there probably needs to be more, but using that as a reference and this group as a resource can help you greatly. 

Julio J. Vazquez


Re: Upgrading to latest version of DITA O-T and PDF build failing #PDF

Kevin Quinn
 

Hi Radu,

When I sent out my email I eventually found some guidance/help on google an old thread. I knew it was about my CLASSPATH and I was looking at the env.bat script and I decided to update my CLASSPATH with

CLASSPATH C:\dita-ot-3.4\lib\ant-launcher.jar;C:\dita-ot-3.4\plugins\org.dita.index\lib\index.jar

So now it works just have a hiccup at end

: Warning: Could not find file C:\users\kquinn\Documents\DitaOutput\augusta\7.1\platform\7.1\INT-7.1-ReleaseNotes\pdf\platform_7101_release_notes.pdf to copy

Our customizations should send output to C:\users\kquinn\Documents\DitaOutput\augusta\7.1\platform\7.1\INT-7.1-ReleaseNotes\pdf\
however PDF is generated but to different directory

C:\Users\kquinn\Documents\DitaOutput

More to investigate - trial and error for me.

I will also add the one you state below - though did work with above.

Migrating to dita command is something I thought about but I wanted to keep all our original ANT customizations (main build file calls multiple customized XML files.

K

-----Original Message-----
From: dita-users@groups.io <dita-users@groups.io> On Behalf Of Radu Coravu
Sent: 14 January 2020 05:49
To: dita-users@groups.io
Subject: Re: [dita-users] Upgrading to latest version of DITA O-T and PDF build failing #PDF

Hi Kevin,

The "dita" command takes care to contribute to the ANT classpath all the necessary libraries contributed by all plugins when the process starts.
You can look in the "DITA-OT/config/env.bat" script to find references to all JAR libraries which will be used by the started "dita" process.

So if you run ANT manually you will need to add extra JAR libraries to the classpath, for example this JAR library below is the one containing the "IndexPreprocessorTask" class:

DITA-OT/plugins/org.dita.pdf2/lib/fo.jar

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 1/13/2020 10:50 AM, kevin.quinn@... wrote:
Hi All,

We are running a very old version of DITA 1.5.2 and I am trying to
upgrade to DITA 3.4.

I have some success at editing the 3.4 PDF transform (creating custom
one) to create PDF output we have in DITA 1.5.2.

Our implementation was heavily customized with the ant build file
calling various custom properties other build files.

In the first case I am trying to generate a PDF. The ditamap which
works fine with the dita command.

for example:

C:\dita-ot-3.4\bin\dita -v -d
--input=platform_7101_release_notes.ditamap --format=enea_opwv-pdf

Running the ant command calling the legacy build script seems to run
OK (calling correct custom properties files) until a point where it
references the C:\dita-ot-3.4\plugins\org.dita.index\build.xml

and it fails with

taskdef class org.dita.index.IndexPreprocessorTask cannot be found
using the classloader AntClassLoader[]

I am not sure what this means - any help appreciated. Done various
goggling but cannot find answer.

We normally run on Linux env but here I am executing the command on
Windows 10 is there something I need to set in CLASSPATH ?



Kevin






This message, including attachments, is CONFIDENTIAL. It may also be privileged or otherwise protected by law. If you received this email by mistake please let us know by reply and then delete it from your system; you should not copy it or disclose its contents to anyone. All messages sent to and from Enea may be monitored to ensure compliance with internal policies and to protect our business. Emails are not secure and cannot be guaranteed to be error free as they can be intercepted, a mended, lost or destroyed, or contain viruses. The sender therefore does not accept liability for any errors or omissions in the contents of this message, which arise as a result of email transmission. Anyone who communicates with us by email accepts these risks.


Re: Odd results with glossary elements and PDF generation #glossary #PDF

Radu Coravu
 

Hi Dan,

I updated the DITA content of our Oxygen user's guide to state that the print="yes" attribute must be set on the glossref so the next version of Oxygen will come with the updated documentation.

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 1/14/2020 7:36 AM, Dan Vint wrote:
Thanks that did the trick. It would help to put a note in your doc on handling this for PDF. https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/dita-creating-glossary.html I'm sort of surprised that print=no takes the keys out of processing like this. Should somehow be don't print but keep the definition so any use in <term>s would still work.
I'm not sure what happened, I had the content marked that way while working in the file system. I imported into a CMS and things changed.
-----Original Message-----
From: dita-users@groups.io <dita-users@groups.io> On Behalf Of Radu Coravu
Sent: Sunday, January 12, 2020 10:38 PM
To: dita-users@groups.io
Subject: Re: [dita-users] Odd results with glossary elements and PDF generation
Hi Dan,
You need to explicitly set the "print='yes'" attribute on the glossref:
https://github.com/dita-ot/dita-ot/issues/3328
Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
On 1/10/2020 10:03 PM, Dan Vint wrote:
I've been following the instructions for using the glossary elements
https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/dita-crea
ting-glossary.html

This all works perfectly for HTML output. When I produce the
associated PDF file though it fails. In the OT log I'm getting

[keyref]
file:/opt/ixiasoft/outgen/temp/Dita2Pdf.danvint.15080.1578671565937/content/authoring/npf1578670232926.dita:11:29:
[DOTJ047I][INFO] Unable to find key definition for key reference
"gAdapter" in root scope. The href attribute may be used as fallback
if it exists
[keyref]
file:/opt/ixiasoft/outgen/temp/Dita2Pdf.danvint.15080.1578671565937/content/authoring/npf1578670232926.dita:12:33:
[DOTJ047I][INFO] Unable to find key definition for key reference
"gCertificate" in root scope. The href attribute may be used as
fallback if it exists
[keyref]
file:/opt/ixiasoft/outgen/temp/Dita2Pdf.danvint.15080.1578671565937/content/authoring/npf1578670232926.dita:13:32:
[DOTJ047I][INFO] Unable to find key definition for key reference
"gExtensible" in root scope. The href attribute may be used as
fallback if it exists


My topic has this content as a test

<p>We have a glossary that can be linked to with &lt;term
keyref="gloss_ddl" />. We have terms like

<termkeyref="gAdapter"/>and

<termkeyref="gCertificate"/>and

<termkeyref="gExtensible"/>and

<termkeyref="gOpenid"/>and

<termkeyref="gPKI"/> as well as

<termkeyref="gWebservice"/>.</p>


I also have a map for the formal glossary content that uses the same keys


<topicref keyref="gAdapter" />

<topicref keyref="gCertificate" />

<topicref keyref="gExtensible"/>

<topicref keyref="gOpenid" />

<topicref keyref="gPKI" />

<topicref keyref="gWebservice" />


These are not found either.


I have a separate map with the definitions


<glossref keyref="vjp1572627554113" keys="gAdapter" />

<glossref keyref="pof1572627554169" keys="gCertificate" />

<glossref keyref="adv1572627554227" keys="gExtensible" />

<glossref keyref="sui1572627554285" keys="gOpenid" />

<glossref keyref="oom1572627554342" keys="gPKI" />

<glossref keyref="ikt1572627554399" keys="gWebservice" />


It seems like the key processing in PDF is not using the glossrefs properly.




Re: Upgrading to latest version of DITA O-T and PDF build failing #PDF

Radu Coravu
 

Hi Kevin,

The "dita" command takes care to contribute to the ANT classpath all the necessary libraries contributed by all plugins when the process starts.
You can look in the "DITA-OT/config/env.bat" script to find references to all JAR libraries which will be used by the started "dita" process.

So if you run ANT manually you will need to add extra JAR libraries to the classpath, for example this JAR library below is the one containing the "IndexPreprocessorTask" class:

DITA-OT/plugins/org.dita.pdf2/lib/fo.jar

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 1/13/2020 10:50 AM, kevin.quinn@... wrote:
Hi All,
We are running a very old version of DITA 1.5.2 and I am trying to upgrade to DITA 3.4.
I have some success at editing the 3.4 PDF transform (creating custom one) to create PDF output we have in DITA 1.5.2.
Our implementation was heavily customized with the ant build file calling various custom properties other build files.
In the first case I am trying to generate a PDF. The ditamap which works fine with the dita command.
for example:
C:\dita-ot-3.4\bin\dita -v -d --input=platform_7101_release_notes.ditamap --format=enea_opwv-pdf
Running the ant command calling the legacy build script seems to run OK (calling correct custom properties files) until a point where it references the C:\dita-ot-3.4\plugins\org.dita.index\build.xml
and it fails with
taskdef class org.dita.index.IndexPreprocessorTask cannot be found using the classloader AntClassLoader[]
I am not sure what this means - any help appreciated. Done various goggling but cannot find answer.
We normally run on Linux env but here I am executing the command on Windows 10 is there something I need to set in CLASSPATH ?
Kevin


Re: Odd results with glossary elements and PDF generation #glossary #PDF

Dan Vint
 

Thanks that did the trick. It would help to put a note in your doc on handling this for PDF. https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/dita-creating-glossary.html I'm sort of surprised that print=no takes the keys out of processing like this. Should somehow be don't print but keep the definition so any use in <term>s would still work.

I'm not sure what happened, I had the content marked that way while working in the file system. I imported into a CMS and things changed.

-----Original Message-----
From: dita-users@groups.io <dita-users@groups.io> On Behalf Of Radu Coravu
Sent: Sunday, January 12, 2020 10:38 PM
To: dita-users@groups.io
Subject: Re: [dita-users] Odd results with glossary elements and PDF generation

Hi Dan,

You need to explicitly set the "print='yes'" attribute on the glossref:

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

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 1/10/2020 10:03 PM, Dan Vint wrote:
I've been following the instructions for using the glossary elements
https://www.oxygenxml.com/doc/versions/21.1/ug-editor/topics/dita-crea
ting-glossary.html

This all works perfectly for HTML output. When I produce the
associated PDF file though it fails. In the OT log I'm getting

[keyref]
file:/opt/ixiasoft/outgen/temp/Dita2Pdf.danvint.15080.1578671565937/content/authoring/npf1578670232926.dita:11:29:
[DOTJ047I][INFO] Unable to find key definition for key reference
"gAdapter" in root scope. The href attribute may be used as fallback
if it exists
[keyref]
file:/opt/ixiasoft/outgen/temp/Dita2Pdf.danvint.15080.1578671565937/content/authoring/npf1578670232926.dita:12:33:
[DOTJ047I][INFO] Unable to find key definition for key reference
"gCertificate" in root scope. The href attribute may be used as
fallback if it exists
[keyref]
file:/opt/ixiasoft/outgen/temp/Dita2Pdf.danvint.15080.1578671565937/content/authoring/npf1578670232926.dita:13:32:
[DOTJ047I][INFO] Unable to find key definition for key reference
"gExtensible" in root scope. The href attribute may be used as
fallback if it exists


My topic has this content as a test

<p>We have a glossary that can be linked to with &lt;term
keyref="gloss_ddl" />. We have terms like

<termkeyref="gAdapter"/>and

<termkeyref="gCertificate"/>and

<termkeyref="gExtensible"/>and

<termkeyref="gOpenid"/>and

<termkeyref="gPKI"/> as well as

<termkeyref="gWebservice"/>.</p>


I also have a map for the formal glossary content that uses the same keys


<topicref keyref="gAdapter" />

<topicref keyref="gCertificate" />

<topicref keyref="gExtensible"/>

<topicref keyref="gOpenid" />

<topicref keyref="gPKI" />

<topicref keyref="gWebservice" />


These are not found either.


I have a separate map with the definitions


<glossref keyref="vjp1572627554113" keys="gAdapter" />

<glossref keyref="pof1572627554169" keys="gCertificate" />

<glossref keyref="adv1572627554227" keys="gExtensible" />

<glossref keyref="sui1572627554285" keys="gOpenid" />

<glossref keyref="oom1572627554342" keys="gPKI" />

<glossref keyref="ikt1572627554399" keys="gWebservice" />


It seems like the key processing in PDF is not using the glossrefs properly.




Re: Where do YOU go for high-quality information about DITA? #resources

Radu Coravu
 

Hi Mica,

Right, that's what I'm currently doing for the Oxygen XML Blog, it's a public GitHub project:

https://github.com/oxygenxml/blog

It contains a Gradle script to build WebHelp responsive from it:

https://github.com/oxygenxml/blog/blob/master/build/build.gradle

and it gets automatically published to Netlify whenever I make changes to it:

https://oxygenxmlblog.netlify.com/topics/welcome.html

Each HTML page as an "Edit online" link which uses Oxygen WebAuthor for editing and also a feedback form at the end of the page which uses our new Oxygen Feedback.

People who want to contribute new articles can open pull requests which when accepted will cause the web site to automatically refresh and presents the new content.

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com

On 1/13/2020 7:49 PM, Mica Semrick wrote:
Instead of a wiki, why not start a github repo full of dita content about dita?
You can like the oxygen web editor to it for free.
On January 13, 2020 4:59:14 AM PST, Chris Papademetrious <chrispitude@...> wrote:
OMG Chris, *this this this this*! Your post is right on the money
and describes my own experience perfectly. Thanks for taking the
time to write it up.
[copy and paste his response as mine here]
 - Chris
P.S. My wiki suggestion was so I could make this hard-won
"info-in-the-middle" knowledge available to others before moving on
to the next urgent task.
On Mon, Jan 13, 2020 at 6:25 AM despopoulos_chriss via Groups.Io
<despopoulos_chriss=yahoo.com@groups.io
<mailto:yahoo.com@groups.io>> wrote:
If I need information about a specific element, I go to the
spec.  For information about how DITA works in my current tool,
I go to the tool docs.  For XSLT information I go to WWW.org
<https://groups.io/g/dita-users/message/WWW.org> and
stackoverflow.  To use the OT, I go to the OT docs (thanks
guys!), but the authoring tool I use hides the OT from me, so
its been a while.  These are all good sources for using the
specific tools at my disposal (assuming DITA is itself a tool). But there's a level of information that is hard to put
together...  How these tools all work together to make a
publishing chain. Hot to implement best practices, and why.
There's lots of documentation about what DITA is, how to think
about using it, and various guidelines for authors.  The specs
describe what a DITA implementation must support.  What's
missing is documentation in the middle.  There are a few blogs
and even maybe books that bring the specs a little bit closer to
the human scale, but not much closer in my experience.  Unless
you want to devote your career to learning this stuff
(basically, implementing it yourself to learn what works and
what doesn't), it seems there isn't much help.  I think this is
for two reasons, which center on the level of expertise you need
to get to know this stuff:
Cynical Reason:  After investing in this knowledge, you want to
make money, not friends (ok, pretty harsh...  bear with me). One obvious direction to take this knowledge is into a product
that codifies the knowledge.  This actually provides a service
in that it shields the average user from needing to know.  The
hope is that users will rely on your product, and let you take
care of the knowledge.  You have little motivation to tell all
because it encourages competition.  And an effort in sharing
knowledge takes away from resources you could pour into R&D. Which brings up the noble reason...
Noble Reason: Time spent sharing knowledge is time not spent
applying your hard-won knowledge or acquiring new knowledge. Even so, some noble people have tried to lay out their
discoveries.  Sadly, the information I have found at this level
assumes a knowledge of the spec that is so intimate that you
probably wouldn't need the blog entry or whatever it is you're
reading.  And why should somebody who is pushing her knowledge
to the envelope stop and meticulously think through the didactic
issues that need to be addressed to bring everybody else along?
For a person on a deadline who is implementing a DITA workflow
as just a small part of her or his overall job, there's no time
to work out the knowledge.  And in many cases there is no money
to hire a specialist.  If you want DITA to reach down to a level
below mega-enterprise, you have to accept that.  I can tell you
this from experience.  As a result of my ongoing ignorance, we
have implemented some things that are plain wrong, or at least
not optimal.  But we're too invested in them now to suddenly fix
them.  And anyway, who has the time to do it?  Pain could have
been spared with more obvious access to this info-in-the-middle
sort of content.
So that's an appeal on my part...  What, why, how is a
template?  What is the motivation behind the relative locations
of maps vs topics?  I'm sure I can think of other questions that
are open for me, but in fact, I don't have time...  Gotta get to
work!  Bottom line, I'm saying there's a lack of documentation
in the middle.  I have given up looking for it.


Re: Adding "next topic", "previous topic" throughout an entire map? #HTML #linking

Kristen James Eberlein
 

Set collection-type="sequence" on the <map> element.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 1/13/2020 1:40 PM, Chris Papademetrious wrote:
Hi all,

I've embarrassingly spent half a day trying to figure this out! For the DITA-OT html5 transformation, is there a way to add "next topic" and "previous topic" links throughout the entire map, such that the map can be traversed from beginning to end using them?

The use case is that when we run FrameMaker-to-DITA conversion, the writers must step through every topic to evaluate whether the chunking is acceptable. I've been looking through XSLT code trying to figure out how to do this with existing parameters, but to no avail.

 - Chris


Re: Hashtags #admin

Kristen James Eberlein
 

Hi, David.

Right now, moderators apply hashtags -- and create new ones when needed. If we open up this policy, we'll certainly consider what you suggest.

Moderators can edit topic titles to apply hashtags after an e-mail is sent.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 1/13/2020 2:04 PM, David H wrote:
Hi,

I've just looked at dita-users@groups.io, and seen that there are 30 Hashtags in use.

I think this is a great idea, and a very useful departure from what was available on Yahoo. To be useful, though, folks need to use them!

I'm a member of a couple of other groups on groups.io, and these groups send out a monthly 'Group Guidelines'. I'm pretty sure that this group does not need such a reminder, however, I thought it might be useful to regularly remind folks which Hashtags are available. It would also put the list in everyone's inbox, nice and handy.

Would that be an idea?

HTH,
David



Re: Where do YOU go for high-quality information about DITA? #resources

Joe Williams
 

This list is the first (and often only) stop. Subscribers include the technical committee, DITA-OT developers, vendors, consultants. This is the place to get a question answered or to get pointed to an authoritative source.


Re: Hashtags #admin

 

I agree, but it should be easier to add hashtags after the fact. (or maybe I'm just clueless? <grin> )


On Mon, Jan 13, 2020 at 12:04 PM David H <djbhollis@...> wrote:
Hi,

I've just looked at dita-users@groups.io, and seen that there are 30 Hashtags in use.

I think this is a great idea, and a very useful departure from what was available on Yahoo. To be useful, though, folks need to use them!

I'm a member of a couple of other groups on groups.io, and these groups send out a monthly 'Group Guidelines'. I'm pretty sure that this group does not need such a reminder, however, I thought it might be useful to regularly remind folks which Hashtags are available. It would also put the list in everyone's inbox, nice and handy.

Would that be an idea?

HTH,
David




--
Grant Hogarth 
Technical Writer, SA Tools
Workiva Inc. 
1700 Platte St, Suite 200, Denver, Colorado 80202 
Mobile: 1-801-815-8353 


Hashtags #admin

David H
 

Hi,

I've just looked at dita-users@groups.io, and seen that there are 30 Hashtags in use.

I think this is a great idea, and a very useful departure from what was available on Yahoo. To be useful, though, folks need to use them!

I'm a member of a couple of other groups on groups.io, and these groups send out a monthly 'Group Guidelines'. I'm pretty sure that this group does not need such a reminder, however, I thought it might be useful to regularly remind folks which Hashtags are available. It would also put the list in everyone's inbox, nice and handy.

Would that be an idea?

HTH,
David


Adding "next topic", "previous topic" throughout an entire map? #HTML #linking

Chris Papademetrious
 

Hi all,

I've embarrassingly spent half a day trying to figure this out! For the DITA-OT html5 transformation, is there a way to add "next topic" and "previous topic" links throughout the entire map, such that the map can be traversed from beginning to end using them?

The use case is that when we run FrameMaker-to-DITA conversion, the writers must step through every topic to evaluate whether the chunking is acceptable. I've been looking through XSLT code trying to figure out how to do this with existing parameters, but to no avail.

 - Chris


Re: Where do YOU go for high-quality information about DITA? #resources

Mica Semrick
 

Instead of a wiki, why not start a github repo full of dita content about dita?

You can like the oxygen web editor to it for free.


On January 13, 2020 4:59:14 AM PST, Chris Papademetrious <chrispitude@...> wrote:
OMG Chris, this this this this! Your post is right on the money and describes my own experience perfectly. Thanks for taking the time to write it up.

[copy and paste his response as mine here]

 - Chris

P.S. My wiki suggestion was so I could make this hard-won "info-in-the-middle" knowledge available to others before moving on to the next urgent task.



On Mon, Jan 13, 2020 at 6:25 AM despopoulos_chriss via Groups.Io <despopoulos_chriss=yahoo.com@groups.io> wrote:
If I need information about a specific element, I go to the spec.  For information about how DITA works in my current tool, I go to the tool docs.  For XSLT information I go to WWW.org and stackoverflow.  To use the OT, I go to the OT docs (thanks guys!), but the authoring tool I use hides the OT from me, so its been a while.  These are all good sources for using the specific tools at my disposal (assuming DITA is itself a tool).  But there's a level of information that is hard to put together...  How these tools all work together to make a publishing chain. Hot to implement best practices, and why.

There's lots of documentation about what DITA is, how to think about using it, and various guidelines for authors.  The specs describe what a DITA implementation must support.  What's missing is documentation in the middle.  There are a few blogs and even maybe books that bring the specs a little bit closer to the human scale, but not much closer in my experience.  Unless you want to devote your career to learning this stuff (basically, implementing it yourself to learn what works and what doesn't), it seems there isn't much help.  I think this is for two reasons, which center on the level of expertise you need to get to know this stuff:

Cynical Reason:  After investing in this knowledge, you want to make money, not friends (ok, pretty harsh...  bear with me).  One obvious direction to take this knowledge is into a product that codifies the knowledge.  This actually provides a service in that it shields the average user from needing to know.  The hope is that users will rely on your product, and let you take care of the knowledge.  You have little motivation to tell all because it encourages competition.  And an effort in sharing knowledge takes away from resources you could pour into R&D.  Which brings up the noble reason...

Noble Reason: Time spent sharing knowledge is time not spent applying your hard-won knowledge or acquiring new knowledge.  Even so, some noble people have tried to lay out their discoveries.  Sadly, the information I have found at this level assumes a knowledge of the spec that is so intimate that you probably wouldn't need the blog entry or whatever it is you're reading.  And why should somebody who is pushing her knowledge to the envelope stop and meticulously think through the didactic issues that need to be addressed to bring everybody else along? 

For a person on a deadline who is implementing a DITA workflow as just a small part of her or his overall job, there's no time to work out the knowledge.  And in many cases there is no money to hire a specialist.  If you want DITA to reach down to a level below mega-enterprise, you have to accept that.  I can tell you this from experience.  As a result of my ongoing ignorance, we have implemented some things that are plain wrong, or at least not optimal.  But we're too invested in them now to suddenly fix them.  And anyway, who has the time to do it?  Pain could have been spared with more obvious access to this info-in-the-middle sort of content. 

So that's an appeal on my part...  What, why, how is a template?  What is the motivation behind the relative locations of maps vs topics?  I'm sure I can think of other questions that are open for me, but in fact, I don't have time...  Gotta get to work!  Bottom line, I'm saying there's a lack of documentation in the middle.  I have given up looking for it.


Upgrading to latest version of DITA O-T and PDF build failing #PDF

Kevin Quinn
 

Hi All,

 

We are running a very old version of DITA 1.5.2 and I am trying to upgrade to DITA 3.4.

 

I have some success at editing the 3.4 PDF transform (creating custom one) to create PDF output we have in DITA 1.5.2. 

 

Our implementation was heavily customized with the ant build file calling various custom properties other build files.

 

In the first case I am trying to generate a PDF. The ditamap which works fine with the dita command.

 

for example:

C:\dita-ot-3.4\bin\dita -v -d --input=platform_7101_release_notes.ditamap --format=enea_opwv-pdf

 

Running the ant command calling the legacy build script seems to run OK (calling correct custom properties files) until a point where it references the C:\dita-ot-3.4\plugins\org.dita.index\build.xml

 

and it fails with 

 

taskdef class org.dita.index.IndexPreprocessorTask cannot be found using the classloader AntClassLoader[]

 

I am not sure what this means - any help appreciated. Done various goggling but cannot find answer.

 

We normally run on Linux env but here I am executing the command on Windows 10 is there something I need to set in CLASSPATH ?



Kevin


Re: Where do YOU go for high-quality information about DITA? #resources

Chris Papademetrious
 

OMG Chris, this this this this! Your post is right on the money and describes my own experience perfectly. Thanks for taking the time to write it up.

[copy and paste his response as mine here]

 - Chris

P.S. My wiki suggestion was so I could make this hard-won "info-in-the-middle" knowledge available to others before moving on to the next urgent task.



On Mon, Jan 13, 2020 at 6:25 AM despopoulos_chriss via Groups.Io <despopoulos_chriss=yahoo.com@groups.io> wrote:
If I need information about a specific element, I go to the spec.  For information about how DITA works in my current tool, I go to the tool docs.  For XSLT information I go to WWW.org and stackoverflow.  To use the OT, I go to the OT docs (thanks guys!), but the authoring tool I use hides the OT from me, so its been a while.  These are all good sources for using the specific tools at my disposal (assuming DITA is itself a tool).  But there's a level of information that is hard to put together...  How these tools all work together to make a publishing chain. Hot to implement best practices, and why.

There's lots of documentation about what DITA is, how to think about using it, and various guidelines for authors.  The specs describe what a DITA implementation must support.  What's missing is documentation in the middle.  There are a few blogs and even maybe books that bring the specs a little bit closer to the human scale, but not much closer in my experience.  Unless you want to devote your career to learning this stuff (basically, implementing it yourself to learn what works and what doesn't), it seems there isn't much help.  I think this is for two reasons, which center on the level of expertise you need to get to know this stuff:

Cynical Reason:  After investing in this knowledge, you want to make money, not friends (ok, pretty harsh...  bear with me).  One obvious direction to take this knowledge is into a product that codifies the knowledge.  This actually provides a service in that it shields the average user from needing to know.  The hope is that users will rely on your product, and let you take care of the knowledge.  You have little motivation to tell all because it encourages competition.  And an effort in sharing knowledge takes away from resources you could pour into R&D.  Which brings up the noble reason...

Noble Reason: Time spent sharing knowledge is time not spent applying your hard-won knowledge or acquiring new knowledge.  Even so, some noble people have tried to lay out their discoveries.  Sadly, the information I have found at this level assumes a knowledge of the spec that is so intimate that you probably wouldn't need the blog entry or whatever it is you're reading.  And why should somebody who is pushing her knowledge to the envelope stop and meticulously think through the didactic issues that need to be addressed to bring everybody else along? 

For a person on a deadline who is implementing a DITA workflow as just a small part of her or his overall job, there's no time to work out the knowledge.  And in many cases there is no money to hire a specialist.  If you want DITA to reach down to a level below mega-enterprise, you have to accept that.  I can tell you this from experience.  As a result of my ongoing ignorance, we have implemented some things that are plain wrong, or at least not optimal.  But we're too invested in them now to suddenly fix them.  And anyway, who has the time to do it?  Pain could have been spared with more obvious access to this info-in-the-middle sort of content. 

So that's an appeal on my part...  What, why, how is a template?  What is the motivation behind the relative locations of maps vs topics?  I'm sure I can think of other questions that are open for me, but in fact, I don't have time...  Gotta get to work!  Bottom line, I'm saying there's a lack of documentation in the middle.  I have given up looking for it.


Re: How can we make use of the 'wiki' feature of groups.io? #admin

Chris Papademetrious
 

Hi Ron,

My suggestion to use the Wiki functionality has two important differentiating aspects:

  • We all visit this group often (versus being spread out across the Internets).
    • The information is available where the activity is, which also encourages discussion answers to be migrated to Wiki best-practice posts.
  • We can all contribute, update, and correct (versus the information being read-only).
I see plenty of outdated information about DITA on the Internet and many times I'm willing to update it but unable to do. Per Ron's observation that we're a community of technical writers, let's empower ourselves to make use of that skill set.

 - Chris



Re: Where do YOU go for high-quality information about DITA? #resources

despopoulos_chriss
 

If I need information about a specific element, I go to the spec.  For information about how DITA works in my current tool, I go to the tool docs.  For XSLT information I go to WWW.org and stackoverflow.  To use the OT, I go to the OT docs (thanks guys!), but the authoring tool I use hides the OT from me, so its been a while.  These are all good sources for using the specific tools at my disposal (assuming DITA is itself a tool).  But there's a level of information that is hard to put together...  How these tools all work together to make a publishing chain. Hot to implement best practices, and why.

There's lots of documentation about what DITA is, how to think about using it, and various guidelines for authors.  The specs describe what a DITA implementation must support.  What's missing is documentation in the middle.  There are a few blogs and even maybe books that bring the specs a little bit closer to the human scale, but not much closer in my experience.  Unless you want to devote your career to learning this stuff (basically, implementing it yourself to learn what works and what doesn't), it seems there isn't much help.  I think this is for two reasons, which center on the level of expertise you need to get to know this stuff:

Cynical Reason:  After investing in this knowledge, you want to make money, not friends (ok, pretty harsh...  bear with me).  One obvious direction to take this knowledge is into a product that codifies the knowledge.  This actually provides a service in that it shields the average user from needing to know.  The hope is that users will rely on your product, and let you take care of the knowledge.  You have little motivation to tell all because it encourages competition.  And an effort in sharing knowledge takes away from resources you could pour into R&D.  Which brings up the noble reason...

Noble Reason: Time spent sharing knowledge is time not spent applying your hard-won knowledge or acquiring new knowledge.  Even so, some noble people have tried to lay out their discoveries.  Sadly, the information I have found at this level assumes a knowledge of the spec that is so intimate that you probably wouldn't need the blog entry or whatever it is you're reading.  And why should somebody who is pushing her knowledge to the envelope stop and meticulously think through the didactic issues that need to be addressed to bring everybody else along? 

For a person on a deadline who is implementing a DITA workflow as just a small part of her or his overall job, there's no time to work out the knowledge.  And in many cases there is no money to hire a specialist.  If you want DITA to reach down to a level below mega-enterprise, you have to accept that.  I can tell you this from experience.  As a result of my ongoing ignorance, we have implemented some things that are plain wrong, or at least not optimal.  But we're too invested in them now to suddenly fix them.  And anyway, who has the time to do it?  Pain could have been spared with more obvious access to this info-in-the-middle sort of content. 

So that's an appeal on my part...  What, why, how is a template?  What is the motivation behind the relative locations of maps vs topics?  I'm sure I can think of other questions that are open for me, but in fact, I don't have time...  Gotta get to work!  Bottom line, I'm saying there's a lack of documentation in the middle.  I have given up looking for it.