Date   

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@gmail.com> 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 Hollis
 

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.


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

Rodolfo M. Raya
 

Hi Kris,

In my computer's desktop there is a folder containing the full 1.3 specification, another one with the errata text plus a folder with errata grammars, a folder with dita-lwdita-master and a big one with DITA samples from different clients collected through the years. 

At https://ditatranslation.com/articles/index.html I published a few articles that I wrote or co-authored and are relevant for DITA localization. Some of those articles were also published by DITA Adoption TC or CIDM.

Those are my preferred consulting sources.

Regards,
Rodolfo


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

Kristen James Eberlein
 

You are really missing the boat here. Please see my comments inline.

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/12/2020 7:58 PM, Ron Wheeler wrote:
Is there any way to fix  http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html ?
<kje>The OASIS DITA specification is a legal specification. It cannot be modified in any way after it is released; a specific version can be superceded by an errata or a DITA release. Is there a reason that you referenced version 1.2? DITA 1.2 was released over nine years ago, and it has been replaced by DITA 1.3, DITA 1.3 Errata One, and DITA 1.3 Errata Two.</kje>

The descriptions are very cryptic and often seem almost self-referential.
The examples are often edge cases and only show one possible use of a language feature that can appear in many other contexts and have many attributes applied.

<kje>The DITA specification is NOT end-user documentation. Its primary audience is implementors who build implementations of the DITA spec, such as DITA-OT and ditac. Given that audience, we certainly do our best to cover edge cases, as edge cases are where implementors might make different implementation choices.</kje>

It appears to be no longer maintained. Most pages have not been touched in many years.

At the very least the examples should have been augmented to cover more of the features described in the specification.

https://www.dita-ot.org/3.4/topics/troubleshooting-overview.html is also another place where some work could be done.
I believe some error codes are missing in https://www.dita-ot.org/3.4/topics/error-messages.html

