Topics

Reltable-Struggles #reltable


@l3arn4life
 

Hi there,

we’re making progress on our journey to implementing a reuse-strategy, which made me happy – until I added reltables.
I defined resource-only keys to be used for navigational topicrefs. In my maps, I reference the desired topics using those keys. At the same time, in accordance with Eliot’s prescription about keys, I created unique keys for each instance of a topic on their respective navigational topicref. I then used this unique key to create links among the topics using a reltable. That failed spectacularly: not a single link in my output.
Please refer to the attached sample for the specifics of this setup. I also included an html5-transformation from DOT 3.4.1. (DOT 3.5.2 btw. renders no output at all, which I have no explanation for.)
I tried moving the reltable to its own map, to no avail. In addition to using their unique keys, I added the appropriate href – still no links. I replaced the unique keys and used the resource-only keys – no links.
After searching github, I found a number of bugs related to reltables, some of which had been solved. With the little time I had I unfortunately could not determine whether the issue at hand belongs to one of the known bugs or whether I’m just missing something here. Any help would greatly appreciated.

Many thanks,
Ed


@l3arn4life
 

Here is the progress I made:
The problem described seems to be related to these issues:
https://github.com/dita-ot/dita-ot/issues/2393
https://github.com/dita-ot/dita-ot/issues/2538
I affirmed my suspicion about keyscopes being the culprit by removing the keyscope for the submap containing the reltable and generating output: my keyrefed reltable-links suddenly showed up. I’m using DOT 3.4.1.

As far as I understand, this problem was fixed in
https://github.com/dita-ot/dita-ot/pull/3344
The fix proposed by Radu has been approved and added to the 3.4 milestone on Nov. 5th, 2019. Since I’m still comparatively new to the world of github, I can only assume that the fix would be part of DOT 3.4 and, since we now use DOT 3.4.1, part of the DOT we use.

I therefore fail to understand why my problem persists. I’ve run out of ideas, please help.

Regards,
Ed


Radu Coravu
 

Hi Ed,

From what I see this issue is still open:

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

Indeed I wrote in a comment that it was probably related to another closed one, but this does not mean that my fix on that other issue also fixed this problem.

Maybe you can add a comment on the open issue, attach also a sample project.

Regards,
Radu
Radu Coravu
Oxygen XML Editor
On 8/17/20 3:47 PM, schmidt.eduard@... wrote:

Here is the progress I made:
The problem described seems to be related to these issues:
https://github.com/dita-ot/dita-ot/issues/2393
https://github.com/dita-ot/dita-ot/issues/2538
I affirmed my suspicion about keyscopes being the culprit by removing the keyscope for the submap containing the reltable and generating output: my keyrefed reltable-links suddenly showed up. I’m using DOT 3.4.1.

As far as I understand, this problem was fixed in
https://github.com/dita-ot/dita-ot/pull/3344
The fix proposed by Radu has been approved and added to the 3.4 milestone on Nov. 5th, 2019. Since I’m still comparatively new to the world of github, I can only assume that the fix would be part of DOT 3.4 and, since we now use DOT 3.4.1, part of the DOT we use.

I therefore fail to understand why my problem persists. I’ve run out of ideas, please help.

Regards,
Ed



@l3arn4life
 

Hi Radu,
thanks for your input. I wonder though: How do people reuse stuff these days with DITA 1.3? Is there a way to actually use branch-filtering and keyscopes, keys and all the wonderful things it promises? Has anybody ever succeeded in implementing a smart strategy that uses these tools? DITA 1.3 has been around since 2015, after all.
I’m also bewildered that an issue regarding such a core functionality of DITA 1.3 can remain unsolved for more than a couple months, let alone years.
When we decided to make the jump from Microsoft Word to DITA, we were promised this shiny world of reuse, single-source publishing and smart content management. Once we tried to come up with a smart reuse-strategy that uses all these promising tools, a lot (not so say most) of it’s glory vanished into thin air. We are met, instead, with old bugs and the faint hope that one day maybe things will start working.
Yes, I absolutely understand the DITA-OT is a free tool with exceptionally smart but few people working on it. But I imagine there’s a significant number of businesses relying on it functioning properly. Why not establish a paid branch with designated developers that actually solve bugs at an acceptable rate? I know the company where I work would be willing to pay for stuff to work. However, in the absence of justified hope for things to work in the forseeable future, the outlook indeed is grim, and maybe one needs to start looking for other solutions.
This in no way is a personal attack on anybody, I’m just venting my frustration about my being disillusioned so quickly. Please tell me there’s hope.


Chris Papademetrious
 

Hi Ed,

Going off on your tangent a bit...

We're in the process of migrating a couple hundred books to DITA. We are only using basic features (profiling conditions, some reuse of topic files across maps) but no branch filtering, keyscopes, reltables, etc. They are all areas of interest and we'll soon be following in your footsteps to explore them, but first we need to complete our migration, get the writers comfortable with the new environment, and get a solid working status quo. But I hope everything works when we get there.

