oxygenxml / blog Goto Github PK

Oxygen XML Editor Blog Posts

Shell 0.10% Batchfile 0.05% CSS 1.96% HTML 92.17% XSLT 0.96% JavaScript 4.73% Dockerfile 0.04%

blog's Introduction

Oxygen XML Web Author Monitoring plugin

This plugin is used to provide monitoring information from a running Web Author instance.

Web Author collects various metrics about its runtime behavior. It can be configure to report these metrics in a number of ways.

In the browser

To access the information you should access one of the following URLs Note that you have to be logged in the Administration Page when visiting these URLs.

http://host:port/oxygen-xml-web-author/plugins-dispatcher/monitoring/threads - to get thread dumps of all threads
http://host:port/oxygen-xml-web-author/plugins-dispatcher/monitoring/metrics - to get various metrics about Web Author

In the server logs

By default, the monitoring information is written in JSON format in the server logs every minute. You can use various tools to parse this information and present a graphical dashboard.

To a Graphite server

You have to set the GRAPHITE_SERVER environment variable in order for Web Author to send monitoring information to this server.

To AWS CloudWatch

You have to set the following environment variables:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_REGION
https_proxy - in cases you use one

By extending this plugin you can send the collected metrics also to other metrics servers.

Custom configuration

The name of the logger used by this plugin to log the above information is NO_LAYOUT_LOGGER.METRICS

WebAuthor default configuration defines a logger named NO_LAYOUT_LOGGER. This logger has a console appender with no layout, so any child logger (with a naming scheme NO_LAYOUT_LOGGER.<LOGGER_NAME>) will log only the messages to stdout.

To override this default configuration, a NO_LAYOUT_LOGGER.METRICS logger must be defined explicitly in WebAuthor logging configuration.

Copyright and License

This project is licensed under Apache License 2.0

blog's People

Contributors

Stargazers

Watchers

Forkers

airquick zhoufansky dcwise rekcuz chrispy-snps jeanniebacon alexsmarandache15 dunamariuscosmin tsweeney73 sorincarbunaru kirkilj dorinajitianu

blog's Issues

Blog post about generating a list of changes between releases

Create Blog post about generating a list of changes between releases

Common XSLT pitfalls

Converted from internal issue EXM-42907
Discuss about various problems beginners encounter when doing XSLT

apply templates versus xsl:copy
Know on what content you are matching
debug xsl:message and printstacktrace
Generic template match versus a more specific one.
xsl:next-match
apply templates excluding attribute
template match //
How are relative references resolved document() and result-document()
Match more items than expected using xsl:value-of
Not typing your function's paramaters and variables
Difference between variables and parameters
Copy template, match only elements, default match templates
default attributes, recognizing default attributes when matching Schematron rules.

See:
http://gandhimukul.tripod.com/xslt/xslquality.html
https://github.com/mricaud/xslt-quality

Blog Post - Creating and sharing a customization at project level

Migrated from internal EXM-43467.
@georgebina presented for one of our partners how settings and frameworks can be saved at project level options, he created a small sample project for it:

https://github.com/oxygenxml/oXygenDITAProject

Attaching a small topic I created for a similar presentation:
customizing_the_dita_editing_experience_using_oxygen_xml_editor.zip

Explain how a custom dictionary with custom terms can be built for spell checker

Converted from internal issue: EXM-44574
Starting with Chris's explanation here:

https://www.oxygenxml.com/forum/topic20897.html

Add support for a new XML vocabulary

Converted from internal issue: EXM-37912
Document a step by step procedure for adding support for an new XML vocabulary in Oxygen: validation, content completion, new file templates, custom CSS, custom Author actions, custom Schematron rules maybe.

Pasting an older answer I gave at some point:

Oxygen comes bundled with out of the box support for several XML vocabularies. If you look in the Oxygen Preferences->"Document Type Association" page you can see a list of them.
For all other XML vocabularies like Pubmed, support for editing can be added to Oxygen.

For example you can add new file templates:

https://www.oxygenxml.com/doc/versions/18.1/ug-editor/topics/create-your-own-templates.html

