oxygenxml / oxygen-dita-prolog-updater-addon

Updates the author information, created and modified dates in the DITA prolog section for topics and maps.

Oxygen DITA Prolog Updater

Oxygen XML plugin that contributes a preferences page that includes various options for updating the "prolog" section of a DITA topic/map.

Compatibility

This add-on is compatible with Oxygen XML Editor (or XML Author) version 22.1 or higher.

How to install

1. In Oxygen, go to Help->Install new add-ons to open an add-on selection dialog box.
2. Enter or paste https://www.oxygenxml.com/InstData/Addons/default/updateSite.xml in the Show add-ons from field.
3. Select the DITA Prolog Updater add-on and click Next.
4. Read the end-user license agreement. Then select the I accept all terms of the end-user license agreement option and click Finish.
5. Restart the application.

Result: A DITA Prolog Updater preferences page will now be available in Options->Preferences->Plugins. This preferences page includes various options for updating the prolog section of a DITA topic or map.

The add-on can also be installed using the following alternative installation procedure:

1. Go to the Releases page and download the oxygen-dita-prolog-updater-{version}-plugin.jar file.
2. Unzip it inside {oXygenInstallDir}/plugins. Make sure you don't create any intermediate folders. After unzipping the archive, the file system should look like this: {oXygenInstallDir}/plugins/oxygen-dita-prolog-updater-x.y.z, and inside this folder, there should be a plugin.xmlfile.

Configuration

To configure the update options, go to Options->Preferences->Plugins->DITA Prolog Updater.

The following options can be set for DITA topics or maps (or both):

• Author: Specifies the name of the author. By default, it is the system user name.
• Date format: Specifies the format for the date added in the created date or revised date elements. If the specified format is invalid, yyyy/MM/dd is used as a fallback.
• Limit the number of revised dates to: Specifies the number of revisions that will be kept. Anytime a revised element is added in the prolog section and the specified limit has been reached, the oldest revised element is deleted.
• Custom type attribute value for the original author: Specifies a custom value for the type attribute of the author element that is inserted to specify the primary or original author of the content. If it is not set, the creator value is used.
• Custom type attribute value for an additional author: Specifies a custom value for the type attribute of the author element that is inserted to specify an additional author who is not the primary/original author. If it is not set, the contributor value is used.
• Enable automatic prolog update on save: When this option is selected, the prolog is updated anytime the document is saved.
• Set creator name: When this option is selected, the author is set as the document's creator in the prolog when the document is saved. This option is only applicable for new documents.
• Set created date: When this option is selected, a created date is added to the prolog when the document is saved. This option is only applicable for new documents.
• Update contributor names: When this option is selected, the author is set as a contributor in the prolog when the document is saved. This option is only applicable for already existing documents.
• Update revised dates: When this option is selected, a revised date is added to the prolog when the document is saved. This option is only applicable for already existing documents.

Copyright and License

Copyright 2018 Syncro Soft SRL.

This project is licensed under Apache License 2.0

oxygen-dita-prolog-updater-addon's Issues

Enable automatic build of plugin using Travis

Prevent "contributor" entry if author already exists as "creator"

Currently, the plugin will add the author as a contributor when a document is modified, even if they are already listed as the creator:

  <prolog>
    <author type="creator">chrispy</author>
    <author type="contributor">chrispy</author>
  </prolog>

Could you please provide a way to disable an author being listed twice, whether by default or as an option?

Thanks!

Ability to include/exclude DITA file types

Wondering if you could add an option to include/exclude files the the updater changes? For example, if we only want the revision elements added to topic files (e.g. task, concept, reference), but not DITA maps, we could exclude .ditamap. Thanks!

Only valid elements should be inserted

The plugin creates invalid markup. This should not happen.

<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="urn:oasis:names:tc:dita:spec:classification:rng:subjectScheme.rng" schematypens="http://relaxng.org/ns/structure/1.0"?> 
<subjectScheme>
    <subjectHead>
        <subjectHeadMeta>
            <author type="contributor">Stefan.Eike</author>   <!-- invalid -->
            <critdates>   <!-- invalid -->
                <!--Stefan.Eike-->
                <revised modified="2018/02/14"/>
            </critdates>
            <navtitle>
                <!-- Enter a description of the subject scheme. -->
            </navtitle>
        </subjectHeadMeta>
    </subjectHead>
    <!-- ... -->
</subjectScheme>

Consider if we should also implement this feature for opened and saved DITA Maps

A DITA Map also has a section where you can add similar information about the author and the modification dates:

    <map>
        <title></title>
        <topicmeta>
            <author></author>
            <critdates>
                <created date=""/>
                <revised modified=""/>
            </critdates>
        </topicmeta>
    </map>

