Common subject map for company users

[upa]

Hi,

We want to use subject maps to control the values for specific attributes, such as audience. I've succeeded in defining the subject map and integrating it in the main DITA map.

However, we want to control and update the values for some of the attributes company-wide. There are, for example, defined audiences. If these change, all users would need to update the subject maps of their Oxygen projects. So, here are my questions:

1. Is there a way to centrally define the subjects - integrate the subject map in the Oxygen framework, for example? Or another way that I have not seen so far?
2. Is there a way to combine a central subject map with a project-specific one?

Thanks for any help
Ulrike

[Radu]

Hi Ulrike,

I do not have a clear idea of how your organization is collaborating. Do you use a CMS? Do you use a versioning system like Subversion or GIT? Do you have multiple projects you are working on? Do all these projects need to have the same profiling attributes imposed for writers?

1. Is there a way to centrally define the subjects - integrate the subject map in the Oxygen framework, for example? Or another way that I have not seen so far?

The Subject Scheme Map which provides the profiling attributes and values needs to be referenced by the root DITA Map opened in Oxygen in the DITA Maps Manager.
So it cannot be referenced at framework level. Even if it were, the users would still need to update their framework from a common repository. Do you have a customization of the DITA framework? Is it distributed as an add-on in the organization?

2. Is there a way to combine a central subject map with a project-specific one?

We have no concept of project-specific Subject Scheme. As I previously said the Subject Scheme Map which provides the profiling attributes and values needs to be referenced by the root DITA Map opened in Oxygen in the DITA Maps Manager.
Do you use Oxygen Projects to share options between users? If so you can switch the Preferences->Editor / Edit modes / Author / Profiling/Conditional Text page to Project level and the profiling attributes and values defined there will be used if the main DITA Map does not refer a Subject Scheme Map.

Regards,
Radu

[upa]

Hi Radu.

I do not have a clear idea of how your organization is collaborating. Do you use a CMS? Do you use a versioning system like Subversion or GIT? Do you have multiple projects you are working on? Do all these projects need to have the same profiling attributes imposed for writers?

Yes, we use Subversion to manage our documentation files. Yes, the company is working on multiple projects, using the same documentation framework for all of them. Some of the profiling attributes are common to all projects (like status) and need to be standardized. Others are project-specific. We need to impose the standardized profiling attributes.

So it cannot be referenced at framework level. Even if it were, the users would still need to update their framework from a common repository. Do you have a customization of the DITA framework? Is it distributed as an add-on in the organization?

Yes, we used a customized framework, it is distributed via Subversion

We have no concept of project-specific Subject Scheme.

That is a pity. Would DITAVAL files be better then to distribute common condition attributes throughout the company?
I really like the concept of subject maps, as we are also working with ontologies and taxonomies. But if I cannot control the subjects centrally, they are of limited use for us right now.

[Radu]

Hi,

Maybe you could have one common subject scheme map with the common attributes and values.
This common map would be referenced from all your SVN projects (there is this concept of SVN externals which should allow you to refer from an SVN project a folder which belongs to another project). So if you would commit this common map in one project, users from other projects would just need to update their specific project and receive the common map.

So each individual project's master DITA Map would refer two subject scheme maps, one with the common content and one with the project-specific content, Oxygen should gather and propose you values from both referenced maps.

Regards,
Radu

[upa]

Thanks, I will try that and come back with results.

Ulrike

[upa]

Hi,

We tried several things and in the end the following constellation worked:
- The document map has a map reference to the project-specific subject map. (It does not work if you reference 2 subject maps in the document map, the subjects did not add up, only the subjects from 1 subject map were available in this case)
- The project-specific subject map has a map reference to the general subject map. In this way, the sum of all subjects defined in the 2 subject maps is available as profiling attributes.
- We use SVN externals to link in common files into the project, e.g. common keys.

What does not work:
- The subject maps MUST be located in the same folder as the document map, otherwise the PDF generation with the DITA-OT (legacy PDF) does not work, because the scripts do not seem to copy the subject maps to the the correct directory, at least the error message is "Cannot find the specified file". Any idea how to change this? We would like to store the common subject map, for example, in a common folder integrated as SVN external.
- We specified NAV titles for the subjects to make it easier for the authors to assign profiling attributes. However, the Oxygen dialog for assigning profiling attributes does not display the NAV title. Does Oxygen support this?
- We cannot select the subject map as basis for filtering the output in the transformation scenario (analog to profiling condition set). Is this supported?

[Radu]

Hi Ulrike,

Please see some answers below:

- The document map has a map reference to the project-specific subject map. (It does not work if you reference 2 subject maps in the document map, the subjects did not add up, only the subjects from 1 subject map were available in this case)

The values for a profiling attribute are defined in a key definition, something like:

Code: Select all

<subjectdef keys="productSbjKey">

            <subjectdef keys="X2000">

.....................

and keys with the same name are not additive, indeed only the first key's defined values will be used.

But you could also do something like this:

1) In one Subject Scheme Map you define something like this:

