Authoring
Issues with the 2019 authors’ use of DocBook led to the development of an Oxygen framework that extends the DocBook 5 framework by adding some Schematron checks for some of the issues. The stylesheets for the proceedings are now also bundled with the framework so that authors can preview how their paper will look in the proceedings. The framework is available as an Oxygen add-on that the Oxygen editor will offer to update whenever a new add-on release is made.
Figure 9. Edit in Oxygen and preview in AH Formatter GUI
The support for authoring went through three stages:
The extension framework and the Schematron file were available from the GitHub repository. [MUK-xsl] The Schematron was not used by the validation scenario defined in the framework.
Using the framework would require cloning the GitHub repository and configuring Oxygen to look for framework files in the cloned directory.
The “markupuk-2019-paper” repository from Markup UK 2019 [XMLPAPER] was forked to create a new GitHub repository. The Markup UK stylesheets were added as a submodule, and transformation scenarios were added for formatting using the stylesheets. The new repository was configured as a “template”: forking a template repository on GitHub generates a new repository with all of the current files in the template but without their revision history.
Because the new repository does not share any history with its template, if the template repository is updated – for example, to include updates to the XSLT stylesheets – the changes cannot be merged into the new repository. If, instead, the new repository was a fork of the original repository, it would be possible to update the new repository to reflect changes in the original repository. However, if the user has modified their project file, there is potential for an update to cause conflicts that would have to be fixed by editing the framework XML file.
The original framework repository was modified to include the stylesheets as a submodule and transformation scenarios to use the stylesheets were added. In addition, the Oxygen add-on definition file that was already in the repository was modified to refer to a Zip file from the repository as the location for the add-on’s files. For each new release, a new Zip file is generated and added to the files for the release. The add-on definition is updated to use the new version number and refer to the location of the new Zip file.
The framework now includes a template Oxygen project from which new Oxygen projects can be created. The template project includes a sample article that demonstrates some DocBook usage. It also defines some transformation scenarios, but these use the XSLT stylesheets from the framework rather than having the stylesheets bundled with each generated project. It is expected that the template project will not need to be updated very often. The most likely changes would be updates to the sample article, which would not affect an existing article.
Once Oxygen is configured to use the add-on definition, Oxygen will automatically detect new releases of the framework and offer to update it. This saves authors from needing to think about Git and Git submodules. If the template project is updated, the only way to get the changes is to create a new project and then copy files between the old and new projects. However, as stated previously, the template project is expected to not change very much.