If you have access to the schemas used for the Pubmed vocabulary, you can configure Oxygen to use those schemas for validating the Pubmed XML documents.
You can download the schemas locally and if there is a "catalog.xml" catalog file included, you can go to the Oxygen Preferences->"XML / XML Catalog" page and add there a reference to the XML catalog.
Oxygen will also use the schemas information to propose content completion entries when editing the XML documents.

Customizing content completion item in Author mode

Converted from internal issue: EXM-42806
Based on this answer:
https://www.oxygenxml.com/forum/post51575.html#p51575

Oxygen add-ons Overview

I need a small article with some kind of overview of Oxygen's capability for add-ons.
I will use it at XML Prague.

Using MathML Equations with DITA

Converted from internal issue EXM-38364

Pasting an answer I gave some time ago:

Yes, embedded MathML works fine for me with DITA-OT 2.2.x. Please follow these steps:

To add DITA support for MathML:

Download jeuclid-core-3.1.9.jar, jeuclid-fop-3.1.9.jar and put them in DITA-OT/plugins/org.dita.pdf2.fop/fop/lib

Install dita community plugins:

Download the archive:

https://github.com/dita-community/dita13-dita-ot-1.x-support/releases/download/1.0.2/dita13-support-toolkit-plugins-1.0.2.zip

Unpack and copy 3 directories to DITA-OT/plugins/ (doctypes plugin is not needed since DITA-OT 2.2.0):

org.dita-community.common.xslt

org.dita-community.dita13.html

org.dita-community.dita13.pdf

Enable character entities by replacing “IGNORE” with “INCLUDE” on line 81:

DITA-OT/plugins/org.oasis-open.dita.v1_3/dtd/technicalContent/dtd/mathml/mathml3-ditadriver.dtd

<!ENTITY % mathml-charent.module "INCLUDE" >

Please also make sure to correctly embed MathML into your DITA files. I use "equation-figure" element to embed mathml. Here is an example:
<equation-figure>
<mathml>
<m:math xmlns:m="http://www.w3.org/1998/Math/MathML">
<m:mi>x</m:mi>
</m:math>
</mathml>
</equation-figure>

I need to create a formula with a square root symbol. How can this be accomplished in DITA 1.2?

Example using the non-existing element <square-root> to illustrate what I want to do:

dE<sub>ab</sub> = <square-root>(dL)<sup>2</sup>(da)<sup>2</sup>(db)<sup>2</sup></square-root>

Is there a DITA-OT plug-in (compatible with V1.7.1) that allows me to use such elements?

DITA 1.3 has support for embedding MathML content. But if that looks
right in the published HTML-based output depends on the web browser.
Referencing the MathJax Javascript libraries in the generated HTML
content helps:

http://blog.oxygenxml.com/2013/10/using-mathjax-to-properly-view-mathml.html

As possible other approached you can either refer to a binary image
containing the formula or somehow dynamically convert the mathml to a
binary image when the publishing is done. Or have the equation available
as an SVG image and refer to it. SVG recently started being supported
quite well by web browsers.

An easy workaround is to create your equation in an editor and insert it as graphic.

DITA for Publishers includes support for MathML that predates DITA 1.3 by many years—it’s now obsolete in the face of DITA 1.3’s support for MathML but it does work with DITA 1.2 as long as you can integrate the domains into your document types.

Otherwise using images or some custom-built version of the DITA 1.3 mathmlref will be your only options.

Go to MathML Cloud, insert your equation in mathml and process it. Copy the SVG out and use that SVG as an image in your document. You may have to add some fonts in your processing but that is an easy way to do one or a few equations and get them in highest quality format that work with both browsers and PDF renderers,

Blog post about how to install add-ons when offline

We ahev a lot of plugins packed as addons. If users are offline, they can't access the internet, an administrator needs to download these packages and put them in a proper location for Oxygen to load them.

Something that I wrote to one of our users that faced this challenge:

All these add-ons are represent frameworks and plugins that are unpacked inside a predefined location. In your case this location is:

- For frameworks: C:\Users\{user}\AppData\Roaming\com.oxygenxml\extensions\v22.0\frameworks

- For plugins: C:\Users\{user}\AppData\Roaming\com.oxygenxml\extensions\v22.0\plugins

If you look inside these folders you will notice an additional level of folders, like a namespace, before the actual plugins/frameworks.

