Using @rev to track content on a per-project basis

Are you missing a feature? Request its implementation here.
chrispitude
Posts: 907
Joined: Thu May 02, 2019 2:32 pm

Using @rev to track content on a per-project basis

Post by chrispitude »

We are transitioning our writing team to DITA+Oxygen+Git. We are a software company (semiconductor industry). In each release cycle, a writer has between 5 and 40 software projects to document. Each software project has a project ID associated with it, in the form of XXX-YYY.

I would like to use DITA's @rev attribute to help our writers manage this. Each writer would set the @rev attribute to the pertinent project label as needed. For example, here are two topics with content related to TCL-001:

1.PNG
1.PNG (14.17 KiB) Viewed 3038 times
2.PNG
2.PNG (13.61 KiB) Viewed 3038 times

I would develop an external utility for Oxygen (Tools > External Tools) that finds all topics with @rev content, then creates/updates a <draftinto> topic in <frontmatter> that lists the topics by project:

3.PNG
3.PNG (30.55 KiB) Viewed 3038 times

The challenge is that the list of project IDs will vary for each writer, and there will be hundreds of project IDs across the writing team in each release cycle. It would be impossible to manage this as a centralized set of allowed @rev values in the *.xpr file is not workable.

(more to come when this post is approved; I appear to be limited to three attachments per post)
chrispitude
Posts: 907
Joined: Thu May 02, 2019 2:32 pm

Re: Using @rev to track content on a per-project basis

Post by chrispitude »

If I edit the XML directly to set the desired @rev value:

Code: Select all

<ph rev="TCL-001">To disable this feature, set the <codeph>sh_enable_line_editing</codeph> variable to <codeph>false</codeph> in the setup file.</ph>
then Oxygen gives me the following dialog the next time I invoke the profiling conditions dialog:

4.png
4.png (11.69 KiB) Viewed 3035 times

Somehow I need Oxygen to provide an interface where writers can define their own additional values for the @rev attribute, stored in the writer's user configuration instead of the project file:

5.PNG
5.PNG (14.33 KiB) Viewed 3035 times

Then I would need a way to tell Oxygen that the @rev attribute is free-form and might contain values not in the global set, and not to warn about them or prompt to add them to the project file (for when one writer opens a topic file with another writer's @rev values).

There is a lot of potential power here, and the @rev attribute is the perfect mechanism for flagging *and* tracking revisions. But I'll need some help from the authoring infrastructure to make it work.

Would anyone else find this useful, or have you solved this problem another way?
chrispitude
Posts: 907
Joined: Thu May 02, 2019 2:32 pm

Re: Using @rev to track content on a per-project basis

Post by chrispitude »

I should mention that the Revisions topic in the frontmatter serves multiple purposes:
  • Before starting a project, I can scope the work required by placing @rev placeholders in all the topics where I think changes will be needed for that project.
  • While working on a project, I can use the Revisions topic as a shortcut to all my "working areas" by using the Ctrl-Enter shortcut which opens the link target in the editor.
  • In the review PDF, the subject matter expert (SME) reviewers will use the Revisions topic to find and review only the topics relevant to their assigned projects.
Radu
Posts: 8992
Joined: Fri Jul 09, 2004 5:18 pm

Re: Using @rev to track content on a per-project basis

Post by Radu »

Hi Chris,

I added an internal issue with ID EXM-45205 with your details, maybe we can think about this situation in a future meeting.
For now maybe each writer would need to have their own custom project.xpr file.
Maybe you could consider using subject scheme maps:
https://www.oxygenxml.com/doc/versions/ ... e-map.html
but then again they do not seem a good fit with this extra flexibility that you want for each individual writer.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
chrispitude
Posts: 907
Joined: Thu May 02, 2019 2:32 pm

Re: Using @rev to track content on a per-project basis

Post by chrispitude »

Hi Radu,

My @rev feature thinking is a complicated feature, and it's asking CCMS-like functionality of an XML editing tool.

In the meantime, I have implemented a specialization of <draft-comment> called <project-label>, and we will just set @rev to 1.0:

project-label.PNG
project-label.PNG (15.39 KiB) Viewed 2986 times

It has some limitations:
  • It requires each writer to track their own list of labels and enter them each time without typos.
  • When multiple projects modify the same content, it doesn't clearly mark which @rev is for which project.
But it does allow us to proceed with some kind of project-tracking ability. I will report back here as I test this approach with the writers. And if it works well, I will share my <draftintro> project summarization script here.
chrispitude
Posts: 907
Joined: Thu May 02, 2019 2:32 pm

Re: Using @rev to track content on a per-project basis

Post by chrispitude »

Taking a slight detour for a support question... I noticed that when I insert a <draft-comment> element, it automatically populates the @author attribute. This is pretty cool! I'd like to implement this for a <project-label> specialization, but I can't figure out how it's implemented by looking in the following files:

Code: Select all

./frameworks/dita/dita_project/resources/cc_config.xml
./frameworks/dita/lw/resources/cc_config.xml
./frameworks/dita/plugin/cc_config.xml
./frameworks/dita/resources/cc_config.xml
How is this configured?
Radu
Posts: 8992
Joined: Fri Jul 09, 2004 5:18 pm

Re: Using @rev to track content on a per-project basis

Post by Radu »

Hi Chris,

The way this expansion works for draft-comment is via some Java code but it can be implemented also without Java.
What you want cannot be done using the cc_config.xml, we have an internal issue to make something like this work using the content completion configuration files (EXM-45200) and I added your contact details to it.
For now what you want could be done like this:

1) There is already an Oxygen editor variable called ${author.name} which gets expanded to the name of the author set in the preferences (exactly the value used by draft-comment):