Code: Select all

        <subjectdef keys="productSbjKey1">

            <subjectdef keys="X3">

                <topicmeta>

                    <navtitle>X3 Phone Guide</navtitle>

                </topicmeta>

            </subjectdef>

            <subjectdef keys="X4">

                <topicmeta>

                    <navtitle>X4 Phone Guide</navtitle>

                </topicmeta>

            </subjectdef>

        </subjectdef>

and in another Subject Scheme Map you define another key with extra values:

Code: Select all

<subjectdef keys="productSbjKey2">

            <subjectdef keys="X2">

                <topicmeta>

                    <navtitle>X2 Phone Guide</navtitle>

                </topicmeta>

            </subjectdef>

            <subjectdef keys="X1">

                <topicmeta>

                    <navtitle>X1 Phone Guide</navtitle>

                </topicmeta>

            </subjectdef>

        </subjectdef>

then in the third referenced Subject Scheme Map you can refer to both sets of values for a certain profiling attribute like:

Code: Select all

    <enumerationdef>

        <attributedef name="product"/>

        <subjectdef keyref="productSbjKey1"/>

        <subjectdef keyref="productSbjKey2"/>

    </enumerationdef>

- The project-specific subject map has a map reference to the general subject map. In this way, the sum of all subjects defined in the 2 subject maps is available as profiling attributes.
- We use SVN externals to link in common files into the project, e.g. common keys.

Ok.

What does not work:
- The subject maps MUST be located in the same folder as the document map, otherwise the PDF generation with the DITA-OT (legacy PDF) does not work, because the scripts do not seem to copy the subject maps to the the correct directory, at least the error message is "Cannot find the specified file". Any idea how to change this? We would like to store the common subject map, for example, in a common folder integrated as SVN external.

I'm surprised the legacy PDF works at all. It has not been updated in ages in the DITA OT implementation. You should really consider taking the time to migrate to the current PDF output type.

- We specified NAV titles for the subjects to make it easier for the authors to assign profiling attributes. However, the Oxygen dialog for assigning profiling attributes does not display the NAV title. Does Oxygen support this?

It should, I'm using Oxygen 15.2 for tests and if I have something like this in the Subject Scheme Map for each profiling attribute value:

Code: Select all

            <subjectdef keys="X3">

                <topicmeta>

                    <navtitle>X3 Phone Guide</navtitle>

                </topicmeta>

            </subjectdef>

the "Edit Profiling Attributes" dialog shows the navigation title next to each checkbox.

- We cannot select the subject map as basis for filtering the output in the transformation scenario (analog to profiling condition set). Is this supported?

A Subject Scheme Map can be used for controlling attribute values. It does not have the equivalent functionality of an Oxygen current selected profiling condition set or of a DITAVAL file used to produce the output. So the Subject Scheme Map can impose restrictions on how the DITA content is edited and validated + it can impose a hierarchy of values which can then be used to filter in the DITAVAL files in a hierarchical fashion:

http://www.oxygenxml.com/doc/ug-oxygen/ ... e-map.html

Hope this helps.
Regards,
Radu

[upa]

Hi Radu,

Thanks for your answers.

We made some further tests with the subject maps. We used the “flowers” sample files and the default DITA OT PDF transformation. We still have the following problem:

What does not work:
- The subject maps MUST be located in the same folder as the document map, otherwise the PDF generation with the DITA-OT (legacy PDF) does not work, because the scripts do not seem to copy the subject maps to the the correct directory, at least the error message is "Cannot find the specified file". Any idea how to change this? We would like to store the common subject map, for example, in a common folder integrated as SVN external.

My colleague found an issue (did you post it?) from last year and that is exactly our problem (PDF output instead of XHTML output): https://github.com/dita-ot/dita-ot/issues/1456