Instead of using the add-on mechanism to install them, you can manually download the packages and put them inside one of he locations where Oxygen looks for plugins/frameworks. This location can be the previously mentioned location, assuming you respect the folder structure, or the default one:

- put plugins inside {oxygenInstallDir}/plugins

- put frameworks inside {oxygenInstallDir}/frameworks

The frameworks/plugins packages can be found by opening those update sites into Oxygen, using the Open URL action on the toolbar. An XPath expression like this pinpoints the packages:

/xt:extensions/xt:extension/xt:location/@href

If we are to refer to the ones you enumerated, their corresponding packages are these:

1. Plugins

https://www.oxygenxml.com/maven/com/oxygenxml/oxygen-cgm-plugin/21.1.0.2/oxygen-cgm-plugin-21.1.0.2-plugin.jar

https://github.com/xspec/oXygen-XML-editor-xspec-support/releases/download/1.6.1/xspec.support-1.6.1-plugin.zip

https://www.oxygenxml.com/maven/com/oxygenxml/oxygen-patched-jsonix-schema-compiler/22.1.0.0/oxygen-patched-jsonix-schema-compiler-22.1.0.0-plugin.jar

2. Frameworks:

https://github.com/xspec/oXygen-XML-editor-xspec-support/releases/download/1.6.1/xspec.support-1.6.1-framework.zip

No feed?

I would like to subscribe this "blog" but it lacks Atom (RSS) feed?

Using PlantUML diagrams in DITA topics (editing and publishing)

Converted from: EXM-44686
We have a plugin which allows seeing such diagrams in the Author visual editing mode:

https://github.com/oxygenxml/wsaccess-javascript-sample-plugins/tree/master/plantuml-images-support

and a plugin which handles the publishing part here:

https://github.com/oxygenxml/dita-plant-uml

So the blog post would need to discuss about these two extensions.

Blog post about how to switch from a project file to an add-on

One of our end users has an already configured Oxygen project which has a framework, transformation scenarios, layout templates and they want to pack it as an add-on.
Pasting below @AlexJitianu 's answer to them:

Hello,

An Oxygen project file is very powerful and versatile and it groups many settings in it, like you've already configured. You can pack as an add-on either a framework or a plugin. The good news is that a plugin can do pretty much what an xpr does. In your case:

Distribute a framework [1]. You put the framework directory inside the plugin's directory and then you edit the {{plugin.xml}} file and add something like this ({{@path}} is relative to {{plugin.xml}}):
{code:xml}

{code}

Layout file. The Impose Options [1] plugin can impose a layout file, too. {{README.html}} describes how to name it and where to place it.
Templates. The Impose Options [1] plugin can contribute templates, too. {{README.html}} describes how to do that. Please note that templates can also be defined inside the framework. If you put the templates inside the framework [3] then you can just skip this step.
Options. In your case, these might be the transformation scenarios used in publishing. The procedure from my previous email describes how to prepare the scenarios. Please note that transformation scenarios can also be defined inside the framework [4], in your case the custom_dita framework folder which is an extension of the default DITA framework. If this is indeed how the transformation scenarios are configured, then you don't actually need to do anything for them. The simple fact that you've done 1. means that you have contributed the scenarios as well.

bq. Is it possible to bundle all these into single add-on and enforce the restrictions and schematron rules through the add-on?
So the answer is yes, but the project file is no longer the glue that binds these pieces together. The plugin is. And the plugin is packed and distributed as an add-on.

bq. I gave it a try but the add-on unzips the content of the add-on to {{\AppData\Roaming\com.oxygenxml\extensions\v22.1\frameworks\http_ip:8091_ngaddons.xml}}
That is the default location where add-ons are deployed.

bq. But I don’t see any configuration changes in Oxygen nor does the project bundled with the plugin automatically load in Oxygen? Wondering how I can make this work.
If you've zipped the contents of your project directory then your settings will not be loaded. Your zip must be an Imposed Options plugin [2] that was changed and enriched with your files as described above.

Have you tried using the Impose Options [2] plugin as a starting point for your add-on? If you have something already then you can send me the add-on archive to take a look at it. If I notice something amiss then I'll tell you how to fix it and I will remove it from my system afterwards.

Anyway, to try and summarize all of these, I recommend you to:

