Add XML Production guide

[NateWr]

This issue is a place to discuss the development of a new XML Production guide. This guide is planned to cover how to set up the tools, what to expect from them, how to get the best results, and what training editorial staff will need.

[NateWr]

Here is a work-in-progress pull-request. I've prepared an initial outline of the XML production guide, written an intro, and ported over the user-facing documentation that @Vitaliy-1 has written for the DocxConverter.

This is a very early draft and open to a completely different structure/tone/audience.

To the DIG: does the outline and introduction look ok? how does it correspond to your expectations? did you have a different audience/intend in mind?

To XML team and interested parties: although we focus on one particular workflow, I've left a space to recommend other conversion tools. Which of these tools should we recommend?

@Vitaliy-1: I've only pulled over the documentation that I think is best directed at editorial staff. I think the technical side of the documentation, where you talk about cell merging, ooxml, etc, can be left in the plugin's readme since it's more technical. Does my draft look ok? Please add/edit as you see appropriate.

Lists: which numbered types are supported by docxconverter? Is it just 1/2/3 or do we support i/ii/ii and a/b/c? Any additional considerations to take into account when formatting lists for the converter?

Tables: I noticed that it says cells may appear with no paragraphs. But this was different from the specification we recommended to Libero. Should we change that with docxconverter?

Bibliography style and Google Docs: there's no way to do bibiliography style in Google Docs, right? That's what I've said.

@withanage: I've not yet drafted up the stuff on using Texture. Is this the best place to pull information from?

Also, what does the Texture plugin do when saving the citations back from Texture? Does it write them to the citations in OJS's database?

[NateWr]

Also, what does the Texture plugin do when saving the citations back from Texture? Does it write them to the citations in OJS's database?

Dulip said that so far it's only saved to the XML, not rendered back to OJS's citations table.

[withanage]

@NateWr

@withanage: I've not yet drafted up the stuff on using Texture. Is this the best place to pull information from?

yes, alongside I would take the handbook,

https://github.com/pkp/texture#handbook

I have written (although some screenshots , may be old ) , cause there I added the other functionalities which I created like Galley creation, DAR import and export. And also the very basic HTML ZIP import function is documented there.

[NateWr]

The handbook looks amazing! Is this in a Google Doc somewhere? Maybe someone from the DIG could take it and convert into a resource for the docs hub?

[Vitaliy-1]

Lists: which numbered types are supported by docxconverter? Is it just 1/2/3 or do we support i/ii/ii and a/b/c? Any additional considerations to take into account when formatting lists for the converter?

They are ordered and unordered only. I can extract some additional styling info from DOCX but it may not be consistent across text editors. I think the best would be to wait for JATS Editor release and then decide list styles mapping.

Tables: I noticed that it says cells may appear with no paragraphs. But this was different from the specification we recommended to Libero. Should we change that with docxconverter?

Paragraphs are removed at the post-conversion stage, on the plugin level, after JATS XML is outputted by the parsing library: https://github.com/Vitaliy-1/docxConverter/blob/master/classes/DOCXConverterDocument.inc.php#L130
That was done for compatibility reasons with the Texture. I always found this inconvenient as paragraphs are allowed by the standards. Once Libero Editor is in place, I have planned to remove this workaround. So, my mistake when writing docs - paragraphs, for now, are always removed.

Bibliography style and Google Docs: there's no way to do bibiliography style in Google Docs, right? That's what I've said.

To be more precise, Google Docs doesn't have bibliography style for paragraphs, although recently Google added the ability to include citations into the document, which anyway aren't exported in any structured way to DOCX.

[NateWr]

Note from XML discussion: when using Texture, don't try to use the references field in OJS. You'll need to use JATSParser, eLens or equivalent to publish from the XML directly.

[marcbria]

First thanks for all for the effort. I feel like is something the community was asking for and will enjoy a lot.

About this guide, I think we also need and introduction to contextualize/summarize what you will find in the rest of the document
So I will suggest adding an introduction to make a zoom-in approach (is this right in English), from a bird's eye view to the detailed documentation.

Even in a brief way, I think this introduction need to cover 3 main goals:

1. Explain the benefits and future potentials of an XML workflow for the different user's roles.
2. Explain the workflow itself (in ojs context), the tools involved/recommended and how those pieces fit together.
3. Suggest a "safe-path" or, till we don't have any, make it clear what tools are solid and will be compatible with any future work or experimental (and susceptible to changes).

About 1, we have plenty of documents that list those benefits, so just need to be adapted and summarized.
About 2, we will need to describe the workflow stages and tools. I'm biased but I think a variation of this diagram could help for a visual representation.
About 3, even nothing is never for sure, I think is important to make a recommendation, because nobody knows better than you 4 (you two, Vitaliy and James) what are the risks and the opportunities here.

What do you think?

[NateWr]

Thanks @marcbria. I think I've tried to 1-3 in the intro. Can you recommend some specific changes or identify places where the intro doesn't provide the right details?

[withanage]

@NateWr

Sure, I have attached the source word document and all the images, for the DIG team to have a look.
Texture_Handbook.docx
assets.zip