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

Are you missing a feature? Request it's implementation here.
chrispitude
Posts: 144
Joined: Thu May 02, 2019 2:32 pm

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

Post by chrispitude » Wed Mar 11, 2020 8:58 pm

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 213 times
2.PNG
2.PNG (13.61 KiB) Viewed 213 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 213 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: 144
Joined: Thu May 02, 2019 2:32 pm

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

Post by chrispitude » Wed Mar 11, 2020 11:57 pm

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 210 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 210 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: 144
Joined: Thu May 02, 2019 2:32 pm

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

Post by chrispitude » Thu Mar 12, 2020 1:14 am

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: 6811
Joined: Fri Jul 09, 2004 5:18 pm

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

Post by Radu » Fri Mar 13, 2020 10:52 am

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: 144
Joined: Thu May 02, 2019 2:32 pm

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

Post by chrispitude » Fri Mar 13, 2020 3:01 pm

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 161 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: 144
Joined: Thu May 02, 2019 2:32 pm

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

Post by chrispitude » Tue Mar 17, 2020 5:36 pm

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: 6811
Joined: Fri Jul 09, 2004 5:18 pm

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

Post by Radu » Wed Mar 18, 2020 12:20 pm

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: 6811
Joined: Fri Jul 09, 2004 5:18 pm

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

Post by Radu » Wed Mar 18, 2020 12:22 pm

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: 6811
Joined: Fri Jul 09, 2004 5:18 pm

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

Post by Radu » Fri Mar 27, 2020 9:16 am

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

Post Reply