Put the templates inside the framework [3]
Put the transformation scenarios inside the framework.
Put the framework inside the Impose Options plugin
Put the layout file inside the Impose Options plugin
The Impose Options plugin directory is what you need to need to zip and and deploy as an add-on.

Your Impose Options plugin directory should look like this:
{code}
oxygen-sample-plugin-impose-options-22.1
lib
oxygen-sample-plugin-impose-options-22.1.jar
plugin.xml
Framework
application.layout
{code}
To make the framework load, {{plugin.xml}} should contain this line:
{code:xml}

{code}
I hope this helps! let me know if you need additional details. If you can send me the resulting archive, then I can analyze it to see is everything is O.K.

[1] https://www.oxygenxml.com/doc/versions/22.1/ug-editor/topics/additional-framework-extension.html

[2] https://www.oxygenxml.com/maven/com/oxygenxml/samples/oxygen-sample-plugin-impose-options/22.1.0.0/oxygen-sample-plugin-impose-options-22.1.0.0-plugin.jar

[3] https://www.oxygenxml.com/doc/versions/22.1/ug-editor/topics/sharing-templates.html

[4] https://www.oxygenxml.com/doc/versions/22.1/ug-editor/topics/document-type-transformation-tab.html

Add PDF and EPUB downloads for blog

Add links to the footer to downloadable PDF and EPUB which are created on the fly.

Spell check entire site

Apply automatic spell checker on entire site, learn words and force auto correct setting at project level.

Before or after the fact validation

Converted from internal issue EXM-38781.

Discuss about these different types of validation: before and after the content is inserted.

An answer I gave some time ago:

All the automatic validation that we do is "after the fact" validation, validation which is performed on the current state of the edited document.
Because it may take a while on large documents validation is done on a separate parallel thread in order not to block the user from editing so we cannot block the user interaction with the keyboard (for example user types "a" and we need to validate an entire document before inserting "a" in the document).

I'm thinking about this particular case, I've filled forms which add these restrictions recently and I would find it very frustrating if the application rejected my input. For example I may paste a small fragment of text from some place else. I know the text is too long but after I paste I want to review the entire short description and make it shorter.

We have Java-based API which could be used to intercept editing events from the end user and maybe reject the event if it would make the document not valid in a way. So if you want to try this approach I could try to give you some hints, the checks would no longer use Schematron but you could have similar Java-implemented rules.

In the meantime maybe you can report the overflow of the shortdesc as an error and also in the Preferences->"Editor / Open/Save" page we have a "Check errors on save" checkbox which your writers could check in order to be notified before save that there are still problems in the document.

Add validate and check for completeness

After the web site is built from the DITA content we can apply validate and check for completeness using the Oxygen validate and check for completeness script, then move the report here:

https://oxygenxmlblog.netlify.com/validationReport.xml

DITA For Small Teams Using Oxygen XML and private GitHub projects

Converted from internal issue: EXM-44582
Explain in great detail how GitHub can be used to collaborate on a technical documentation project.

Create GitHub account
Create organisation
Create private GitHub project
Install Git plugin in Oxygen standalone.
Work with History view and Blame in the plugin.
Show how WebAuthor can be used to edit GitHub files.
Discuss workflow, pull commit, push,
Merging conflicts
Adding and solving GitHub issues
Maybe give some steps about publishing using Oxygen WebHelp plugin and Netlify

Add "Welcome" topic

Add a welcome topic to the blog.

Extending framework to customize XML Refactoring operations

Converted from internal issue: EXM-39769

Give precise steps somebody who wants to share refactoring operations needs to do in order to extend and modify the DITA framework.

Oxygen editor variables - use cases

Converted from internal issue EXM-42833
Blog post about using editor variables in various places, maybe give some interesting examples.

Use cases for Oxygen editor variables:

Transformation scenarios - output folder, parameters, xpath_eval
Code templates - selection, caret, xpath_eval
New File templates
Author operations - ask editor variable in operation parameters.
Examples

Add contributed author name and date to generated posts

Extract prolog information from DITA topics to display author name and publishing date.
So each contributed topic needs to have a prolog like this one:

<prolog>
    <author>Radu Coravu</author>
    <critdates>
        <created date="2020-01-14" class="- topic/created "/>
    </critdates>
</prolog>

Tutorial about using a chatbot with DITA content

Equivalent of internal issue: EXM-43530