From cbea90fa8a27891134c4fb24bd4d9cd2739f110e Mon Sep 17 00:00:00 2001 From: Nate Wright Date: Thu, 1 Oct 2020 13:10:39 +0100 Subject: [PATCH 1/3] #492 Initial scaffold of XML Production guide --- xml-production/en/SUMMARY.md | 6 +++ xml-production/en/convert.md | 91 ++++++++++++++++++++++++++++++++++++ xml-production/en/edit.md | 21 +++++++++ xml-production/en/index.md | 32 +++++++++++++ xml-production/en/publish.md | 26 +++++++++++ xml-production/index.md | 8 ++++ 6 files changed, 184 insertions(+) create mode 100644 xml-production/en/SUMMARY.md create mode 100644 xml-production/en/convert.md create mode 100644 xml-production/en/edit.md create mode 100644 xml-production/en/index.md create mode 100644 xml-production/en/publish.md create mode 100644 xml-production/index.md diff --git a/xml-production/en/SUMMARY.md b/xml-production/en/SUMMARY.md new file mode 100644 index 000000000000..340fcbf1d645 --- /dev/null +++ b/xml-production/en/SUMMARY.md @@ -0,0 +1,6 @@ +# Summary + +* [Introduction](.) +* [Convert Files](./convert) +* [Copyedit and Typeset XML](./edit) +* [Publish and Distribute](./publish) \ No newline at end of file diff --git a/xml-production/en/convert.md b/xml-production/en/convert.md new file mode 100644 index 000000000000..16bc3033723e --- /dev/null +++ b/xml-production/en/convert.md @@ -0,0 +1,91 @@ +--- +title: Convert - XML Production - OJS +description: How to convert journal articles prepared in Microsoft Word, Google Docs or LibreOffice to JATS XML. +--- + +# Convert to JATS XML + +Scholarly articles are often written using software that is not compatible with JATS XML, such as Microsoft Word, Google Docs, and LibreOffice. These files must be converted to JATS XML. + +The DocxConverter plugin for OJS can convert these documents when they have been prepared correctly. This guide will describe how to install the plugin, how to prepare the document, and how to convert it to JATS XML. + +> System administrators may want to try other tools to convert documents to XML. These often require technical assistance to deploy, but in some cases they may provide a more accurate conversion. These tools include ... +{:.tip} + +## Install the DocxConverter Plugin + +... Step-by-step with screenshots or gifs... + +## Prepare the Document + +Limitations of DocxConverter (things not supported), need to prepare the document in advance, advice on training editorial staff + +The article's title, abstract, contributors, and other metadata should be stripped from the document. In OJS, this metadata (the frontmatter and backmatter of a JATS XML document) is handled separately from the main body of the article. The document should only include the main body of the article, and the references and citations. + +... Links to example documents in MS Word and Google Docs... + +### Paragraphs + +All paragraphs must have the "default" or "normal" style applied in the editor. + +... screenshot ... + +### Headings + +All headings must have one of the heading styles applied in the editor. Each section, such as the Introduction or Conclusion, should start at **Heading 1**. Any sub-sections should use **Heading 2**. + +... screenshot ... + +### Lists + +... + +### Tables + +All tables will be converted. However, table titles and captions can not be captured in the conversion process. After converting the document, table captions will appear as paragraphs and must be cleaned up when [copyediting and typesetting](./edit). + +### Bold, Italic, Superscript, Subscript, Underlined and Strikethrough + +All text must be formatted using the document editor's designated formatting tools, such as bold, italic, superscript, subscript, underlined and strikethrough. Any text formatting that indicates a font type or size will be removed when the document is converted in order to comply with the specifications of a JATS XML document. + +> Never use underline in text formatting if it can be avoided. When the article is published to the web, underlined text will be confused for a link and users may think the document is "broken". +{:.warning} + +### Figures, Charts and Images + +All figures, charts and images must be inserted into the document in `JPEG` or `PNG` format. Some editors allow charts and graphs to be imported and displayed directly from data. These charts and graphs must be replaced with an image in `PNG` format in order to be converted correctly. + +### References and Citations + +References and citations must have the "bibliography" style applied in the editor. This style is not typically found alongside the other styles and must be applied by locating it in the editor's advanced style settings. + +... screenshot or gif ... + +> Google Docs does not support a bibliography style. When using Google Docs, references and citations will need to be entered manually when [copyediting and typesetting](./edit). +{:.warning} + +References identified with the "bibliography" style will be imported as a `mixed-citation`. This means that the JATS XML will not be able to identify the distinct parts of a citation, such as the title, author or date. This information can be supplied manually when [copyediting and typesetting](./edit). + +> The [Zotero plugin for Microsoft Word](https://www.zotero.org/support/word_processor_plugin_usage) will insert structured references so that the converter can identify the distinct parts of a citation. Citations inserted by Zotero do not need to be manually corrected when [copyediting and typesetting](./edit), which will save a lot of time. +{:.tip} + +## Export the File + +When the document is prepared it must be exported in `docx` format. + +- In **Microsoft Word**, no additional action is needed to save the file in `docx` format. +- In **LibreOffice**, select File > Save as > Microsoft Word 2007-2013 XML (.docx). +- In **Google Docs**, select File > Download > Microsoft Word (.docx). + +## Upload to OJS + +... Step-by-step with screenshots or gifs... + +## Convert to JATS XML + +... Step-by-step with screenshots or gifs... + + +--- + +When the conversion is complete, editorial staff will need to [review and edit](./edit) the final document. diff --git a/xml-production/en/edit.md b/xml-production/en/edit.md new file mode 100644 index 000000000000..261e742f18c1 --- /dev/null +++ b/xml-production/en/edit.md @@ -0,0 +1,21 @@ +--- +title: Copyedit and Typeset - XML Production - OJS +--- + +# Copyedit and Typeset + +... + +## Install the Texture Plugin + +... + +## Edit the JATS XML File + +... + +## Limitations of Texture + +--- + +Once the article is typeset it can be [published](./publish). \ No newline at end of file diff --git a/xml-production/en/index.md b/xml-production/en/index.md new file mode 100644 index 000000000000..5c8f880fd03f --- /dev/null +++ b/xml-production/en/index.md @@ -0,0 +1,32 @@ +--- +title: XML Production - OJS +description: How to discover and use tools to convert, edit and publish journal articles in JATS XML. +--- + +# Introduction + +This document is a guide to the tools and editorial procedures that can be used with Open Journal Systems to prepare and publish articles in [JATS XML](https://en.wikipedia.org/wiki/Journal_Article_Tag_Suite), a widely used standard for publishing and distributing scholarly articles. It is written for journal managers, managing editors or system administrators who want to produce XML as part of their publishing efforts. + +JATS XML is a complex, technical specification for describing a journal in a machine-readable format. Typesetting an article in JATS XML can be a difficult process. However, once an article has been typeset in JATS XML it becomes possible to automate tasks, such as generating PDFs, depositing citation information, or data-mining research articles. + +This guide will help you navigate the options that are available, understand what to expect from them, set up and configure the tools for a journal, and train editorial staff to get the best results. + +## Production Workflow + +The XML production workflow recommended in this guide mixes is a three-step process that includes automated and manual tasks. + +1. The full text of an article's submission is [automatically converted](./convert) to JATS XML in a process that often introduces errors. +2. The JATS XML is then [manually copyedited and typeset](./edit) by editorial staff to correct errors and prepare the final proof. +3. When the article is [published](./publish), full-text HTML and PDFs are automatically generated from the JATS XML. + +This guide will focus on free, scholar-owned tools that the Public Knowledge Project recommends in order to accomplish each step, along with the limitations of these tools and any editorial guidelines needed to use them correctly. + +Many publishing services may be able to take advantage of other tools and services to perform some or all of these steps. For example, a publisher may contract with a professional typesetting service to perform the initial conversion process with fewer errors. Publishers with technical support staff may find it easier to implement their own tools for HTML and PDF generation. This guide will mention these alternatives but can not provide a recommendation. + +Learn how to take an author's submission file and [convert it to JATS XML](./convert). + +---- + +Copyright: Simon Fraser University holds the copyright for work produced by the Public Knowledge Project and has placed its documentation under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/). + +[![](https://licensebuttons.net/l/by/4.0/88x31.png "Creative Commons Attribution 4.0 International")](https://creativecommons.org/licenses/by/4.0/) diff --git a/xml-production/en/publish.md b/xml-production/en/publish.md new file mode 100644 index 000000000000..37eaca77d7eb --- /dev/null +++ b/xml-production/en/publish.md @@ -0,0 +1,26 @@ +--- +title: Publish - XML Production - OJS +description: How to publish from JATS XML to the web or a PDF. +--- + +# Publish with JATS XML + +... + +## Generate Full-Text + +...JATSParser and eLens... + +## Generate PDF Galley + +... + +## Deposit Citations + +... + +## A Note on Article Metadata + +Publishing professionals familiar with JATS XML may be familiar with tools that handle metadata, such as an article's title, abstract and keywords, when converting, editing or publishing XML. In OJS, this metadata (the frontmatter and backmatter of a JATS XML document) is handled separately from the main body of the article. + +For this reason, the conversion, editing and publishing tools described in this document focus on the article's main body and citations. Only when the article is published is the metadata and article body merged into a complete JATS XML document. \ No newline at end of file diff --git a/xml-production/index.md b/xml-production/index.md new file mode 100644 index 000000000000..3de4f1d30710 --- /dev/null +++ b/xml-production/index.md @@ -0,0 +1,8 @@ +--- +isBookIndex: true +--- +# XML Production + +How to discover and use tools to convert, edit and publish journal articles in JATS XML. + +* [English](en/) From 7b94aa6efce4e421f9efeb0e4f87aa7d21dcf464 Mon Sep 17 00:00:00 2001 From: Nate Wright Date: Thu, 1 Oct 2020 13:25:24 +0100 Subject: [PATCH 2/3] #492 Remove unnecessary word --- xml-production/en/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml-production/en/index.md b/xml-production/en/index.md index 5c8f880fd03f..82f3a7095f76 100644 --- a/xml-production/en/index.md +++ b/xml-production/en/index.md @@ -13,7 +13,7 @@ This guide will help you navigate the options that are available, understand wha ## Production Workflow -The XML production workflow recommended in this guide mixes is a three-step process that includes automated and manual tasks. +The XML production workflow recommended in this guide is a three-step process that includes automated and manual tasks. 1. The full text of an article's submission is [automatically converted](./convert) to JATS XML in a process that often introduces errors. 2. The JATS XML is then [manually copyedited and typeset](./edit) by editorial staff to correct errors and prepare the final proof. From a69c3f9d2c01264944e5216ae26f6e1c47557434 Mon Sep 17 00:00:00 2001 From: Nate Wright Date: Thu, 8 Oct 2020 16:52:07 +0100 Subject: [PATCH 3/3] #492 Add section for describing all XML tools --- xml-production/en/SUMMARY.md | 3 ++- xml-production/en/tools.md | 22 ++++++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) create mode 100644 xml-production/en/tools.md diff --git a/xml-production/en/SUMMARY.md b/xml-production/en/SUMMARY.md index 340fcbf1d645..1bbd56f8ddeb 100644 --- a/xml-production/en/SUMMARY.md +++ b/xml-production/en/SUMMARY.md @@ -3,4 +3,5 @@ * [Introduction](.) * [Convert Files](./convert) * [Copyedit and Typeset XML](./edit) -* [Publish and Distribute](./publish) \ No newline at end of file +* [Publish and Distribute](./publish) +* [Other Tools](./tools) \ No newline at end of file diff --git a/xml-production/en/tools.md b/xml-production/en/tools.md new file mode 100644 index 000000000000..02763baa1fbb --- /dev/null +++ b/xml-production/en/tools.md @@ -0,0 +1,22 @@ +--- +title: Other Tools - XML Production - OJS +description: A comprehensive overview of tools and software for JATS XML. +--- + +# JATS XML Tools + +...introduction... + +...diagram showing jats tools and which phases they can be used in... + +## name of tool + +... + +## name of tool + +... + +## name of tool + +... \ No newline at end of file