Here's a talk from Kristen Eberlein about exactly the points you raised about the DITA-OT:

"Long term DITA-OT planning" presented by Kristen Eberlein at DITA-OT Day 2016
DITA-OT Day - Munich 2016


This also looks interesting, although I've only just noticed it now and I haven't watched it:

"What are we missing? Where would you like to see us go?" - J. Elovirta, R.Anderson, DITA-OT Day
DITA-OT Day - Berlin 2017


(To all - are there any other high-level contextual videos from conferences like this that are worth a watch?)

 - Chris


@l3arn4life
 

Hi Chris,
I appreciate your thoughts. That first video actually made me decide to drop a comment along with my testfiles ( I just now see that Radu already beat me to it – you made my day Sir, thank you!).

I knew the support for DOT was small but didn’t realize it is that small. With that many companies using the DOT, one would think that funding the project should be easier. Is there any information on whether the points addressed by Kris have seen any movement?

Regards,
Ed


Julio J Vazquez
 

Hi, 

I think you're conflating a few things. I have helped folks successfully use branch filtering and, at least in DITA-OT 2.54 there were no problems with reltables.ditamap of you used keys and prefixes or suffixes with your ditavalref strictures. There is no need for keyscopes for this to work and it could be that your references in the reltables, if they are using keyscopes, are not quite right. 

You may want to make sure that the keyscope is needed at the point of reference and there is no other keyscope that might have an effect on your reference. 

Julio J. Vazquez


@l3arn4life
 

Hi Julio,
thanks for chiming in.

For us, keyscopes provide a handy mechanism for content swapping: the same key in different submaps resolves to different images e. g. All our keyscopes are parallel, so interference should not be an issue. I understand the same effect could be achieved with profiling and branch filtering, however, the key-approach seems more elegant and less bloated.
Branch filtering provides a way to reuse entire topics. Irrelevant content is filtered out depending on the context, which means we always end up with several copies of the same topic. Adding suffixes to each ditaval context helped solve this problem (thanks to Radu for the tip). Using navigational keys to reference specific instances of a topic in a reltable now should yield reliable linking between topics. This sadly does not work.

Removing the keyscopes from the sample project I attached above resulted in properly rendered links, but for some reason broke the branch filtering. Adding keyscopes breaks reltables. Either situation is highly unsatisfactory and I hope a solution will be found. If there’s a problem with my setup, please feel free to point it out, I’m happy to stand corrected.

Regards,
Ed


Dan Vint
 

Can someone explain:

".ditamap of you used keys and prefixes or suffixes with your ditavalref strictures. There is no need for keyscopes for this to work and it" 

I don't understand the reference to prefix and suffix in this context.

..dan


Sent from my Verizon, Samsung Galaxy smartphone


-------- Original message --------
From: "Julio J Vazquez via groups.io" <julio_v27612@...>
Date: 8/18/20 4:10 AM (GMT-08:00)
To: main@dita-users.groups.io
Subject: Re: [dita-users] Reltable-Struggles

Hi, 

I think you're conflating a few things. I have helped folks successfully use branch filtering and, at least in DITA-OT 2.54 there were no problems with reltables.ditamap of you used keys and prefixes or suffixes with your ditavalref strictures. There is no need for keyscopes for this to work and it could be that your references in the reltables, if they are using keyscopes, are not quite right. 

You may want to make sure that the keyscope is needed at the point of reference and there is no other keyscope that might have an effect on your reference. 

Julio J. Vazquez


Lief Erickson
 

The prefixes and suffixes are explained from this page in the DITA 1.3 specification.


On Tue, Aug 18, 2020 at 9:27 AM Dan Vint <dvint@...> wrote:
Can someone explain:

".ditamap of you used keys and prefixes or suffixes with your ditavalref strictures. There is no need for keyscopes for this to work and it" 

I don't understand the reference to prefix and suffix in this context.

..dan


Sent from my Verizon, Samsung Galaxy smartphone


-------- Original message --------
From: "Julio J Vazquez via groups.io" <julio_v27612=yahoo.com@groups.io>
Date: 8/18/20 4:10 AM (GMT-08:00)
Subject: Re: [dita-users] Reltable-Struggles

Hi, 

I think you're conflating a few things. I have helped folks successfully use branch filtering and, at least in DITA-OT 2.54 there were no problems with reltables.ditamap of you used keys and prefixes or suffixes with your ditavalref strictures. There is no need for keyscopes for this to work and it could be that your references in the reltables, if they are using keyscopes, are not quite right. 

You may want to make sure that the keyscope is needed at the point of reference and there is no other keyscope that might have an effect on your reference. 

Julio J. Vazquez


Radu Coravu
 

Hi Eduard,

I investigated a little bit the problem and proposed a possible fix here:

https://github.com/dita-ot/dita-ot/issues/2393#issuecomment-675479251

Maybe you can try the fix on your side and add a comment on the issue when you have the time. I made the fix against DITA OT 3.5.1.

