wendellpiez / jatskit Goto Github PK

Two of the document types formally supported by the framework (and several more that are informally supported) permitted a JATS-defined close variant of the OASIS table model, which is to say an updated and slightly refined subset of a CALS/Docbook table model.

Additionally, all of the models also support an HTML-flavored table model.

A sample document https://github.com/wendellpiez/JATSKit/blob/develop/samples/pathological-blue.xml contains a couple of tables, both HTML and CALS/OASIS, and is suitable as a testbed for table-related functionality (as for other things).

Other frameworks in oXygen (notably Docbook and HTML) have a great deal of table-processing logic that could perhaps be adapted for JATS/BITS. Actions for table manipulation can be bound to buttons and menu items. In some cases this may be as simple as calling their .jar files in and using their APIs. In others there will have to be changes in the Java since although logic is the same, names are different (e.g. Docbook 'entry' vs JATS 'oasis:entry' as the name of an element.).

This also goes for testing things like the OASIS table Schematron checks I plan shortly to install ...

Maybe there are icons we can find somewhere (in an open-source framework library or collection?) for the Actions I have included in the base framework, for inserting MathML, boxed text and one or two items ... presently these show in the Toolbar as buttons with text labels.

Any tips on where to find a library of free-to-use icons?

One of our users has a DOCTYPE like this:

<!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Publishing DTD v1.1d1 20130915//EN" "https://jats.nlm.nih.gov/archiving/1.1/JATS-archivearticle1.dtd">

and Oxygen does not recognize the file as JATS. It should, even if it does not have the DTDs available, at least the visual editing will work if the user provides the DTDs via an additional XML catalog.

Currently, I'm testing various open-source solutions in order to implement a JATS XML publishing workflow, which includes the following steps:

1. Creating the original file in DOCX format, adhering to a pre-defined stylesheet
2. Pre-processing and converting the file from DOCX to JATS XML
3. Validating the JATS XML file
4. Converting the JATS XML file into XLIFF format for translation
5. Translating and reviewing using CAT tools (e.g., RWS Trados Studio)
6. Importing the translated content and generating the target JATS XML files
7. Performing a final proofreading
8. Publishing the original and translated documents in PDF, DOCX, and HTML formats

However, my coding experience is limited, and I'm facing difficulties with the DOCX to JATS XML conversion process. I can follow directions and can usually figure out programs. I also have oXygen XML Editor, but I'm still learning how to use it.

-- Could you please provide some tips or suggest the best approach to address this challenge?

I look forward to your guidance and greatly appreciate any assistance you can provide.

For whatever reason, the Schematron Quickfixes in the two Schematron files inside lib/Schematron are not working.

For example at https://github.com/wendellpiez/JATSKit/blob/develop/lib/Schematron/jatskit-QA.sch

I have double-checked namespaces but there's something missing. Perhaps not in the Schematron file itself. What would disable QuickFixes? (oXygen 17.1. And I looked at the panel under Options/Preferences.) This can be tested by binding the Schematron to the document by hand or by using a Validation Scenario in the editor.

The QuickFix I have (in the file cited) is supposed to add an @id to any of certain element types, which do not have one (matching '\S').

Support for tables involves two aspects:

1. Support for rendering tables + more complex table properties like horizontal and vertical spans, alignments of content in cells, etc.

2. Support for actions to insert a table, add rows and column, join and split cells, table properties.

JATS uses the CALS table model so (1) could be done only via CSS, probably part of it already works.

(2) can be done via Java extensions (the ones in the DITA and Docbook frameworks could serve as a model.

This would imply about one or two weeks of work.

A toolbar action which would show a dialog to the user for inserting a reference to an image resource.

It seems that a new version of JATS is available.
Should we update all the schemas to it or also leave the schemas for 1.0 and add the 1.1 schemas side by side + catalog entries?

Hi Wendell, found an issue with p:border-spec function within oasis-table-normalize.xsl. The top and bottom variables were ranking value of @rowsep above a value specified by .

These two lines seem to render proper borders:

<xsl:variable name="top" select="(($neighbor-up/@rowsep, $neighbor-up/parent::row/@rowsep, 
  $neighbor-up/p:colspec-for-entry(.)/@rowsep, $entry/ancestor::tgroup[1]/@rowsep, $entry/ancestor::table[1]/@rowsep)[1] = '1')
  or ($top-edge and $frame-spec=('top','topbot','all'))"/>
<!-- checking the entry likewise for $bottom -->
<xsl:variable name="bottom" select="(($entry/@rowsep, $entry/parent::row/@rowsep, 
  $entry/p:colspec-for-entry(.)/@rowsep, $entry/ancestor::tgroup[1]/@rowsep, $entry/ancestor::table[1]/@rowsep)[1] = '1')
  or ($bottom-edge and $frame-spec=('bottom','topbot','all'))"/>

1. Rename the project, right now it has JATS 1.0 in its name.
2. Modify the readme to also state JATS 1.1 instead of 1.0.
3. There is a templates folder on disk called "templates/bits" but the bits.framework is referencing to it like "templates/BITS", meaning that the new file template will not be available when working on Linux which is case sensitive.