We saw that this issue/bug was fixed in DITA OT 1.7.3. I have installed oXygen XML Author 15.2, build 2014013017 with DITA OT 1.7. The file DebugAndFilterModule.java was fixed (see https://github.com/dita-ot/dita-ot/comm ... 584331da22). Is this fix already implemented in oXygen? If not, can we easily implement the fix in our framework (it’s a specialization of your DITA framework)?

[Radu]

Hi Ulrike,

I posted the issue you mentioned. Oxygen 15.2 comes with DITA OT 1.7. If you look in the Oxygen Help menu->About dialog there is a tabbed pane called Frameworks in which you can see the bundled DITA OT version.
If you are already using Oxygen 15.2 and the legacy PDF problem still manifests, then the already fixed issue is not related to it, it is just similar in behavior.
You could try to add an issue on the DITA OT GIT HUB bugs list for the legacy PDF problem but I'm not sure it will get done, very few people are still interested in maintaining legacy PDF.
Anyway, from what I googled SVN 1.6 might have support for file externals, you should look into it:

http://svnbook.red-bean.com/nightly/en/ ... rnals.html

Regards,
Radu

[Frank Ralf]

Hi Radu,

JFTR, this seems to be indeed a problem with the DITA-OT version. With older versions (1.7.2) the transformation breaks with the error message

Code: Select all

The key "my-doc-type" is defined more than once in the same map file. The reference href="" is ignored.

https://dita-ot.github.io/1.8/readme/DI ... __DOTJ045I

With DITA-OT >= 1.7.5 the transformation runs through, though I get the same message. I suppose this problem will be solved as soon as all users have switched to oXygen 16

Kind regards,
Frank

[Radu]

Hi Frank,

Yes, probably but I cannot guarantee that the legacy PDF will continue to work with a future DITA OT version.

Regards,
Radu

[Frank Ralf]

Hi Radu,

Actually, we plan to finally switching to PDF2 as this is not the only issue we have with the Legacy transformation

Kind regards,
Frank

[Frank Ralf]

Hi Radu,

- We specified NAV titles for the subjects to make it easier for the authors to assign profiling attributes. However, the Oxygen dialog for assigning profiling attributes does not display the NAV title. Does Oxygen support this?

It should, I'm using Oxygen 15.2 for tests and if I have something like this in the Subject Scheme Map for each profiling attribute value:

I am using an Author CSS Combo Box without "values" property so the values get collected from the subject scheme map. However, in this case the navtitles are not used. I suppose this is because the profiling attribute dialog works differently from the CSS function?

Kind regards,
Frank

[Radu]

Hi Frank,

Nice idea. I'll add an improvement request to also use the navtitle rendering information gathered from the subject scheme for each profiling attribute value also in the default form control implementations we deliver.

Regards,
Radu

[Frank Ralf]

Thanks, Radu.

I now do some testing using oXygen 16 and a PDF2 transformation but still get an http://www.oxygenxml.com/DITA-messages. ... or message when using a second subject scheme map which is included in the main subject scheme map using <schemeref>:

Code: Select all

<schemeref href="subjectscheme_components.ditamap" />

Code: Select all

Engine name: DITA-OT

Severity: info

Description: [DOTJ045I] The key "my-doctype" is defined more than once in the same map file. The reference href="" is ignored.

Is this a (known) issue with the OT or do I have to look for any mistake on my side?

Kind regards,
Frank

[Radu]

Hi Frank,

I'm not sure, if you want you can send me to support@oxygenxml.com a small DITA project on which the problem can be reproduced and I could try to look into it.

Regards,
Radu

[Frank Ralf]

Hi Radu,

Thanks for your kind offer. I will do some more testing and evaluating, and if the issue persists I will send you a sample project.

Kind regards,
Frank

[Frank Ralf]

JFTR, Radu has written a great sum-up of all available options to provide controlled values in oXygen:
Controlled Attribute Values for your DITA Project

Frank

[Frank Ralf]

And here's part 2 (by Alex Jitianu) - great stuff! "Controlled Attribute Values (Part 2 - Advanced)"

[Frank Ralf]

Hi,

I'm getting the following message when working with a single subject scheme map.

Code: Select all

[DOTJ045I] The key "models" is defined more than once in the same map file. The reference href="" is ignored.

The map looks and works ok. http://www.dita-ot.org/1.8/readme/DITA- ... __DOTJ045I states:

No response is needed if the keys are defined as expected; this is informational only, to help catch incorrectly defined keys.

IMHO, this is a rather strange error message because in the end it leaves me clueless whether there is something wrong or not. Should I report this as an issue with the DITA-OT (https://github.com/dita-ot/dita-ot)?

Frank

[Radu]

Hi Frank,

Are you using DITA OT 1.8 or 2.0? I do not have enough details, maybe you could come up with a simple DITA Map sample project which exhibits the problem.

Regards,
Radu

[Frank Ralf]

Hi Radu,

sorry, I'm using oXygen 16.1 with the enclosed DITA-OT 1.8.5. Here's an excerpt from my subject scheme map:

Code: Select all

<subjectScheme>

	<title>Automotive Subject Scheme</title>

	

	<hasInstance>

		<subjectdef keys="models">

			<subjectdef keys="taifun" navtitle="parson Taifun" />

			<subjectdef keys="hurricane" navtitle="parson Hurricane" />

			<subjectdef keys="breeze" navtitle="parson Breeze" />

		</subjectdef>

	</hasInstance>



	<!-- OLD: as element -->

	<enumerationdef>

		<elementdef name="model" />

		<attributedef name="content" />

		<subjectdef keys="models" />

	</enumerationdef>



	<!-- OLD: for @product attribute -->

	<enumerationdef>

		<attributedef name="product" />

		<subjectdef keys="models" />

	</enumerationdef>



	<!-- NEW: as profiling attribute -->

	<enumerationdef>

		<attributedef name="model" />

		<subjectdef keys="models" />

	</enumerationdef>



  </subjectScheme>

My suspicion is that the DITA-OT cannot distinguish between all those <subjectdef keys="models" /> elements in different contexts. This is due to the IMHO unfortunate fact that the <subjectdef> element serves multiple purposes.

Kind regards,
Frank

[Radu]

Hi Frank,

The DITA 1.2 specs regards all keys as having global scope. So it does not matter in what hierarchy of subjectdef (which is a specialization of topicref) they are defined, the publishing engine will consider a single effective definition for the key models.
But you are using keys in this case to impose controlled attribute values so I don't think the publishing warning has any influence on the published output.

Regards,
Radu