so maybe we should do the same for DITA Maps. A DITA Map can be opened and created either in the main editor area or in the DITA Maps Manager and ideally this should work in both.
We should probably add a setting to disable this for people who do not want this behavior but our of the box, after installing the add-on probably all our settings should be checked and enabled.

Add comment with contributor.

Add a comment that contains the contributor above the revised tag.

Add author to DITA prolog section

The first time a DITA topic is created in Oxygen, the plugin could add information about the current author:

https://www.oxygenxml.com/dita/1.3/specs/langRef/base/author.html

And on subsequent times it could add information about the last author who modified it.
Basically it would look in the DITA topic, if it does not have a prolog section it would add it and if it has a prolog section it would update it to contain the author information:

    <prolog>
      <author type="creator">Jane</author>
      <author type="contributor">John</author>
    </prolog>

The plugin would add a listener to be notified when a WSEditor is opened.
On all opened WSEditor's it can add a save listener.
The listener has callbacks before each save operation. If the "ro.sync.exml.workspace.api.editor.WSEditorBase.isNewDocument()" returns true, then it is a new file and on the first save we need to set the author with type="creator".
If the document is not new, we can add an author of type contributor to it.

There is a configuration page where the end user can set their author name to be used.

Allow "creator" and "contributor" @type values to be configured

Starting with DITA 1.2, the @type attribute is not constrained to predefined values, as noted here:

https://docs.oasis-open.org/dita/v1.2/os/spec/langref/author.html

We would like to use owner instead of creator, as documentation sometimes gets reassigned from one writer to another. Could you please allow the plugin's creator and contributor values to be configured?

Thanks!

Ditamap with Existing Topicmeta Child Elements Without Critdates Broken on Update

Given the following DITA Prolog Updater options:

• Enable automatic prolog update on save = true
  • Set original author = false
  • Set created date = true
  • Update additional authors = false
  • Update revised dates = true

Any ditamap that has existing topicmeta child elements except for <critdates> becomes broken when the DITA Prolog Updater adds the <critdates> element. This is because the DITA schema for ditamaps is restrictive about the order of topicmeta child elements, and the add-on places the <critdates> element after the existing topicmeta child elements.

For example, a ditamap with the following structure:

<map>
    <title>Getting Started</title>
    <topicmeta>
        <othermeta name="classification" value="getting-started"/>
    </topicmeta>
    ...
</map>

Would become broken when the DITA Prolog Updater automatically adds the critdates element to the topicmeta:

<map>
    <title>Getting Started</title>
    <topicmeta>
        <othermeta name="classification" value="getting-started"/>
        <critdates>
            <revised modified="2023-04-04"/>
        </critdates>
    </topicmeta>
    ...
</map>

Add a preferences page

A plugin can add its own preferences page to Oxygen:

https://www.oxygenxml.com/doc/versions/19.1/ug-editor/topics/optionpage-plugin.html

Using such a preferences page users can configure their author name (defaults to the system user name), and maybe some checkboxes they can use in order to configure if they want the author name to be added to the prolog, if they want the created/modification dates to be added and so on....

Add created and revised dates to DITA prolog section

The DITA prolog can also have a created and a revised date:

https://www.oxygenxml.com/dita/1.3/specs/langRef/base/created.html
https://www.oxygenxml.com/dita/1.3/specs/langRef/base/revised.html

Again, depending on weather the topic is saved for the first time or on subsequent times, the prolog could be updated to contain this information every time the document is saved.

Option to overwrite existing prolog

Thank you very much for providing this plugin and continuing to update it! I've only done limited testing, but it appears that saving a changed DITA topic with an existing prolog appends the revised element with the current date. This means that each day we save the topic, the list of revised elements grows. I know we could simply delete the older revised elements, but is there an option to simply replace the existing revised element with the current date?

Allow configuration of date formats

I'd prefer to use ISO 8601 date formats (YYYY-MM-DD) in the prolog elements, but I don't see any way to configure that in the preferences or plug-in code.

Add Option to Ignore Changes to Prolog/Revised Date

Let's say I make a couple of minor revisions to a DITA topic, for example, fixing some typos and refactoring a bulleted list into a table. The contents of the topic itself have not fundamentally changed; therefore, I want the revised date of the topic to remain unchanged. Else my readers might expect to see brand new content.

It is understood and accepted that the addon automatically updates the revised date to the current day, regardless of the type of change, which is expected.

However, when attempting to manually override the automatically updated revised date to the previous date, the addon automatically changes the manually overridden date to the current date preventing me from manually overriding the date.

I would like an option in the Preferences to have the addon ignore any changes made to the prolog and any of its child elements. This will enable me to manually override the updated revised date in these instances where I determine that the contents of the topic have not actually changed.

Thanks!

If DITA topic is not wellformed and prolog updating is disabled I still get a warning message

Oxygen should not report the topic is not wellformed because the prolog updater is disabled.