Support to easily insert links to external or internal resources. This would imply a toolbar action which would probably show a dialog to the user allowing him to select a target for the link.
I do not know the type of links JATS has. Aare there also links to external resources or only internal IDREF-based links?

The current distribution includes jar files that flag security warnings.

@raducoravu can you offer any tips on how this can be updated?

Hi,

For whatever reason, it no longer works to point to https://github.com/wendellpiez/JATSKit/raw/develop/oXygenJATSframework.xml from the Add-ons panel under Options / Preferences in oXygen. Nothing happens when I select Apply, and the framework does not load.

I can, however, see the zip file at https://github.com/wendellpiez/JATSKit/archive/develop.zip as referenced.

But I seem to have broken the framework xml file somehow. (Radu, any idea?)

Thanks, Wendell

We recently had this feedback from one of our user:

   I am running an older version of oxygen author 17.1; and we recently upgraded our JATS from 1.0 to 1.3 we are now experiencing lots of rendering problems on our files when we publish them online. Does the new version of oxygen 24.1 support JATS 1.3? 

The end user seems to not necessarily want to add 1.3 schemas in the framework, but some updates on the publishing side.

@wendellpiez is there a certain place from which you added the original XSLTs for publishing JATS to HTML?

When you drop a resource (from the Oxygen project or Windows Explorer or Finder for example) in the Author visual editing mode a Java extension could be implemented to automatically add a proper link or image reference to the dropped resource.

If I have an XML file with this DOCTYPE:

 <!DOCTYPE article PUBLIC "-//NLM//DTD JATS (Z39.96) Journal Publishing DTD v1.1 20151215//EN" "http://jats.nlm.nih.gov/publishing/1.1/JATS-journalpublishing1.dtd">

1. The ""-//NLM//DTD JATS (Z39.96) Journal Publishing DTD v1.1 20151215//EN"" public ID is not mapped to any DTD, the jats-catalog.xml has a commented out reference to a missing DTD
2. The jatskit-catalog.xml also has commented out references to "-//NLM//DTD JATS (Z39.96) JATS DTD Suite MathML Setup Module v1.1 20151215//EN" and a missing "JATS-mathmlsetup1.ent" which seems to be found in the ZIP file:
   ftp://ftp.ncbi.nlm.nih.gov/pub/jats/publishing/1.1/JATS-Publishing-1-1-MathML2-DTD.zip

@wendellpiez should I update the jatskit-catalog.xml, un comment the inactive mappins and add the missing DTDs? Or is there a reason why the DTDs are not there in the first place?

When using "JATS/BITS single HTML page preview" to generate HTML preview from XML, the references are generated ok, but there are a few small issues. I attached the example (references_input.xml) with 7 references.

a) First 4 references from example are tagged within the same line, where references 5-7 are tagged in separate lines. Please run the transformation and you'll see the first 4 generate the right result, while 5-7 have some issues. The issues are gaps (empty spaces) between some elements. For instance reference 5 creates gaps here: May; 138( 5): 585– 8. The result should be without gaps like: May; 138(5): 585–8. I also spotted empty spaces on some other places where signs like "-(),;" are included.

b) Is there an option to fix/upgrade the "jatskit-html.xsl" (or maybe even better - create two new .xsl files) so the references first output will be "naked" without any links (no DOI, no PMID), while the second output would have both DOI and PMID links? I attached the word document (references_export.docx) how the format without links should look like and how it would be nice to improved html export with URL links included should look like. This means, the first format should not have DOI and PMID links at all, while the second format should have both links included, one as direct URL, the other also as URL, but in a format like PMID: 12345678. This will be then useful to create two different reference lists (true Vancouver style) for interactive PDF files and for publishing them online on various places.

references.zip

Now it's been a few months living with the "tighter" bindings (JATSKit now "turns on" only for documents with the latest FPIs) I am thinking we can loosen them up again, thereby providing JATSKit functionality back to older NLM DTD variants. It would probably do no harm if we do it right. And even if the current codebase isn't tested against (structures only in) the older DTDs, most things should still work.

Maybe something like an Association Rule in the base JATSKit framework -- whose priority should be Lowest in oXygen -- that matches it to either "NLM DTD" or "NISO Z39.96-2015" in a document's FPI. that should catch just about everything.

Note that as delivered right now, all the frameworks have Priority Setting Low -- the base framework is non-operational only because it doesn't match anything. (It is only a template.) If it also going to be the "fallback" framework for documents that appear NLM-like (by FPI) -- it should be set to Lowest.

As a side effect of #5 there seem to be various rendering problems, elements like "date" have an imposed size, the font sizes are larger in the Author mode.

@futurion in #46 proposed some CSS improvements, I will list some of them below:

1. Inside an "element-citation" some of the child sub-elements appear with display:block;. The problem cannot be reproduced for the same elements inside a "mixed-citation" element.
2. Better rendering inside "journal-meta, article-meta" elements, maybe we can for example add some static text before each child element.
3. Add in Author mode links to the specification for the "pub-id" elements with type "doi" or "pmid". By the way, are these the only possible types? How about others?

