Oxygen XML Forum

I run a one-person startup. I come up with the ideas and write both the code and the documentation. When writing, I jump from topic to topic. A few situations come up often that I don't know how to handle efficiently:

1) While writing, I introduce a word that will eventually need its own concept topic and related task topics. For example, in the concept "Initial Distributions", I wrote "Initial distributions quantify the chance of encountering a specific thing in a specific region prior to generation zero." Both "region" and "generation zero" need concept pages and task pages (e. g, "How to define generation zero" and "How to create a region"). I'd like to quickly stub out these files (just filename and title) and place them in the DITA map without leaving the current topic. Is that possible?

2) There should be links between related pages, either directly in the text or in a related links section at the top or bottom of the topic. If the link is directly in the text, should every instance of that word be a link in the entire document? What is the DITA standard for linking related pages?

3) Is there any way for Oxygen to automatically create links? For example, if I created a concept titled "Generation Zero" could that combination of words in other pages automatically become inline links to the concept page or trigger the addition of the appropriate link in the related pages header or footer?

4) I often want to leave myself programming and TODO notes. Is there a way to add and track such annotations without making them part of the DITA document? For example, could I highlight some text in a topic and attach a comment like "this should be its own function in the agents module" and then see a list of all such comments throughout the DITA map?

Thank you,
-d. vyd

Hi,

Thanks for taking the time to tell us about your interesting use cases.
Please see some answers below:

1) While writing, I introduce a word that will eventually need its own concept topic and related task topics. For example, in the concept "Initial Distributions", I wrote "Initial distributions quantify the chance of encountering a specific thing in a specific region prior to generation zero." Both "region" and "generation zero" need concept pages and task pages (e. g, "How to define generation zero" and "How to create a region"). I'd like to quickly stub out these files (just filename and title) and place them in the DITA map without leaving the current topic. Is that possible?

We have a bunch of actions in the DITA Maps Manager to create new topics. I do understand that it would be better to have some kind of action when the focus is inside a topic to create another topic. The action would need to be quite complex though as you would need to choose the place for the new topic in the DITA Map.
Here's one existing way to create a new topic while you are working in another:
- select a word that you want to point to that new topic, press ENTER and wrap it in an empty DITA <xref> element.
- press alt-enter and set the @href attribute of the <xref> to point to a non existing topic file name like "preparation.dita"
- press Ctrl-Enter inside the xref, Oxygen will attempt to open the link, it will notice the link does not exist and propose you to create a new file for it.
- you will still need to add the new topic to the DITA Map using the DITA Maps Manager view.

2) There should be links between related pages, either directly in the text or in a related links section at the top or bottom of the topic. If the link is directly in the text, should every instance of that word be a link in the entire document? What is the DITA standard for linking related pages?

From what I think this is not related to the DITA standard, the DITA standard does not give indication about how various DITA elements should be used to achieve maximum readability and comprehension by the end users.
But in the DITA ecosystem most experts seem to preach leaving the links at the bottom of the topic and minimizing the amount of in-content links. Like this topic in the DITA Style Guide written by dr. Tony Self:
https://www.oxygenxml.com/dita/stylegui ... ences.html

3) Is there any way for Oxygen to automatically create links? For example, if I created a concept titled "Generation Zero" could that combination of words in other pages automatically become inline links to the concept page or trigger the addition of the appropriate link in the related pages header or footer?

We do not have such a feature, and yes it would be very cool to have such a feature. Although like any automatic feature it might not always produce quality links. Each DITA topic has metadata, a place where you can define key words, maybe a publishing engine could rely on these keywords to automatically add links between topics.
As a possible useful feature when you right click inside a DITA topic opened in the Author visual editing mode there is a "Find Similar Topics" action, it tries based on the page's words to find similar topics in the user's manual, afterwards you can insert the links in a relationship table for example.

4) I often want to leave myself programming and TODO notes. Is there a way to add and track such annotations without making them part of the DITA document? For example, could I highlight some text in a topic and attach a comment like "this should be its own function in the agents module" and then see a list of all such comments throughout the DITA map?

When you are working with topics in the Author visual editing mode, the toolbar (but also the contextual menu) has an "Add comment" action which can be used on selected content.
Once the comment is added, Oxygen's "Open/Find Resource" dialog from the main Find menu can be used to "search in reviews", meaning that you can search for a certain comment in all your project's topics.
There is also a "Review" view (main menu Window->Show view) which shows all the comments in the current document. When the DITA Maps Manager has an opened DITA Map the "Review" view should contain some blue arrows allowing you to navigate between topics which have such comments in the order in which they are referenced in the DITA Map.

Regards,
Radu

Radu, as always, thank you for your detailed response. The numbers below correspond to the issues in my original email and your response.

1) I'll try your method

2) Thanks for sharing an expert opinion. I'll follow it.

3) How is a relationship table used within a topic? Oxygen documentation states it is not exposed by default for navigation. I'd like an explicit "related links" section that users can see and click on. Can you provide or link to an example?