https://www.oxygenxml.com/doc/versions/ ... ables.html

2) If you extend and edit the DITA document type in the Preferences->"Document Type Associations" page, in the "Author" tab there is an "Actions" subtab where you can define a new action, something like: https://blog.oxygenxml.com/topics/custo ... based.html

As base operation for your action choose the "InsertFragmentOperation" and as value for the "fragment" parameter set an XML fragment like:

Code: Select all

<project-label author="${author.name}"/>
https://www.oxygenxml.com/doc/versions/ ... toperation

3) After the action is defined go to the Author->Content Completion subtab and add the action in the content completion list.
In the "Filter - Remove content completion items" list add a new entry for "project-label" because it will eliminate the XML element proposed by the RelaxNG schema and replace it with your custom Author action.

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
Radu
Posts: 8992
Joined: Fri Jul 09, 2004 5:18 pm

Re: Using @rev to track content on a per-project basis

Post by Radu »

I've been meaning to blog about these steps for quite some time but I did not find the time for it yet:

https://github.com/oxygenxml/blog/issues/3

but at least the blog entry contains references to more detailed forum replies, like this one:

post51575.html#p51575

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
Radu
Posts: 8992
Joined: Fri Jul 09, 2004 5:18 pm

Re: Using @rev to track content on a per-project basis

Post by Radu »

Hi,

Just to update this thread, I wrote a small article on the Oxygen XML Blog about contributing an Author action to the content completion window:
https://blog.oxygenxml.com/topics/custo ... etion.html

Regards,
Radu
Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com
chrispitude
Posts: 907
Joined: Thu May 02, 2019 2:32 pm

Re: Using @rev to track content on a per-project basis

Post by chrispitude »

To follow up on this older discussion...

Our method of using <project-label> (specialized from <draft-comment>) to track per-project book updates is working well. And the latest version of Oxygen makes it easy to populate <project-label> with the writer's name via the following cc_config_ext.xml entry:

Code: Select all

<!-- automatically define the @author attribute for <project-label> elements -->
<elementProposals path="project-label">
  <insertAttribute name="author" value="${author.name}"/>
</elementProposals>
Radu - we no longer have a need for EXM-45205. Feel free to close it on your side. Thanks!

- Chris
Post Reply