For (2) and (3), in the "Styles" drop down toolbar button there is a "JATSKit - enhanced" layer, I think I will make the changes there. The layer seems to also display some form controls but their widths are quite large, also for "xref" the rid is displayed twice, once with a text field and once with a combo. I can try to fix this as well.

When in the clipboard you have HTML flavor (for example when you copy content from the Web Browser or from MS Office) and you paste in the Author visual editing mode, there are Java extensions which could be implemented to apply an XSLT transformation over the HTML content and convert it to the JATS vocabulary. We do this for example for DITA and Docbook.
Basically this feature would mean that users could automatically convert articles written in MS Word or in HTML to JATS by copy-pasting.

For whatever reason I can't seem to get the insert.graphic Action (invoked via button) to work directly in the context of 'fig', where the element 'graphic' is permitted. It wants to insert 'inline-graphic' and it can't due to its being invalid.

We may wish to consider separate actions for (a) inserting single graphics (either 'graphic' or 'inline-graphic') depending on context, and (b) for inserting 'fig' elements with graphics and (optionally) captions.

<fig>
   <caption>
     <title>A Figure</title>
  </caption>
  <graphic xlink:href="..."/>
</fig>

We have an opportunity to build in more buttons, menu options etc., in some cases by comparing or adapting from other frameworks in oXygen. These bindings are configured by means of Actions at the framework level. Such Actions include support for table manipulation (both HTML and OASIS), but not only these - and of course the potential is open-ended.

On this issue, it would be nice to have a list of nice-to-have Actions.

For example, the Docbook framework has actions for promoting sections (Docbook sect1-sect6 elements); there is no reason that something similar would not work for the JATS/BITS sec element.

This may not be a high priority in view of how easy it is to move 'sec' elements around with simple drag-and-drop (in both Author and Outline views). But some people like buttons and menu items - and there are other possible ideas for Actions than these.

I have already added a couple of simple Actions for adding a couple of paragraph-level structures.

Feel free to contribute ideas to this discussion.

Toolbar actions for inserting unordered lists, ordered lists and list items. The equivalent functionality from the Docbook framework could be copied, this would not imply any Java extensions, just a framework configuration.

The addon is advertised to work with Oxygen 17 and newer. But recently in Oxygen 22.1 we upgraded the used logging system and the Java extensions used for the table related actions use the new type of logger, whose libraries are not part of Oxygen 22.0 and older.
My colleague Cosmin proposes a fix by adding the new logging libraries to the add-on:
#50
I will also ask him to provide a NOTICES file to state there that the logging libraries (Apache 2.0 license) are distributed with the add-on.

Keyboard shortcuts for some actions (3-4 actions) like "Monospace" are using platform dependent shortcuts like "CTRL M". This means that on Mac OSX it will not work as expected (using COMMAND M).
When you define a shortcut for an action you can check a checkbox to make it platform independent.

I fired up the old NCBI Preview XSL-FO and was able to produce PDF successfully on a JATS Orange (Authoring) document using AntennaHouse.

It errors in FOP, however, which does not support floats.

If there's a workaround for no floats in FOP please do make suggestions! but I'm afraid it's such a fundamental thing, that offering PDF via FOP isn't really viable.

This raises the question of (if the framework cannot offer a transformation that runs in FOP) how do we configure a Transformation Scenario in the framework to run the PDF conversion.

More on this - I just tried "quarantining" the floats by permitting them to be suppressed by a runtime parameter. Unfortunately I then hit a bug in FOP's handling of (apparently) lists -- ugly traceback.

This makes me think that even if the framework delivers an XSL that can generate PDF (from either/both JATS and BITS), it nonetheless can't include a Transformation Scenario that calls it.

(We can document how to create one, for users that have AH or XEP. But that's not ideal for a number of reasons.)

Consider zipping everything up and making it available as a hosted add-on for Oxygen.

See http://www.oxygenxml.com/doc/ug-editor/topics/dg-deploying-addons.html

We got this feedback:

I went to run the ePub conversion (oxygen 23, mac Big Sur) but I get a message that Calabash XProc is no longer available and I should reconfigure the transformation scenario. 

At some point we changed the name of the XProc engine used by Oxygen but we forgot to update its name in the pre-configured "JATSKit - NISO JATS / NLM BITS - EPUB" transformation scenario.

We have a client who uses the BITS 2.0 XSDs for validation.
Maybe we could also incorporate the DITA 2.0 XSDs in the framework.

https://www.oxygenxml.com/forum/viewtopic.php?f=1&t=21567

   I live in Slovenia where we use some scaron signs like "ŠĐČĆŽ - šđčćž". I noticed that when I convert the XML to "JATS/BITS single HTML page" all letters are displayed just fine.
   But when I try to generate the "JATS/BITS PDF preview", just letters Ž and Š are displayed ok, but letters Č and Ć aren't ok. If I try to insert a string like "ŠĐČĆŽ šđčćž" it looks then like this:
 PDF version: Š###Ž š###ž (not ok)

At least define in the XSLTs the "titlefont" and "textfont" variables as xsl:parameters in order to be accessible when editing an XSLT transformation scenario from Oxygen in the "Parameters" list.