<kje>Ironically, the topic that you mention in the DITA-OT documentation (https://www.dita-ot.org/3.4/topics/error-messages.html) cannot be out-of-date. The topic is programmatically generated from the code that stores the error messages. Thus, if DITA-OT has an error message, the error message is present in the DITA topic and thus the documentation. Now, I'm sure that some explanations are missing or can be improved; please see https://www.dita-ot.org/contributing for information about how to suggest edits to the documentation.</kje>

https://www.dita-ot.org/3.4/topics/dita-and-dita-ot-resources.html is not up to date. This group is not mentioned for starters.

<kje>Yes, the dita-users group is mentioned at its then current location at Yahoo! Groups. At the time DITA-OT 3.4 was released, we were awaiting the transfer of the groups messages from Yahoo! to Groups.io. Please note the test version of the DITA-OT documentation correctly places the group at Groups.io.</kje>

I am not sure that adding another wiki is the best answer. Fixing and expanding some of the existing resources might be more productive.

It is very odd that a community of technical writers has such poor and disorganized documentation.


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

Radu Coravu
 

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-creating-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: How can we make use of the 'wiki' feature of groups.io? #admin

Ron Wheeler
 

Thanks.


I am just a longtime user and use Eclipse (Spring Tool Suite) as my authoring environment.
I use standalone DITA-OT as well as the Maven plug-ins to publish my documents.

I do get by through Google which finds many useful pieces of documentation.

This discussion seems to have been prompted by a desire to create a new repository for DITA documentation oriented to actual use of DITA.

My point is that the documentation on the core organizations should be improved before we start a new wiki out of frustration.

Ron


On 2020-01-12 8:14 p.m., Tom Magliery wrote:

Hi Ron,

The first link you mentioned cannot be "fixed" per se. At least, that page can never be changed. It is a specification, not "documentation".

FWIW, there is a newer version of the DITA specification--version 1.3. Many changes and improvements were made to the specification from version 1.2 to 1.3. You can find version 1.3 here:

http://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part0-overview.html

If you have suggestions for new DITA features or about the specification in general, they should be addressed to the DITA Technical Committee. In particular if they pertain directly to the specification, you should send comments to the "dita-comment" mailing list:
https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita#feedback

But if you are a DITA user (as opposed to someone developing applications that support DITA in some way) you may benefit more from reading documentation about your own DITA tools than from reading the DITA specification itself. 

mag

-- 
Tom Magliery


On 2020-01-12 16:58, Ron Wheeler wrote:

Is there any way to fix  http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html ?

The descriptions are very cryptic and often seem almost self-referential.
The examples are often edge cases and only show one possible use of a language feature that can appear in many other contexts and have many attributes applied.

It appears to be no longer maintained. Most pages have not been touched in many years.

At the very least the examples should have been augmented to cover more of the features described in the specification.

https://www.dita-ot.org/3.4/topics/troubleshooting-overview.html is also another place where some work could be done.
I believe some error codes are missing in https://www.dita-ot.org/3.4/topics/error-messages.html

https://www.dita-ot.org/3.4/topics/dita-and-dita-ot-resources.html is not up to date. This group is not mentioned for starters.

I am not sure that adding another wiki is the best answer. Fixing and expanding some of the existing resources might be more productive.

It is very odd that a community of technical writers has such poor and disorganized documentation.



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

Kristen James Eberlein
 

I wanted to take some of the content from a recent post and turn it in a more positive direction.

Question: Where do you go for high-quality information about DITA?

My personal response:

I use the DITA specification (as published at oasis-open.org) and the DITA Open Toolkit (DITA-OT) documentation heavily. I also use whitepapers published by the DITA Adoption Technical Committee, especially the one about troubleshooting authored by Bob Thomas (https://www.oasis-open.org/committees/download.php/53516/DITA13TroubleshootingArticle_FINAL_03jul14.pdf).

You? Curious minds want to know.

--
Best,
Kris

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


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

Tom Magliery
 

Hi Ron,

The first link you mentioned cannot be "fixed" per se. At least, that page can never be changed. It is a specification, not "documentation".

FWIW, there is a newer version of the DITA specification--version 1.3. Many changes and improvements were made to the specification from version 1.2 to 1.3. You can find version 1.3 here:

http://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-part0-overview.html

If you have suggestions for new DITA features or about the specification in general, they should be addressed to the DITA Technical Committee. In particular if they pertain directly to the specification, you should send comments to the "dita-comment" mailing list:
https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita#feedback

But if you are a DITA user (as opposed to someone developing applications that support DITA in some way) you may benefit more from reading documentation about your own DITA tools than from reading the DITA specification itself. 

mag

-- 
Tom Magliery


On 2020-01-12 16:58, Ron Wheeler wrote:

Is there any way to fix  http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html ?

The descriptions are very cryptic and often seem almost self-referential.
The examples are often edge cases and only show one possible use of a language feature that can appear in many other contexts and have many attributes applied.

It appears to be no longer maintained. Most pages have not been touched in many years.

At the very least the examples should have been augmented to cover more of the features described in the specification.

https://www.dita-ot.org/3.4/topics/troubleshooting-overview.html is also another place where some work could be done.
I believe some error codes are missing in https://www.dita-ot.org/3.4/topics/error-messages.html

https://www.dita-ot.org/3.4/topics/dita-and-dita-ot-resources.html is not up to date. This group is not mentioned for starters.

I am not sure that adding another wiki is the best answer. Fixing and expanding some of the existing resources might be more productive.

It is very odd that a community of technical writers has such poor and disorganized documentation.



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

Ron Wheeler
 

Is there any way to fix  http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html ?

The descriptions are very cryptic and often seem almost self-referential.
The examples are often edge cases and only show one possible use of a language feature that can appear in many other contexts and have many attributes applied.

It appears to be no longer maintained. Most pages have not been touched in many years.

At the very least the examples should have been augmented to cover more of the features described in the specification.

https://www.dita-ot.org/3.4/topics/troubleshooting-overview.html is also another place where some work could be done.
I believe some error codes are missing in https://www.dita-ot.org/3.4/topics/error-messages.html

https://www.dita-ot.org/3.4/topics/dita-and-dita-ot-resources.html is not up to date. This group is not mentioned for starters.

I am not sure that adding another wiki is the best answer. Fixing and expanding some of the existing resources might be more productive.

It is very odd that a community of technical writers has such poor and disorganized documentation.


reltable loses navtitle when collection-type="family" is added #reltable

Ron Wheeler
 

I am using DITA to document the plans for condominiums in a condo association.

Many units have the same plan. The relatble links the plan to the condos bult with the plan and links each condo unit to the appropriate plan.


My original reltable without collection-type="family" worked in the sense that plans had a list of condos built using that plan and each condo had a link to the plan.
The headings came out on the PDF and were in the correct language.
The problem that I was trying to address was that each condo had its own navtitle on the plan which looked a bit silly and took a lot of space.

Adding collection-type="family" did get rid of the extra headings but now I have a "Related Concepts" title on the condo page that lists similar condos using the same plan.
The "Condominiums built with this plan" or "Copropriétés construite avec ce plan" on the condo page is replaced by English text "Related Concepts" which is a NO-NO in Quebec.

The "Condominiums built with this plan" or "Copropriétés construite avec ce plan" does appear on the Plan page once per plan rather than once per address which is great.

It looks like a bug where the navtitle is replaced on one side of the relation.

Can I add something to get my navtitle back or eliminate the list of similar condos on the condo unit page(suppress one side of the relationship)?


<reltable>
        <relheader>
             <relcolspec type="topic">
              <topichead>
                <topicmeta>
                  <navtitle audience="en">Condominiums built with this plan</navtitle>
                  <navtitle audience="fr">Copropriétés construite avec ce plan</navtitle>
                </topicmeta>
              </topichead>
            </relcolspec>
                <relcolspec type="topic">
              <topichead>
                <topicmeta>
                  <navtitle audience="en">Plan for this condominium</navtitle>
                  <navtitle audience="fr">Plan pour cette copropriété</navtitle>
                </topicmeta>
              </topichead>
            </relcolspec>
        </relheader>
        <relrow>
            <relcell collection-type="family">
            <topicref keyref="1_14588Aumais"/><topicref keyref="3_14588Aumais"/><topicref keyref="1_14628Aumais"/><topicref keyref="3_14628Aumais" />
            </relcell>
            <relcell><topicref keyref="leftodd12"/></relcell>
        </relrow>

1241 - 1260 of 46295