4) That sounds perfect!

Hi,

A relationship table is defined in the DITA Map, if you open the DITA Map in the main editing area in the Author visual editing mode, we have a toolbar button to insert a relationship table. You can find an example of a reltable in this sample file which comes with Oxygen OXYGEN_INSTALL_DIR/samples/dita/thunderbird/User_Guide.ditamap.
Each row in the table defines a relationship between the topic references in each cell. This will mean that when the final output is generated, you will see links at the end of each topic pointing to the related topics.
There is a free Oxygen add-on:

https://github.com/oxygenxml/oxygen-dit ... ences-view

which allows you to see when editing a topic all relationships defined for it in the DITA Map's reltable.

Regards,
Radu

Excellent. Thank you.

In the DITA map shown in the attached PNG file, People are Agents, which are Entities. Their hierarchical relationship in the map reflects moving from more general to more specific concepts. Do these relationships need to be made explicit in the reltable or can they be extracted directly from the DITA map? Can the generated links include both parent (is_a) and child (can_be) relationships?

For example, https://www.oxygenxml.com/dita/stylegui ... ately.html has both a labelled "Related concepts" link ("Embedded (or nested) ditamaps") and an unlabelled "Parent topic" (which returns to "Relationship tables"). Were these created manually in a reltable or automatically from the DITA map?

Hi,

On each DITA <topicref> element you can set a collection-type attribute which defines how its child topics are related.
There is this example in the DITA 1.3 specification which explains how links are generated with this collection-type attribute and with the reltable:

https://www.oxygenxml.com/dita/1.3/spec ... -atts.html

Regards
Radu

Radu,

I clearly misunderstand something because I cannot produce parent-child links. Please find a DITA map and a few concepts in the attached ZIP file. When I transform the document using "family" or "sequence" collection-type, I see only "related" links. What did I do wrong? Ideally I'd like to differentiate between the following links:

Parent
Child
Sibling
Related concepts (that are not siblings)
Related tasks (that are not siblings)
Related references (that are not siblings)

Hi,

The "mineral.dita" and "vegetable.dita" topics were missing from your sample project, but I created some empty topics for them.
Looking at a related row like this: if you wanted to express a relationship between agents.dita and things.dita, you should have placed them in separate table cells:
this would have added extra links between these topics in the published output.
But the "collection-type="family"" set on the top "entities.dita" reference already adds links between "agents.dita" and "things.dita" and this would mean that you would get doubled links between them.
I still do not 100% understand your desired outcome. Also to what output format are you publishing? Is it XHTML, HTML5, Oxygen WebHelp or PDF?
How about if you give me a precise example, like:

For topic "agents.dita", when published to HTML I would like the following links to appear in it:
1. Link to "things.dita" with the category text being...

Regards,
Radu

Hi Radu,

I apologize if I have not made my goal clear. I'll prepare an example DITA map and mock-up the output I'm looking for. Thank you for your help (and patience).

-d. vyd

One more thing,
I saw one of our clients posted on the DITA Users List a PDF about using reltables, the editing steps are given with Oxygen, I'm linking it here in case somebody may find it useful:

https://dita-users.groups.io/g/main/message/45658

Regards,
Radu

Thank you Radu. I'll look at the PDF about reltables you linked to. Please find attached a ZIP file with a DITA map, DITA topics, the real PDF output using CSS transformation, and the desired PDF output with notes in red italics.

Hello,

Radu took a few days off, but I noticed the resources you mentioned were not attached, therefore I thought I should mention this. You could try, for example, sending them via e-mail to support@oxygenxml.com. If you decide to send them this way, please also mention the URL of this thread inside the e-mail.

All the best wishes,
Sorin Carbunaru
Oxygen XML Editor

Thanks Sorin. I emailed the example to the address you provided.

Hello,

Unfortunately I cannot find your e-mail in our support inbox. Could you try again? Also let us know the subject of your e-mail, to find it easier.

Sorin C.

Hi Sorin,

I resent the email to support@oxygenxml.com
the subject is: ZIP file for forum post58968

thank you,
d. vyd

I confirm that we got it .

Has anyone had a chance to look at my example file? I'd like to learn how to create reltable links like those described.

Hi Da'ud,

I did write back to your email address, maybe you can check your spam folder, I will re-send my email just in case.
I'm attaching my reply below:

Thanks for the samples.

I took your DITA Map and published it to WebHelp responsive.

Then I opened the "people.html", it has related links to all its siblings:

Code: Select all

 Related information
     Creatures
     Point-Of-View Agent
     How to set a point of view agent

If I change for example the relationship to sequence:

Code: Select all

 <topicref href="agents.dita" collection-type="sequence">

then the generated people.html gets Next/Previous toolbar buttons.

Can you give me an example of link that you want to add and do not know how best to proceed in adding it?

Regards,
Radu