We have Oxygen users publishing DITA using branch filtering and key scopes, but without relationship tables.

About what you said, the two main developers and the documentation lead invest their time mostly as a hobby. They already do more than they should and indeed we, the community who builds commercial tools and offers services around the DITA Open Toolkit, need to help further.

As a developer working for a commercial tool I try to help in the following ways:

 - Add issues to the DITA OT issues list when they are reported, along with relevant sample projects to reproduce the problems.

- Discuss with the DITA OT developers on the issues various aspects of the problem.

- Try to find the time to propose fixes on those issues or to come up with workarounds.

- Open pull requests to propose changes to the DITA OT code.

- Help others with questions related to the publishing engine's functionality.

- Participate in the monthly DITA OT meetups: https://github.com/dita-ot/dita-ot/wiki/Meeting-minutes

There is a small article about contributing to the DITA Open Toolkit:

https://www.dita-ot.org/contributing

If your company has an experienced Java developer or is willing to pay an experienced Java developer to work on the DITA OT project and focus on fixing specific issues, they will be helped with advice by the community and maybe they can donate their work back to the DITA OT by opening pull requests on the DITA OT project. Or if somebody else from the community is willing is willing to do some paid work on the DITA OT code maybe they can contact you directly and discuss about this.

Regards,
Radu
Radu Coravu
Oxygen XML Editor
On 8/17/20 4:45 PM, schmidt.eduard@... wrote:

Hi Radu,
thanks for your input. I wonder though: How do people reuse stuff these days with DITA 1.3? Is there a way to actually use branch-filtering and keyscopes, keys and all the wonderful things it promises? Has anybody ever succeeded in implementing a smart strategy that uses these tools? DITA 1.3 has been around since 2015, after all.
I’m also bewildered that an issue regarding such a core functionality of DITA 1.3 can remain unsolved for more than a couple months, let alone years.
When we decided to make the jump from Microsoft Word to DITA, we were promised this shiny world of reuse, single-source publishing and smart content management. Once we tried to come up with a smart reuse-strategy that uses all these promising tools, a lot (not so say most) of it’s glory vanished into thin air. We are met, instead, with old bugs and the faint hope that one day maybe things will start working.
Yes, I absolutely understand the DITA-OT is a free tool with exceptionally smart but few people working on it. But I imagine there’s a significant number of businesses relying on it functioning properly. Why not establish a paid branch with designated developers that actually solve bugs at an acceptable rate? I know the company where I work would be willing to pay for stuff to work. However, in the absence of justified hope for things to work in the forseeable future, the outlook indeed is grim, and maybe one needs to start looking for other solutions.
This in no way is a personal attack on anybody, I’m just venting my frustration about my being disillusioned so quickly. Please tell me there’s hope.



  


@l3arn4life
 

Hello Radu,

thanks for sacrificing your time to solve this issue. Using your modified stylesheet and DOT 3.5.2 leads to working links in the output. Adding a ditaval to the simplified project (or the original project, for that matter) leads to no output. My comment and some files (including a log for the transformation with ditavals) can be found here:
https://github.com/dita-ot/dita-ot/issues/2393#issuecomment-677442369

Your massive involvement in the DITA-OT-project has not gone unnoticed I think, and all of us are grateful for your invaluable contributions. Most of us in this forum (at least that’s my impression) have in one form or other profited from your expertise.

Considering the number of companies that use the DITA-OT, the lack of support both content-wise and financially is astonishing, at least to me. Either those companies only use a fraction of the tools offered by DITA 1.3, or they have other means of fixing bugs (which would mean different variations and versions of the DITA-OT floating around on these companies’ servers). If the latter is indeed the case and somebody from one of these companies is reading along here, I’d like to ask you to at least offer your fixes for sale so that suffering folks can stop suffering and get back to producing and reusing awesome content.
If the former is true, DITA-development of any kind seems pointless: People are happy with what they have, their systems are well oiled and have been running smoothly since DITA 1.x, so "if it ain’t broke don’t fix it". New people coming to the DITA-world are introduced to well-established best practices and nobody gets itchy for new functions since everything works just fine the way it is.

These scenarios might well be a false dichotomy but whichever scenario is true out there, the speed with which bugs are fixed atm is hard to accept: we’ve got work to do, content to produce, deadlines to meet and customers to satisfy. I’m not a developer myself, but I’m willing to report bugs and issues as they come up (which is basically all I’ve done in this forum so far). Our company has no Java-devs (to my knowledge), we run on C#, C++ and some Javascript. If experienced developers from the community are willing to do paid work, I’m certain my company will at least consider going down this route within clearly defined boundaries and for specific bugs, as we would directly benefit from such cooperation. I will talk to my supervisors should such an offer come in.

With all that said, I can’t imagine this project succeeding long-term with only two core-developers working on it as a hobby. If the DOT had a price and fulltime developers involved, things would look better I suspect. Some competition would probably help, too. That’s my two cents.

Sincerely,
Ed