From f354080382ca9daf61059e6a56e1279c297229db Mon Sep 17 00:00:00 2001
From: julientaq <julien@coko.foundation>
Date: Fri, 7 Jan 2022 02:08:58 +0100
Subject: [PATCH] add articles
---
src/articles-index.md | 2 +-
src/articles/SSP-Kotahi/entry1.md | 289 ------------------
src/articles/articles.json | 6 +-
.../{SSP-JATS/entry2.md => ssp-jats.md} | 5 +-
src/articles/ssp-kotahi.md | 289 ++++++++++++++++++
.../entry1.md => ssp1.md} | 12 +-
.../entry2.md => ssp2.md} | 21 +-
.../entry3.md => ssp3.md} | 21 +-
.../entry4.md => ssp4.md} | 15 +-
.../entry5.md => ssp5.md} | 19 +-
.../entry6.md => ssp6.md} | 25 +-
src/layouts/article-single.njk | 9 +-
src/layouts/articles-index.njk | 35 ++-
static/css/theme-coko/main.css | 24 ++
.../uploads/{SSP => }/A1-Img1-and-A4-img4.jpg | Bin
static/images/uploads/{SSP => }/A1-Img2.jpg | Bin
static/images/uploads/{SSP => }/A2-Img1.jpg | Bin
static/images/uploads/{SSP => }/A2-Img2.jpg | Bin
static/images/uploads/{SSP => }/A2-Img3.jpg | Bin
static/images/uploads/{SSP => }/A2-Img4.jpg | Bin
static/images/uploads/{SSP => }/A3-Img1.jpg | Bin
static/images/uploads/{SSP => }/A3-Img2.jpg | Bin
static/images/uploads/{SSP => }/A3-Img3.jpg | Bin
static/images/uploads/{SSP => }/A3-Img4.jpg | Bin
static/images/uploads/{SSP => }/A4-Img1.jpg | Bin
static/images/uploads/{SSP => }/A4-Img2.jpg | Bin
static/images/uploads/{SSP => }/A4-Img3.jpg | Bin
static/images/uploads/{SSP => }/A5-Img1.jpg | Bin
static/images/uploads/{SSP => }/A5-Img2.jpg | Bin
static/images/uploads/{SSP => }/A6-Img1.jpg | Bin
static/images/uploads/{SSP => }/A6-Img2.jpg | Bin
static/images/uploads/{SSP => }/A6-Img3.jpg | Bin
static/images/uploads/{SSP => }/A6-Img4.jpg | Bin
static/images/uploads/{SSP => }/A6-Img5.jpg | Bin
static/images/uploads/{SSP => }/A6-Img6.jpg | Bin
static/images/uploads/{SSP => }/A6-Img7.jpg | Bin
.../img01.png => sspKotahi-01.png} | Bin
.../img02.png => sspKotahi-02.png} | Bin
.../img03.png => sspKotahi-03.png} | Bin
.../img04.png => sspKotahi-04.png} | Bin
.../img05.png => sspKotahi-05.png} | Bin
.../img06.png => sspKotahi-06.png} | Bin
.../img07.png => sspKotahi-07.png} | Bin
.../img08.png => sspKotahi-08.png} | Bin
.../img09.png => sspKotahi-09.png} | Bin
.../img10.png => sspKotahi-10.png} | Bin
.../img11.png => sspKotahi-11.png} | Bin
.../img12.png => sspKotahi-12.png} | Bin
.../img13.png => sspKotahi-13.png} | Bin
49 files changed, 407 insertions(+), 365 deletions(-)
delete mode 100644 src/articles/SSP-Kotahi/entry1.md
rename src/articles/{SSP-JATS/entry2.md => ssp-jats.md} (97%)
create mode 100644 src/articles/ssp-kotahi.md
rename src/articles/{SingleSourcePublishing/entry1.md => ssp1.md} (97%)
rename src/articles/{SingleSourcePublishing/entry2.md => ssp2.md} (93%)
rename src/articles/{SingleSourcePublishing/entry3.md => ssp3.md} (93%)
rename src/articles/{SingleSourcePublishing/entry4.md => ssp4.md} (94%)
rename src/articles/{SingleSourcePublishing/entry5.md => ssp5.md} (97%)
rename src/articles/{SingleSourcePublishing/entry6.md => ssp6.md} (96%)
rename static/images/uploads/{SSP => }/A1-Img1-and-A4-img4.jpg (100%)
rename static/images/uploads/{SSP => }/A1-Img2.jpg (100%)
rename static/images/uploads/{SSP => }/A2-Img1.jpg (100%)
rename static/images/uploads/{SSP => }/A2-Img2.jpg (100%)
rename static/images/uploads/{SSP => }/A2-Img3.jpg (100%)
rename static/images/uploads/{SSP => }/A2-Img4.jpg (100%)
rename static/images/uploads/{SSP => }/A3-Img1.jpg (100%)
rename static/images/uploads/{SSP => }/A3-Img2.jpg (100%)
rename static/images/uploads/{SSP => }/A3-Img3.jpg (100%)
rename static/images/uploads/{SSP => }/A3-Img4.jpg (100%)
rename static/images/uploads/{SSP => }/A4-Img1.jpg (100%)
rename static/images/uploads/{SSP => }/A4-Img2.jpg (100%)
rename static/images/uploads/{SSP => }/A4-Img3.jpg (100%)
rename static/images/uploads/{SSP => }/A5-Img1.jpg (100%)
rename static/images/uploads/{SSP => }/A5-Img2.jpg (100%)
rename static/images/uploads/{SSP => }/A6-Img1.jpg (100%)
rename static/images/uploads/{SSP => }/A6-Img2.jpg (100%)
rename static/images/uploads/{SSP => }/A6-Img3.jpg (100%)
rename static/images/uploads/{SSP => }/A6-Img4.jpg (100%)
rename static/images/uploads/{SSP => }/A6-Img5.jpg (100%)
rename static/images/uploads/{SSP => }/A6-Img6.jpg (100%)
rename static/images/uploads/{SSP => }/A6-Img7.jpg (100%)
rename static/images/uploads/{SSP-Kotahi/img01.png => sspKotahi-01.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img02.png => sspKotahi-02.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img03.png => sspKotahi-03.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img04.png => sspKotahi-04.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img05.png => sspKotahi-05.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img06.png => sspKotahi-06.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img07.png => sspKotahi-07.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img08.png => sspKotahi-08.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img09.png => sspKotahi-09.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img10.png => sspKotahi-10.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img11.png => sspKotahi-11.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img12.png => sspKotahi-12.png} (100%)
rename static/images/uploads/{SSP-Kotahi/img13.png => sspKotahi-13.png} (100%)
diff --git a/src/articles-index.md b/src/articles-index.md
index 4cee728..c3ca1a1 100644
--- a/src/articles-index.md
+++ b/src/articles-index.md
@@ -2,7 +2,7 @@
title: Articles
layout: articles-index.njk
permalink: /articles/index.html
-menu: false
+menu: true
menutitle: Articles
class: articles
order: 5
diff --git a/src/articles/SSP-Kotahi/entry1.md b/src/articles/SSP-Kotahi/entry1.md
deleted file mode 100644
index 59b7f59..0000000
--- a/src/articles/SSP-Kotahi/entry1.md
+++ /dev/null
@@ -1,289 +0,0 @@
----
-title: "White Paper: Kotahi Current State"
-subtitle: ""
-date: "2021-09-15"
-author: Adam Hyde
-# image: Coko.png
----
- The Kotahi workflow is very configurable and can support very linear, to very concurrent,
- workflows. In addition, the submission types supported are configurable. These two features together mean that
- Kotahi can support a wide variety of use cases and workflow models.</p>
- <p class="paragraph">This document outlines Kotahi as it is configured for a typical Journal workflow. Please note
- that this is just one configured pathway and many parts of what you will see in this document are configurable to
- meet your needs.</p>
- <p class="paragraph"><em>Please note—Kotahi is undergoing heavy continuous development. For an insight into
- the current issues please see </em><a href="https://gitlab.coko.foundation/kotahi/kotahi/-/issues?state=opened"
- rel target="blank"><em>here</em></a><em>. Some pre-recorded demos are provided, please click on the demo icon to
- review. In addition, all images can be clicked on for a more detailed view. This White Paper is a light
- overview, for in depth detail please contact Coko (email included below) for a full demo and discussion.</em>
- </p>
- <h2>Typical Journal Workflow</h2>
- <p class="paragraph">For the purposes of this document we will look at the following configuration which is being
- used by the Aperture Neuro journal (Organization of Human Brain Mapping).</p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img01.png">
- <figcaption class="decoration">Aperture Workflow in Kotahi</figcaption>
- </figure>
- <p class="paragraph">The Aperture workflow in sequential notation looks something like this:</p>
- <ol>
- <li>
- <p class="paragraph">Author creates new submission (a link, attachment, or ingested docx)</p>
- </li>
- <li>
- <p class="paragraph">Author completes submission data</p>
- </li>
- <li>
- <p class="paragraph">Author submits</p>
- </li>
- <li>
- <p class="paragraph">Managing Editor views manuscript</p>
- </li>
- <li>
- <p class="paragraph">Managing Editor desk reject (can reject submission)</p>
- </li>
- <li>
- <p class="paragraph">Managing Editor assigns to Senior Editor</p>
- </li>
- <li>
- <p class="paragraph">Senior Editor checks manuscript</p>
- </li>
- <li>
- <p class="paragraph">Senior Editor assigns to Handing Editor</p>
- </li>
- <li>
- <p class="paragraph">Handling Editor assigns Reviewers</p>
- </li>
- <li>
- <p class="paragraph">Reviewers accept / decline invitation</p>
- </li>
- <li>
- <p class="paragraph">Reviewers review</p>
- </li>
- <li>
- <p class="paragraph">Reviewers submit review</p>
- </li>
- <li>
- <p class="paragraph">Handling Editor makes decision (accept/revise->goto 9)</p>
- </li>
- <li>
- <p class="paragraph">Handling Editor publishes (production covered later in this document)</p>
- </li>
- </ol>
- <p class="paragraph">We can break the above into 4 high level stages:</p>
- <ol>
- <li>
- <p class="paragraph">Author submission (steps 1,2,3)</p>
- </li>
- <li>
- <p class="paragraph">Editor Assignment (steps 4,5,6,7,8)</p>
- </li>
- <li>
- <p class="paragraph">Reviewer Assignment and Review (steps 10,11,12)</p>
- </li>
- <li>
- <p class="paragraph">Editor Decision (steps 13,14)</p>
- </li>
- </ol>
- <p class="paragraph">The following sections will look at each stage and the associated user Interfaces.</p>
- <h3>Author Submission</h3>
- <h4>Login</h4>
- <p class="paragraph">All users authenticate before they can use Kotahi. Aperture supports the ORCID OAuth protocol
- and process. However this can be replaced by any shared login system or with a sign-up and sign-in process. Upon
- login all users are directed to their Dashboard where they can view all the manuscripts they are working on (as
- authors, reviewers, or editors).</p>
- <h4>Submission Types</h4>
- <p class="paragraph">Kotahi supports any type of filetype as a submission attachment as well as link submissions
- (for submitting code stored in repositories or Jupyter notebook instances etc).</p>
- <p class="paragraph">In addition, if a submission is in MS Word docx format then Kotahi will ingest and convert the
- file into an internal stored and editable data format for editing in Kotahi’s internal <a
- href="https://waxjs.net/" rel target="blank">Scholarly Word Processor</a>. In this later mode, Kotahi becomes a
- complete Single Source Publishing system (more on this later).</p>
- <h4>Submission Form</h4>
- <p class="paragraph">Submission data can be captured by user entry with the Submission Form. The creation and
- ongoing maintenance of the Submission Form is done by the Journal Admin with the internal Form Creation user
- interface (see later in this document).</p>
- <p class="paragraph">Please see below for the Aperture form captured in its entirety (click to see the entire form).
- </p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img02.png">
- <figcaption class="decoration">Example Submission Form</figcaption>
- </figure>
- <h4>Submission</h4>
- <p class="paragraph">Upon completion of the submission form, the manuscript and its associated declarations and data
- can be submitted. The author will be asked to agree to any terms and conditions (configurable) before the material
- can be submitted. Upon submission, the state for the manuscript changes from ‘unsubmitted’ to
- ‘submitted’—this information (current state) is displayed on the Dashboard as well as in many
- other places throughout Kotahi.</p>
- <h3>Editor Assignment</h3>
- <p class="paragraph">Editors break down to the following generic roles:</p>
- <ul>
- <li>
- <p class="paragraph">Managing Editor</p>
- </li>
- <li>
- <p class="paragraph">Senior Editor</p>
- </li>
- <li>
- <p class="paragraph">Handling Editor</p>
- </li>
- <li>
- <p class="paragraph">Editor (misc)</p>
- </li>
- </ul>
- <p class="paragraph">Editors can view manuscripts they are associated with via the Dashboard as well as seeing all
- manuscripts on the Manuscripts Page (permissions permitting).</p>
- <h4>Manuscripts Page</h4>
- <p class="paragraph">The Managing Editor can view new submissions via the Manuscripts Page (click to enlarge).</p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img03.png">
- <figcaption class="decoration">Kotahi Manuscripts Page (with example data)</figcaption>
- </figure>
- <p class="paragraph">Columns can be sorted by Creation Dates, State etc.</p>
- <p class="paragraph">Managing Editors (ME) can choose a new (or any) manuscript to view by clicking on
- ‘View’. Alternatively, the ME can click on ‘Control Panel’ to view the manuscript,
- submission data, and the submission’s associated workflow controls.</p>
- <h4>Control Panel</h4>
- <p class="paragraph">The Control Panel displays the Manuscript, Submission Data and workflow controls for the
- selected manuscript as per below (click to enlarge).</p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img04.png">
- <figcaption class="decoration">Kotahi Control Panel</figcaption>
- </figure>
- <p class="paragraph">Please note, the above screenshot is soon to be replaced with three separate tabs for 1)
- workflow controls 2) manuscript 3) submission data (as per <a
- href="https://gitlab.coko.foundation/kotahi/kotahi/-/issues/621" rel target="blank">this issue</a>).</p>
- <p class="paragraph">From the Control Panel, the ME can reject the manuscript or assign a Senior Editor. Upon
- assigning a Senior Editor, the manuscript will appear on the Dashboard for that editor. The Senior Editor can then
- access the Control Panel for that manuscript, view the manuscript and data, and assign a Handling Editor.</p>
- <h3>Reviewer Assignment and Review</h3>
- <p class="paragraph">The Handling Editor (HE) can access the Control Panel for the manuscript from their Dashboard.
- They can then review the manuscript and submission data. The next step is for the HE to invite reviewers. The
- Invite Reviewers page is accessible via the Control Panel.</p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img05.png">
- <figcaption class="decoration">Kotahi Reviewer Management</figcaption>
- </figure>
- <p class="paragraph">At this stage of invitation, the editor can also decide if the reviewer is doing their own
- review or a shared review.</p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img06.png">
- <figcaption class="decoration">Reviewer Management showing shared review option</figcaption>
- </figure>
- <p class="paragraph"><em>Screenshot taken from CB (t.b.a) Instance</em></p>
- <p class="paragraph">Reviewers receive an email with the invitation to review the manuscript. Contained in the email
- is additional information about the manuscript (this is set via the Form Builder, see below).</p>
- <p class="paragraph">The reviewer can then accept or reject the invitation via their Dashboard (soon also via the
- email). The Reviewer can then access the manuscript, filtered submission data, and the review form via the
- Dashboard. The Review Page has a section for writing the review and attaching files:</p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img07.png">
- <figcaption class="decoration">Kotahi Reviewer Form</figcaption>
- </figure>
- <h3>Editor Decision</h3>
- <p class="paragraph">When reviews are complete, the HE can access the reviews via the Control Panel for the
- manuscript and decide on whether to accept, reject, or request a revision. Secondary revision types are managed
- through email templates (see below).</p>
- <p class="paragraph">The HE can write their response to the author in the panel provided. The text is shown to the
- author on the submission form (connected to versions, see below).</p>
- <p class="paragraph">The author can then revise both the submission data and the manuscript and resubmit. The
- process continues until the article is ready to publish. Editors can assign the same reviewers, or new reviewers
- per round.</p>
- <h2>Communication</h2>
- <p class="paragraph">Kotahi leverages many realtime tools for communication as well as utlizing its own email
- template system. Realtime communication is supported by ‘presence indicators’ to indicate if a user
- is logged in at that time. Also supported is live video communication for the editorial staff (linked from the
- Manuscripts Page). Live chat is also available per submission for communication between authors and editorial
- staff, as well as private chats for the editorial staff to discuss the submission.</p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img08.png">
- <figcaption class="decoration">Kotahi Chat (Author view)</figcaption>
- </figure>
- <p class="paragraph"><em>Author—Editor chat embedded in the author submission pane (click to enlarge).</em>
- </p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img09.png">
- <figcaption class="decoration">Kotahi Chat (Editorial view)</figcaption>
- </figure>
- <p class="paragraph"><em>Editorial chat for staff only (per manuscript).</em></p>
- <p class="paragraph">Emails can be sent for each manuscript via the email template controls. The Publisher can
- configure as many templates as they like. Emails can be sent to existing users or people with no account. A record
- of all emails sent is kept as a retrievable log within the editorial staff chat.</p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img10.png">
- <figcaption class="decoration">Email Management</figcaption>
- </figure>
- <p class="paragraph"><em>Screenshot taken from the CB instance of Kotahi.</em></p>
- <h2>Versions</h2>
- <p class="paragraph">Submissions are managed per revision round. Each round creates a new version of both the
- submission data and the manuscript attachments/internal content store. Revision history can be browsed by authors
- and editorial staff alike. Earlier versions cannot (of course) be edited.</p>
- <h2>Single Source Publishing</h2>
- <p class="paragraph">If docx files are submitted, Kotahi can be a complete end-to-end <a
- href="https://coko.foundation/single-source-publishing/" rel target="blank">Single Source Publishing</a> System.
- Docx content is ingested and converted to Kotahi’s internal data format. The content is then editable via
- the Wax web-based word processor built into Kotahi.</p>
- <h2>JATS</h2>
- <p class="paragraph">The JATS production interface is currently being built. The JATS production interface will also
- support automated PDF output via <a href="https://pagedjs.org/" rel target="blank">pagedjs</a>, and SEO optimised
- HTML for pushing to publish interfaces.</p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img11.png">
- <figcaption class="decoration">JATS Export</figcaption>
- </figure>
- <h2>Publishing</h2>
- <p class="paragraph">Aperture is going live with the FLAX publish front end. Flax is a new product from Coko which
- is connects directly to Kotahi for realtime publishing of articles while being a completely extensible CMS for
- building entire Journal sites. Kotahi has an extensible ingestion API and publishing API. These APIs allow for a
- vast variety of (for example) publishing integrations. NCRC, for example publish to a Google spreadsheet (since
- they are processing existing preprint URLs) as well as registering reviews with DOIs on Crossref. If the target
- system for publishing offers an integration endpoint of any kind, then Kotahi can integrate with it.</p>
- <h2>The Form Builder</h2>
- <p class="paragraph">The Form Builder sounds humble but it is an immensely powerful tool. The Form Builder enables
- the admin/ME to build the submission forms using a web interface. However, the interface also allows for the
- tagging of each field with unique IDs (useful for building JATS/XML at export time), identifying which fields will
- be shown to reviewers when inviting them to review, controlling taxonomy, identifying which columns are displayed
- on the Manuscripts Page, and it can even be used to extend the Control Panel UI. The Form Builder will
- increasingly become an central part of the Kotahi platform. Form Builders are much underestimated.</p>
- <h2>Reports</h2>
- <p class="paragraph">Reports are integrated into Kotahi and are pretty comprehensive. We have opted for dynamic
- rendering to improve the user enjoyment of the Kotahi UI.</p>
- <h2> Workflow Configuration</h2>
- <p class="paragraph">There are immense workflow configuration options. So far, almost all are via config files but
- we have a UI config manager design. While we will use the above workflow, the following are two workflow examples
- for the Novel Coronavirus Research Consortium and CBinstances:</p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img12.png">
- <figcaption class="decoration"><em>NCRC Kotahi Workflow</em></figcaption>
- </figure>
- <p class="paragraph"></p>
- <p class="paragraph"></p>
- <figure><img
- src="images/uploads/SSP-Kotahi/img13.png">
- <figcaption class="decoration">CB Kotahi Workflow</figcaption>
- </figure>
- <p class="paragraph"></p>
- <h2>Summary</h2>
- <p class="paragraph">Kotahi is a modern scholarly publishing platform. It is built with modern technologies with
- modern, efficient workflows in mind. The platform is also very modular, extensible, and configurable. There is
- almost no element of the system that is immutable—all elements can be changed if required. In addition
- Kotahi leverages modern realtime communication protocols and together with the Single Source Publishing design the
- entire system offers publishers enormous futureproofing and workflow optimization opportunities.</p>
- <p class="paragraph">Lastly, <em>all</em> aspects of Kotahi are open source and liberally licensed (MIT). Coko
- exists to support organizations wanting to hire us to extend Kotahi or go it alone. In all development scenarios,
- Coko facilitates the multiple organizations extending Kotahi to ensure the community is building upon each
- other’s work—this helps ensure lowering the burden of development cost and time as well as
- eliminating possible duplication of efforts.</p>
- <p class="paragraph">For more information contact Adam Hyde—<a href="http://adam@coko.foundation" rel
- target="blank">adam@coko.foundation</a></p>
diff --git a/src/articles/articles.json b/src/articles/articles.json
index bc523c7..4a4407b 100644
--- a/src/articles/articles.json
+++ b/src/articles/articles.json
@@ -1,4 +1,4 @@
-{
- "layout": "article-single.njk" ,
- "permalink": "/articles/{{ title | slug }}/{{subtitle | slug if subtitle}}"
+{
+ "layout": "article-single.njk",
+ "permalink": "/articles/{{title | slugify}}.html"
}
diff --git a/src/articles/SSP-JATS/entry2.md b/src/articles/ssp-jats.md
similarity index 97%
rename from src/articles/SSP-JATS/entry2.md
rename to src/articles/ssp-jats.md
index 1606cfe..190aaee 100644
--- a/src/articles/SSP-JATS/entry2.md
+++ b/src/articles/ssp-jats.md
@@ -8,7 +8,9 @@ tags: featured
class: ""
icon: "/images/uploads/kotahi-jats-V2-500x500.jpg"
---
+
<!-- link for checking: http://localhost:8080/articles/single-source-publishing-and-jats/ -->
+
In general, Journals (and many of the family of workflows associated with publishing research) require 3 output types – HTML, PDF, and JATS.
Along with finding reviewers, this requirement for document preparation (generally called typesetting) is one of the big publishing bottlenecks. The tooling and processes for typesetting can be complex so it is also difficult for Journal staff to do this themselves. The result is that many ‘throw it over the wall’ to an outsourced vendor. This incurs costs which may or may not be affordable for the Journal. The back and forth with vendors also prolongs the time to publish. In addition, conversion costs are added to the total cost of production and passed along, sooner or later, to subscribing institutions (such as universities), funders, or the researchers (in the case of Open Access via Article Processing Charges).
@@ -23,9 +25,8 @@ However, outputting HTML and PDF is not enough if you cannot also output JATS. I
So, finally (finally!) Coko has been working on an easy-to-use tool to produce JATS at (almost!) the press of a button. This is our newly released WAX-JATS editor.
-
+
The WAX-JATS editor (pictured above) is currently integrated into Kotahi and is very easy to use. No specialist JATS knowledge is required.
The following short series of articles will look at the problem, some of the previous solutions, and discuss how the new WAX-JATS software addresses this issue.
-
diff --git a/src/articles/ssp-kotahi.md b/src/articles/ssp-kotahi.md
new file mode 100644
index 0000000..4ff4109
--- /dev/null
+++ b/src/articles/ssp-kotahi.md
@@ -0,0 +1,289 @@
+---
+title: "White Paper: Kotahi Current State"
+subtitle: ""
+date: "2021-09-15"
+author: Adam Hyde
+# image: Coko.png
+---
+
+<p>The Kotahi workflow is very configurable and can support very linear, to very concurrent,
+workflows. In addition, the submission types supported are configurable. These two features together mean that
+Kotahi can support a wide variety of use cases and workflow models.</p>
+<p class="paragraph">This document outlines Kotahi as it is configured for a typical Journal workflow. Please note
+that this is just one configured pathway and many parts of what you will see in this document are configurable to
+meet your needs.</p>
+<p class="paragraph"><em>Please note—Kotahi is undergoing heavy continuous development. For an insight into
+the current issues please see </em><a href="https://gitlab.coko.foundation/kotahi/kotahi/-/issues?state=opened"
+rel target="blank"><em>here</em></a><em>. Some pre-recorded demos are provided, please click on the demo icon to
+review. In addition, all images can be clicked on for a more detailed view. This White Paper is a light
+overview, for in depth detail please contact Coko (email included below) for a full demo and discussion.</em>
+</p>
+<h3>Typical Journal Workflow</h3>
+<p class="paragraph">For the purposes of this document we will look at the following configuration which is being
+used by the Aperture Neuro journal (Organization of Human Brain Mapping).</p>
+<p class="paragraph"></p>
+<figure><img src="/images/uploads/sspKotahi-01.png">
+<figcaption class="decoration">Aperture Workflow in Kotahi</figcaption>
+</figure>
+<p class="paragraph">The Aperture workflow in sequential notation looks something like this:</p>
+<ol>
+<li>
+<p class="paragraph">Author creates new submission (a link, attachment, or ingested docx)</p>
+</li>
+<li>
+<p class="paragraph">Author completes submission data</p>
+</li>
+<li>
+<p class="paragraph">Author submits</p>
+</li>
+<li>
+<p class="paragraph">Managing Editor views manuscript</p>
+</li>
+<li>
+<p class="paragraph">Managing Editor desk reject (can reject submission)</p>
+</li>
+<li>
+<p class="paragraph">Managing Editor assigns to Senior Editor</p>
+</li>
+<li>
+<p class="paragraph">Senior Editor checks manuscript</p>
+</li>
+<li>
+<p class="paragraph">Senior Editor assigns to Handing Editor</p>
+</li>
+<li>
+<p class="paragraph">Handling Editor assigns Reviewers</p>
+</li>
+<li>
+<p class="paragraph">Reviewers accept / decline invitation</p>
+</li>
+<li>
+<p class="paragraph">Reviewers review</p>
+</li>
+<li>
+<p class="paragraph">Reviewers submit review</p>
+</li>
+<li>
+<p class="paragraph">Handling Editor makes decision (accept/revise->goto 9)</p>
+</li>
+<li>
+<p class="paragraph">Handling Editor publishes (production covered later in this document)</p>
+</li>
+</ol>
+<p class="paragraph">We can break the above into 4 high level stages:</p>
+<ol>
+<li>
+<p class="paragraph">Author submission (steps 1,2,3)</p>
+</li>
+<li>
+<p class="paragraph">Editor Assignment (steps 4,5,6,7,8)</p>
+</li>
+<li>
+<p class="paragraph">Reviewer Assignment and Review (steps 10,11,12)</p>
+</li>
+<li>
+<p class="paragraph">Editor Decision (steps 13,14)</p>
+</li>
+</ol>
+<p class="paragraph">The following sections will look at each stage and the associated user Interfaces.</p>
+<h3>Author Submission</h3>
+<h4>Login</h4>
+<p class="paragraph">All users authenticate before they can use Kotahi. Aperture supports the ORCID OAuth protocol
+and process. However this can be replaced by any shared login system or with a sign-up and sign-in process. Upon
+login all users are directed to their Dashboard where they can view all the manuscripts they are working on (as
+authors, reviewers, or editors).</p>
+<h4>Submission Types</h4>
+<p class="paragraph">Kotahi supports any type of filetype as a submission attachment as well as link submissions
+(for submitting code stored in repositories or Jupyter notebook instances etc).</p>
+<p class="paragraph">In addition, if a submission is in MS Word docx format then Kotahi will ingest and convert the
+file into an internal stored and editable data format for editing in Kotahi’s internal <a
+href="https://waxjs.net/" rel target="blank">Scholarly Word Processor</a>. In this later mode, Kotahi becomes a
+complete Single Source Publishing system (more on this later).</p>
+<h4>Submission Form</h4>
+<p class="paragraph">Submission data can be captured by user entry with the Submission Form. The creation and
+ongoing maintenance of the Submission Form is done by the Journal Admin with the internal Form Creation user
+interface (see later in this document).</p>
+<p class="paragraph">Please see below for the Aperture form captured in its entirety (click to see the entire form).
+</p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-02.png">
+<figcaption class="decoration">Example Submission Form</figcaption>
+</figure>
+<h4>Submission</h4>
+<p class="paragraph">Upon completion of the submission form, the manuscript and its associated declarations and data
+can be submitted. The author will be asked to agree to any terms and conditions (configurable) before the material
+can be submitted. Upon submission, the state for the manuscript changes from ‘unsubmitted’ to
+‘submitted’—this information (current state) is displayed on the Dashboard as well as in many
+other places throughout Kotahi.</p>
+<h3>Editor Assignment</h3>
+<p class="paragraph">Editors break down to the following generic roles:</p>
+<ul>
+<li>
+<p class="paragraph">Managing Editor</p>
+</li>
+<li>
+<p class="paragraph">Senior Editor</p>
+</li>
+<li>
+<p class="paragraph">Handling Editor</p>
+</li>
+<li>
+<p class="paragraph">Editor (misc)</p>
+</li>
+</ul>
+<p class="paragraph">Editors can view manuscripts they are associated with via the Dashboard as well as seeing all
+manuscripts on the Manuscripts Page (permissions permitting).</p>
+<h4>Manuscripts Page</h4>
+<p class="paragraph">The Managing Editor can view new submissions via the Manuscripts Page (click to enlarge).</p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-03.png">
+<figcaption class="decoration">Kotahi Manuscripts Page (with example data)</figcaption>
+</figure>
+<p class="paragraph">Columns can be sorted by Creation Dates, State etc.</p>
+<p class="paragraph">Managing Editors (ME) can choose a new (or any) manuscript to view by clicking on
+‘View’. Alternatively, the ME can click on ‘Control Panel’ to view the manuscript,
+submission data, and the submission’s associated workflow controls.</p>
+<h4>Control Panel</h4>
+<p class="paragraph">The Control Panel displays the Manuscript, Submission Data and workflow controls for the
+selected manuscript as per below (click to enlarge).</p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-04.png">
+<figcaption class="decoration">Kotahi Control Panel</figcaption>
+</figure>
+<p class="paragraph">Please note, the above screenshot is soon to be replaced with three separate tabs for 1)
+workflow controls 2) manuscript 3) submission data (as per <a
+href="https://gitlab.coko.foundation/kotahi/kotahi/-/issues/621" rel target="blank">this issue</a>).</p>
+<p class="paragraph">From the Control Panel, the ME can reject the manuscript or assign a Senior Editor. Upon
+assigning a Senior Editor, the manuscript will appear on the Dashboard for that editor. The Senior Editor can then
+access the Control Panel for that manuscript, view the manuscript and data, and assign a Handling Editor.</p>
+<h3>Reviewer Assignment and Review</h3>
+<p class="paragraph">The Handling Editor (HE) can access the Control Panel for the manuscript from their Dashboard.
+They can then review the manuscript and submission data. The next step is for the HE to invite reviewers. The
+Invite Reviewers page is accessible via the Control Panel.</p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-05.png">
+<figcaption class="decoration">Kotahi Reviewer Management</figcaption>
+</figure>
+<p class="paragraph">At this stage of invitation, the editor can also decide if the reviewer is doing their own
+review or a shared review.</p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-06.png">
+<figcaption class="decoration">Reviewer Management showing shared review option</figcaption>
+</figure>
+<p class="paragraph"><em>Screenshot taken from CB (t.b.a) Instance</em></p>
+<p class="paragraph">Reviewers receive an email with the invitation to review the manuscript. Contained in the email
+is additional information about the manuscript (this is set via the Form Builder, see below).</p>
+<p class="paragraph">The reviewer can then accept or reject the invitation via their Dashboard (soon also via the
+email). The Reviewer can then access the manuscript, filtered submission data, and the review form via the
+Dashboard. The Review Page has a section for writing the review and attaching files:</p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-07.png">
+<figcaption class="decoration">Kotahi Reviewer Form</figcaption>
+</figure>
+<h3>Editor Decision</h3>
+<p class="paragraph">When reviews are complete, the HE can access the reviews via the Control Panel for the
+manuscript and decide on whether to accept, reject, or request a revision. Secondary revision types are managed
+through email templates (see below).</p>
+<p class="paragraph">The HE can write their response to the author in the panel provided. The text is shown to the
+author on the submission form (connected to versions, see below).</p>
+<p class="paragraph">The author can then revise both the submission data and the manuscript and resubmit. The
+process continues until the article is ready to publish. Editors can assign the same reviewers, or new reviewers
+per round.</p>
+<h3>Communication</h3>
+<p class="paragraph">Kotahi leverages many realtime tools for communication as well as utlizing its own email
+template system. Realtime communication is supported by ‘presence indicators’ to indicate if a user
+is logged in at that time. Also supported is live video communication for the editorial staff (linked from the
+Manuscripts Page). Live chat is also available per submission for communication between authors and editorial
+staff, as well as private chats for the editorial staff to discuss the submission.</p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-08.png">
+<figcaption class="decoration">Kotahi Chat (Author view)</figcaption>
+</figure>
+<p class="paragraph"><em>Author—Editor chat embedded in the author submission pane (click to enlarge).</em>
+</p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-09.png">
+<figcaption class="decoration">Kotahi Chat (Editorial view)</figcaption>
+</figure>
+<p class="paragraph"><em>Editorial chat for staff only (per manuscript).</em></p>
+<p class="paragraph">Emails can be sent for each manuscript via the email template controls. The Publisher can
+configure as many templates as they like. Emails can be sent to existing users or people with no account. A record
+of all emails sent is kept as a retrievable log within the editorial staff chat.</p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-10.png">
+<figcaption class="decoration">Email Management</figcaption>
+</figure>
+<p class="paragraph"><em>Screenshot taken from the CB instance of Kotahi.</em></p>
+<h3>Versions</h3>
+<p class="paragraph">Submissions are managed per revision round. Each round creates a new version of both the
+submission data and the manuscript attachments/internal content store. Revision history can be browsed by authors
+and editorial staff alike. Earlier versions cannot (of course) be edited.</p>
+<h3>Single Source Publishing</h3>
+<p class="paragraph">If docx files are submitted, Kotahi can be a complete end-to-end <a
+href="https://coko.foundation/single-source-publishing/" rel target="blank">Single Source Publishing</a> System.
+Docx content is ingested and converted to Kotahi’s internal data format. The content is then editable via
+the Wax web-based word processor built into Kotahi.</p>
+<h3>JATS</h3>
+<p class="paragraph">The JATS production interface is currently being built. The JATS production interface will also
+support automated PDF output via <a href="https://pagedjs.org/" rel target="blank">pagedjs</a>, and SEO optimised
+HTML for pushing to publish interfaces.</p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-11.png">
+<figcaption class="decoration">JATS Export</figcaption>
+</figure>
+<h3>Publishing</h3>
+<p class="paragraph">Aperture is going live with the FLAX publish front end. Flax is a new product from Coko which
+is connects directly to Kotahi for realtime publishing of articles while being a completely extensible CMS for
+building entire Journal sites. Kotahi has an extensible ingestion API and publishing API. These APIs allow for a
+vast variety of (for example) publishing integrations. NCRC, for example publish to a Google spreadsheet (since
+they are processing existing preprint URLs) as well as registering reviews with DOIs on Crossref. If the target
+system for publishing offers an integration endpoint of any kind, then Kotahi can integrate with it.</p>
+<h3>The Form Builder</h3>
+<p class="paragraph">The Form Builder sounds humble but it is an immensely powerful tool. The Form Builder enables
+the admin/ME to build the submission forms using a web interface. However, the interface also allows for the
+tagging of each field with unique IDs (useful for building JATS/XML at export time), identifying which fields will
+be shown to reviewers when inviting them to review, controlling taxonomy, identifying which columns are displayed
+on the Manuscripts Page, and it can even be used to extend the Control Panel UI. The Form Builder will
+increasingly become an central part of the Kotahi platform. Form Builders are much underestimated.</p>
+<h3>Reports</h3>
+<p class="paragraph">Reports are integrated into Kotahi and are pretty comprehensive. We have opted for dynamic
+rendering to improve the user enjoyment of the Kotahi UI.</p>
+<h3> Workflow Configuration</h3>
+<p class="paragraph">There are immense workflow configuration options. So far, almost all are via config files but
+we have a UI config manager design. While we will use the above workflow, the following are two workflow examples
+for the Novel Coronavirus Research Consortium and CBinstances:</p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-12.png">
+<figcaption class="decoration"><em>NCRC Kotahi Workflow</em></figcaption>
+</figure>
+<p class="paragraph"></p>
+<p class="paragraph"></p>
+<figure><img
+src="/images/uploads/sspKotahi-13.png">
+<figcaption class="decoration">CB Kotahi Workflow</figcaption>
+</figure>
+<p class="paragraph"></p>
+<h3>Summary</h3>
+<p class="paragraph">Kotahi is a modern scholarly publishing platform. It is built with modern technologies with
+modern, efficient workflows in mind. The platform is also very modular, extensible, and configurable. There is
+almost no element of the system that is immutable—all elements can be changed if required. In addition
+Kotahi leverages modern realtime communication protocols and together with the Single Source Publishing design the
+entire system offers publishers enormous futureproofing and workflow optimization opportunities.</p>
+<p class="paragraph">Lastly, <em>all</em> aspects of Kotahi are open source and liberally licensed (MIT). Coko
+exists to support organizations wanting to hire us to extend Kotahi or go it alone. In all development scenarios,
+Coko facilitates the multiple organizations extending Kotahi to ensure the community is building upon each
+other’s work—this helps ensure lowering the burden of development cost and time as well as
+eliminating possible duplication of efforts.</p>
+<p class="paragraph">For more information contact Adam Hyde—<a href="http://adam@coko.foundation" rel
+target="blank">adam@coko.foundation</a></p>
diff --git a/src/articles/SingleSourcePublishing/entry1.md b/src/articles/ssp1.md
similarity index 97%
rename from src/articles/SingleSourcePublishing/entry1.md
rename to src/articles/ssp1.md
index 19ff94f..9d921b3 100644
--- a/src/articles/SingleSourcePublishing/entry1.md
+++ b/src/articles/ssp1.md
@@ -1,8 +1,11 @@
---
-title: "Single Source Publishing"
-subtitle: "Part 1: The Problem"
+subtitle: "Single Source Publishing"
+part: 1
+title: "The Problem"
author: Adam Hyde
+date: "2021"
---
+
<p class="paragraph">Publishing has long suffered from broken workflows that slow down the time to publish and
unnecessarily inflate the cost to publish. Publishing of all kinds suffers from these inefficiencies. Some of the
problems are general, others are very idiosyncratic and particular to perhaps just one publisher.</p>
@@ -24,8 +27,7 @@ author: Adam Hyde
what’ – what files are worked on. The people, the tools, and the working files all change as the
content jumps from content creation to content production.</p>
<figure><img
- src="/images/A1-Img1-and-A4-img4.jpg">
- <figcaption class="decoration"></figcaption>
+ src="/images/uploads/A1-Img1-and-A4-img4.jpg">
</figure>
<p class="paragraph">To understand why this is a problem, we just have to consider this one very simple scenario:
what if there need to be changes to the content after it has entered the production stage?</p>
@@ -69,7 +71,7 @@ author: Adam Hyde
all work on the same files, the same source files – hence the term ‘single source’.</p>
<p class="paragraph"></p>
<figure><img
- src="/images/A1-Img2.jpg">
+ src="/images/uploads/A1-Img2.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">In a single source environment if a change needs to be made while the content is in production
diff --git a/src/articles/SingleSourcePublishing/entry2.md b/src/articles/ssp2.md
similarity index 93%
rename from src/articles/SingleSourcePublishing/entry2.md
rename to src/articles/ssp2.md
index 1210c74..1afaa0b 100644
--- a/src/articles/SingleSourcePublishing/entry2.md
+++ b/src/articles/ssp2.md
@@ -1,8 +1,11 @@
---
-title: "Single Source Publishing"
-subtitle: "Part 2: A Solution"
+subtitle: "Single Source Publishing"
+part: 2
+title: "A Solution"
author: Adam Hyde
+date: "2021"
---
+
<p class="paragraph">Let’s look at a simple tool used for single source publishing on the web –
WordPress – which will help us understand some of the more complex problems Publishers face.</p>
<p class="paragraph">WordPress is a single source publishing system. To produce a post, the author does the
@@ -19,12 +22,12 @@ author: Adam Hyde
and at publish time, that content is transformed into the target output – in this case a blog post shared
on the web.</p>
<figure><img
- src="images/uploads/SSP/A2-Img1.jpg">
+ src="/images/uploads/SSP/A2-Img1.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">Let’s add a little complexity as it is hard to really understand the value of single
source publishing from such a simple example. We will add more people and more outputs.</p>
- <h2>Single Source and Multiple Actors</h2>
+ <h3>Single Source and Multiple Actors</h3>
<p class="paragraph">Before publishing, other actors – copy editors, illustrators etc – might also
work on the content. These folks will also work within WordPress to edit the same post. All these people can
collaborate on the same source for the post. When it is time to publish, the process is still as simple as
@@ -32,7 +35,7 @@ author: Adam Hyde
source has, even in this basic example, saved us a lot of hassle.</p>
<p class="paragraph">Furthermore, all the stakeholders here are using familiar tools. The WordPress editor is a
pretty easy editor to use if you are creating content for the web.</p>
- <h2>Single Source and Multiple Outputs</h2>
+ <h3>Single Source and Multiple Outputs</h3>
<p class="paragraph">Now let’s look at adding multiple outputs. What if we wish to display the same WordPress
blog post to look good on both mobile and desktop devices. In this case, CSS (the set of rules used by designers
that describe how webpages should look) has the ability to identify whether the content is being displayed on a
@@ -40,16 +43,16 @@ author: Adam Hyde
<p class="paragraph">As if by magic, we have effectively solved the problem of displaying the same content for two
different types of outputs – desktop and mobile displays.</p>
<figure><img
- src="images/uploads/SSP/A2-Img2.jpg">
+ src="/images/uploads/SSP/A2-Img2.jpg">
<figcaption class="decoration"></figcaption>
</figure>
- <h2>So what’s the problem?</h2>
+ <h3>So what’s the problem?</h3>
<p class="paragraph">If you were building WordPress for the first time, and you needed to cater for the above
outputs (HTML + CSS for 2 display sizes), what file format would you choose to store your source?</p>
<p class="paragraph">No prizes for choosing HTML. To transform from HTML to HTML & HTML is cheap because there
is (in simple terms) no transformation needed. This is exactly what the smart folks at WordPress have done.</p>
<figure><img
- src="images/uploads/SSP/A2-Img3.jpg">
+ src="/images/uploads/SSP/A2-Img3.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">The content you are editing in WP is stored as HTML. Exactly that same source is directly
@@ -59,7 +62,7 @@ author: Adam Hyde
multiple output types, which is most publishing scenarios, you must choose a source file format that can undergo
significant transformation into all of the output formats you require.</p>
<figure><img
- src="images/uploads/SSP/A2-Img4.jpg">
+ src="/images/uploads/SSP/A2-Img4.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">When designing a publishing system you face two basic questions, in this order:</p>
diff --git a/src/articles/SingleSourcePublishing/entry3.md b/src/articles/ssp3.md
similarity index 93%
rename from src/articles/SingleSourcePublishing/entry3.md
rename to src/articles/ssp3.md
index 85f078b..d3fc329 100644
--- a/src/articles/SingleSourcePublishing/entry3.md
+++ b/src/articles/ssp3.md
@@ -1,18 +1,21 @@
---
-title: "Single Source Publishing"
-subtitle: "Part 3: Is Automation the Answer?"
+subtitle: "Single Source Publishing"
+part: 3
+title: "Is Automation the Answer?"
author: Adam Hyde
+date: "2021"
---
+
<p class="paragraph">Obviously it would be awesome if we could push a button in our imaginary publishing system and
all the outputs would roll out automagically – fully formed, perfect and beautiful.</p>
<p class="paragraph"></p>
<figure><img
- src="images/uploads/SSP/A3-Img1.jpg">
+ src="/images/uploads/SSP/A3-Img1.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">Is such automation possible? Let’s have a closer look at the types of conversion
involved.</p>
- <h2>Structure</h2>
+ <h3>Structure</h3>
<p class="paragraph">There are two types (roughly) of structural conversion – upconversion, and
downconversion.</p>
<h3><strong>Downconversion</strong></h3>
@@ -20,7 +23,7 @@ author: Adam Hyde
means removing information (structure).</p>
<p class="paragraph"></p>
<figure><img
- src="images/uploads/SSP/A3-Img2.jpg">
+ src="/images/uploads/SSP/A3-Img2.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">Removing structure is easy (usually), we just throw stuff away.</p>
@@ -29,19 +32,19 @@ author: Adam Hyde
(structure).</p>
<p class="paragraph"></p>
<figure><img
- src="images/uploads/SSP/A3-Img3.jpg">
+ src="/images/uploads/SSP/A3-Img3.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">Adding structure is doable but not as easy.</p>
<p class="paragraph">A simple diagram to help us understand up and down conversion would be as follows:</p>
<p class="paragraph"></p>
<figure><img
- src="images/uploads/SSP/A3-Img4.jpg">
+ src="/images/uploads/SSP/A3-Img4.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">Down-conversion is generally an easier target for automation. Up-conversion is more likely to
require human intervention.</p>
- <h2>Typesetting</h2>
+ <h3>Typesetting</h3>
<p class="paragraph">Another category of conversion is typesetting. Typesetting means we require a change in the
look and feel of the output (design).</p>
<p class="paragraph">There are two approaches to typesetting – ‘automatic typesetting’ (which
@@ -56,7 +59,7 @@ author: Adam Hyde
manual typesetting.</p>
<p class="paragraph">Again, the more sophisticated the design, the more likely it is to require human intervention
to produce the desired result.</p>
- <h2>Where does that leave us?</h2>
+ <h3>Where does that leave us?</h3>
<p class="paragraph">If we can achieve all of our conversions – structural conversions and typesetting
– automatically, then we are in a winning situation. We can start with a source file and then press a
button and all of our outputs will be generated automagically. This is single source publishing achieved through
diff --git a/src/articles/SingleSourcePublishing/entry4.md b/src/articles/ssp4.md
similarity index 94%
rename from src/articles/SingleSourcePublishing/entry4.md
rename to src/articles/ssp4.md
index 9617437..c8e1922 100644
--- a/src/articles/SingleSourcePublishing/entry4.md
+++ b/src/articles/ssp4.md
@@ -1,8 +1,11 @@
---
-title: "Single Source Publishing"
-subtitle: "Part 4: For the Good of The System"
+subtitle: "Single Source Publishing"
+part: 4
+title: "For the Good of The System"
author: Adam Hyde
+date: "2021"
---
+
<blockquote>
<p class="source-note">“[XML].. is seen as something that must be endured by content authors for the
greater good of the enterprise.”<br><a
@@ -21,7 +24,7 @@ author: Adam Hyde
stakeholders work efficiently while they share the same canonical source.</p>
<p class="paragraph"> </p>
<figure><img
- src="images/uploads/SSP/A4-Img1.jpg">
+ src="/images/uploads/SSP/A4-Img1.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph"> </p>
@@ -30,7 +33,7 @@ author: Adam Hyde
thinking’ has looked like this:</p>
<p class="paragraph"></p>
<figure><img
- src="images/uploads/SSP/A4-Img2.jpg">
+ src="/images/uploads/SSP/A4-Img2.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">This thinking has lead us to where we are today, and today we have broken, disjointed
@@ -38,7 +41,7 @@ author: Adam Hyde
<p class="paragraph">To bring about the efficiencies we are after, we need to think in this direction:</p>
<p class="paragraph"></p>
<figure><img
- src="images/uploads/SSP/A4-Img3.jpg">
+ src="/images/uploads/SSP/A4-Img3.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">What if the file format was the last decision you made when constructing ecosystems of
@@ -49,7 +52,7 @@ author: Adam Hyde
largely why the sector has been driven away from single source publishing systems and is mired in the kind of
broken, slow, expensive processes we discussed in earlier and we illustrated as follows:</p>
<figure><img
- src="images/uploads/SSP/A1-Img1-and-A4-img4.jpg">
+ src="/images/uploads/SSP/A1-Img1-and-A4-img4.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">When we started our discussion of single source publishing systems in this article, we talked a
diff --git a/src/articles/SingleSourcePublishing/entry5.md b/src/articles/ssp5.md
similarity index 97%
rename from src/articles/SingleSourcePublishing/entry5.md
rename to src/articles/ssp5.md
index fd2055c..761f33c 100644
--- a/src/articles/SingleSourcePublishing/entry5.md
+++ b/src/articles/ssp5.md
@@ -1,8 +1,11 @@
---
-title: "Single Source Publishing"
-subtitle: "Part 5: Workflow-First Systems"
+subtitle: "Single Source Publishing"
+part: 5
+title: "Workflow-First Systems"
author: Adam Hyde
+date: "2021"
---
+
<p class="paragraph">In Part 4 of this series about single source publishing systems, we concluded that it is a very
good idea to build systems around ecologies of tools that share the same source file format, rather than deciding
on the source file format before workflow needs are considered. Rather than a ‘file-format-first’
@@ -20,12 +23,12 @@ author: Adam Hyde
then downconvert to specific formats for consumption by tools such as InDesign.</p>
<p class="paragraph"></p>
<figure><img
- src="images/uploads/SSP/A5-Img1.jpg">
+ src="/images/uploads/SSP/A5-Img1.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">But it is possible for a single format to contain enough information to feed into each of these
operations. Let’s look again at each category of operations:</p>
- <h2>Content</h2>
+ <h3>Content</h3>
<p class="paragraph">First, the content folks must be able to edit a relatively easy-to-understand document.
Authors, etc, in most cases prefer a document which contains only what is known as ‘display
semantics’ as they don’t generally work with tools that enforce structure, rather they write from
@@ -36,7 +39,7 @@ author: Adam Hyde
the eye.</p>
<p class="paragraph">So any format we choose must be able to support a suite of tools that these kinds of authors
can use. Generally speaking these tools are known as ‘word processors’.</p>
- <h2>Design</h2>
+ <h3>Design</h3>
<p class="paragraph">Designers must be able to take the same content and apply design to the content within the
constraints of the output format. For example, designers must make the document look good in paginated PDF for
printing (eg books), or EPUB, or the web etc.</p>
@@ -47,7 +50,7 @@ author: Adam Hyde
can point and click to target elements and change their look and feel. However, in recent years (well, for a while
now) there have been ‘rules based’ design tools. One such rule-based approach is CSS – the
set of rules web designers use to determine the display format of webpages.</p>
- <h2>Format</h2>
+ <h3>Format</h3>
<p class="paragraph">Format wranglers want to be able to output file formats required for archiving, transmission,
and storage. JATS (Journal Article Tagging Suite) is one such format, it is a variant of XML. Books have BITS
(Book Interchange Tag Suite) which is also a XML variant.</p>
@@ -106,7 +109,7 @@ author: Adam Hyde
We need the source file format to hold just enough information so that we can design elements with our design
tools, but any further logic can be contained within separate rules and not contained within the source file. Once
again, that allows us to keep the requirements of the source file to a minimum.</p>
- <h2>Ecosystem Features</h2>
+ <h3>Ecosystem Features</h3>
<p class="paragraph">So, we have two sets of qualities when choosing our ecosystem — one set of features for
the source file format, and one for the types of tools we choose. For the file format we need this:</p>
<ol>
@@ -124,7 +127,7 @@ author: Adam Hyde
</li>
</ol>
<figure><img
- src="images/uploads/SSP/A5-Img2.jpg">
+ src="/images/uploads/SSP/A5-Img2.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">Where does that leave us? As it happens, it leaves us with the ecology of tools that surround
diff --git a/src/articles/SingleSourcePublishing/entry6.md b/src/articles/ssp6.md
similarity index 96%
rename from src/articles/SingleSourcePublishing/entry6.md
rename to src/articles/ssp6.md
index 3c3cbf4..7606948 100644
--- a/src/articles/SingleSourcePublishing/entry6.md
+++ b/src/articles/ssp6.md
@@ -1,8 +1,11 @@
---
-title: "Single Source Publishing"
-subtitle: "Part 6: Concurrency"
+subtitle: "Single Source Publishing"
+part: 6
+title: "Concurrency"
author: Adam Hyde
+date: "2021"
---
+
<p class="paragraph">In publishing there are two types of concurrency we care about:</p>
<ol>
<li>
@@ -21,20 +24,20 @@ author: Adam Hyde
chapter or even per paragraph (sometimes referred to as batching). Just by doing this we can have more than one
person working on the book at the same time (each tackling a different chapter for example).</p>
<figure><img
- src="images/uploads/SSP/A6-Img1.jpg">
+ src="/images/uploads/SSP/A6-Img1.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">This is workflow concurrency.</p>
<p class="paragraph">Now, if we want two people to edit the same chapter at the same time this is realtime editing.
</p>
<figure><img
- src="images/A6-Img2.jpg">
+ src="/images/uploads/A6-Img2.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">Of course we can blend these two models:</p>
<p class="paragraph"></p>
<figure><img
- src="images/A6-Img3.jpg">
+ src="/images/uploads/A6-Img3.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">Now, realtime editing, as a type of concurrency, is a choice you have depending on the type of
@@ -61,7 +64,7 @@ author: Adam Hyde
crucial question – “what is my ideal workflow”. Other decisions follow from there.</p>
<p class="paragraph">Given all this, it is a good idea to first zoom out and question what value concurrency, of any
kind, can offer a publishing workflow. We can then answer whether we actually want concurrency.</p>
- <h2>Concurrency vs Sequential Workflows</h2>
+ <h3>Concurrency vs Sequential Workflows</h3>
<p class="paragraph">Publishing workflows these days are mostly sequential. A sequential workflow requires
operations to be executed one after the other. Many publishers today, for example, are emailing (or uploading and
downloading) bunches of documents for each other, usually in the MS Word format, to work on. An author emails
@@ -87,28 +90,28 @@ author: Adam Hyde
state of the work at any moment</p>
<p class="paragraph"></p>
<figure><img
- src="images/A6-Img4.jpg">
+ src="/images/uploads/A6-Img4.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">2.<strong> reducing handling time</strong> – reducing the to and fro of
passing documents back and forth</p>
<p class="paragraph"></p>
<figure><img
- src="images/A6-Img5.jpg">
+ src="/images/uploads/A6-Img5.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">3. <strong>parallel processes</strong> – various team members can do what they
need to do in parallel with each other</p>
<p class="paragraph"></p>
<figure><img
- src="images/A6-Img6.jpg">
+ src="/images/uploads/A6-Img6.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">4. <strong>realtime problem solving</strong> – issues can be resolved in
realtime.</p>
<p class="paragraph"></p>
<figure><img
- src="images/A6-Img7.jpg">
+ src="/images/uploads/A6-Img7.jpg">
<figcaption class="decoration"></figcaption>
</figure>
<p class="paragraph">These 4 opportunities provided by concurrency can have, even if moderately implemented, a huge
@@ -171,7 +174,7 @@ author: Adam Hyde
<p class="paragraph">Developmental editors and authors working on the same text at the same time</p>
</li>
</ul>
- <h2>SSP and Concurrency</h2>
+ <h3>SSP and Concurrency</h3>
<h3>So, what about SSP and concurrency?</h3>
<p class="paragraph">Remember these two features of concurrency listed above:</p>
<ol>
diff --git a/src/layouts/article-single.njk b/src/layouts/article-single.njk
index 0d26a2d..077916d 100644
--- a/src/layouts/article-single.njk
+++ b/src/layouts/article-single.njk
@@ -44,17 +44,12 @@
{% if previousPost %}
<div class="grid-item previous">
<a class="previous" href="{{ previousPost.url }}">
- <figure><img src="{{ previousPost.data.icon }}" alt="{{ previousPost.data.title }}"></figure>
- </a>
- <a class="previous" href="{{ previousPost.url }}"><h3>{{ previousPost.data.title }}</h3></a>
+ <a class="previous" href="{{ previousPost.url }}"><h3>Previously: {{ previousPost.data.title }}</h3></a>
</div>
{% endif %}
{% if nextPost %}
<div class="grid-item next">
- <a class="next" href="{{ nextPost.url }}">
- <figure><img src="{{ nextPost.data.icon }}" alt="{{ nextPost.data.title }}"></figure>
- </a>
- <a class="next" href="{{ nextPost.url }}"><h3>{{ nextPost.data.title }}</h3></a>
+ <a class="next" href="{{ nextPost.url }}"><h3>Next: {{ nextPost.data.title }}</h3></a>
</div>
{% endif %}
{# <a class="next" href="https://www.pagedjs.org/search/">Looking for something?</a>
diff --git a/src/layouts/articles-index.njk b/src/layouts/articles-index.njk
index b22e9b5..c907960 100644
--- a/src/layouts/articles-index.njk
+++ b/src/layouts/articles-index.njk
@@ -1,21 +1,26 @@
{% extends "base.njk" %}
-
{% block content %}
-
+
{{content | safe}}
-
+
{% for item in collections.articles -%}
- <div class="posts grid-item {{item.data.class}}">
- <p class="meta">
- <time datetime="{{item.date}}">{{item.data.date}}</time>
- <span>#{{item.data.tags}}</span>
- </p>
- <figure><a href="{{item.url}}">
- <img src="{{item.data.icon}}" alt="{{item.data.title}}"></a>
- </figure>
- <h3 id="{{item.data.title | slug}}"><a href="{{item.url}}">{{item.data.title}}</a></h3>
- {{ item.data.intro | safe }}
- </div>
+ <div class="posts grid-item {{item.data.class}}">
+ <p class="meta">
+ <time datetime="{{item.date}}">{{item.data.date}}</time>
+ {% if item.data.subtitle %}
+ <span>#{{item.data.subtitle}}</span>
+ {% endif %}
+
+ </p>
+ {# <figure><a href="{{item.url}}"> #}
+ {# <img src="{{item.data.icon}}" alt="{{item.data.title}}"></a> #}
+ {# </figure> #}
+
+ <h3 id="{{item.data.title | slug}}"><a href="{{item.url}}">
+ {% if item.data.part %} <span>{{item.data.part}}</span> {% endif %} {{item.data.title}}</a></h3>
+
+ {{ item.data.intro | safe }}
+ </div>
{%- endfor %}
-{% endblock %}
\ No newline at end of file
+{% endblock %}
diff --git a/static/css/theme-coko/main.css b/static/css/theme-coko/main.css
index 9df3be5..0913f93 100644
--- a/static/css/theme-coko/main.css
+++ b/static/css/theme-coko/main.css
@@ -49,6 +49,14 @@
.articles a {
color: var(--color-primary);
}
+.article-single h1,
+.article-single h2,
+.article-single h3,
+.article-single h4,
+.article-single p.tags,
+.article-single a {
+ color: var(--color-secondary);
+}
.about h1,
.about h2,
.about h3,
@@ -113,6 +121,7 @@ aside {
.community aside,
.about aside,
+.article-single aside,
.team aside {
background: linear-gradient(6deg, rgba(255, 255, 255, 1) 58%, #bba3c5 100%);
filter: drop-shadow(700px -15px 15px var(--color-trois));
@@ -252,14 +261,20 @@ article h3 {
}
article p,
article ul,
+article ol,
article blockquote,
article h3,
+/* article figure, */
article h4 {
grid-column: 2/4;
padding: 0.5em 10px;
margin-top: 0px;
border-left: 1px solid var(--color-gris);
}
+article ol p,
+article ul p {
+ border-left: 0;
+}
article figure,
article video {
grid-column: 1 / end;
@@ -608,3 +623,12 @@ footer section.infos a:hover {
grid-column-end: span 4;
}
}
+
+.article-single main .post-content * {
+ border-left: 0;
+ grid-column: 2/5;
+}
+.article-single figcaption {
+ text-align: center;
+ font-style: italic;
+}
diff --git a/static/images/uploads/SSP/A1-Img1-and-A4-img4.jpg b/static/images/uploads/A1-Img1-and-A4-img4.jpg
similarity index 100%
rename from static/images/uploads/SSP/A1-Img1-and-A4-img4.jpg
rename to static/images/uploads/A1-Img1-and-A4-img4.jpg
diff --git a/static/images/uploads/SSP/A1-Img2.jpg b/static/images/uploads/A1-Img2.jpg
similarity index 100%
rename from static/images/uploads/SSP/A1-Img2.jpg
rename to static/images/uploads/A1-Img2.jpg
diff --git a/static/images/uploads/SSP/A2-Img1.jpg b/static/images/uploads/A2-Img1.jpg
similarity index 100%
rename from static/images/uploads/SSP/A2-Img1.jpg
rename to static/images/uploads/A2-Img1.jpg
diff --git a/static/images/uploads/SSP/A2-Img2.jpg b/static/images/uploads/A2-Img2.jpg
similarity index 100%
rename from static/images/uploads/SSP/A2-Img2.jpg
rename to static/images/uploads/A2-Img2.jpg
diff --git a/static/images/uploads/SSP/A2-Img3.jpg b/static/images/uploads/A2-Img3.jpg
similarity index 100%
rename from static/images/uploads/SSP/A2-Img3.jpg
rename to static/images/uploads/A2-Img3.jpg
diff --git a/static/images/uploads/SSP/A2-Img4.jpg b/static/images/uploads/A2-Img4.jpg
similarity index 100%
rename from static/images/uploads/SSP/A2-Img4.jpg
rename to static/images/uploads/A2-Img4.jpg
diff --git a/static/images/uploads/SSP/A3-Img1.jpg b/static/images/uploads/A3-Img1.jpg
similarity index 100%
rename from static/images/uploads/SSP/A3-Img1.jpg
rename to static/images/uploads/A3-Img1.jpg
diff --git a/static/images/uploads/SSP/A3-Img2.jpg b/static/images/uploads/A3-Img2.jpg
similarity index 100%
rename from static/images/uploads/SSP/A3-Img2.jpg
rename to static/images/uploads/A3-Img2.jpg
diff --git a/static/images/uploads/SSP/A3-Img3.jpg b/static/images/uploads/A3-Img3.jpg
similarity index 100%
rename from static/images/uploads/SSP/A3-Img3.jpg
rename to static/images/uploads/A3-Img3.jpg
diff --git a/static/images/uploads/SSP/A3-Img4.jpg b/static/images/uploads/A3-Img4.jpg
similarity index 100%
rename from static/images/uploads/SSP/A3-Img4.jpg
rename to static/images/uploads/A3-Img4.jpg
diff --git a/static/images/uploads/SSP/A4-Img1.jpg b/static/images/uploads/A4-Img1.jpg
similarity index 100%
rename from static/images/uploads/SSP/A4-Img1.jpg
rename to static/images/uploads/A4-Img1.jpg
diff --git a/static/images/uploads/SSP/A4-Img2.jpg b/static/images/uploads/A4-Img2.jpg
similarity index 100%
rename from static/images/uploads/SSP/A4-Img2.jpg
rename to static/images/uploads/A4-Img2.jpg
diff --git a/static/images/uploads/SSP/A4-Img3.jpg b/static/images/uploads/A4-Img3.jpg
similarity index 100%
rename from static/images/uploads/SSP/A4-Img3.jpg
rename to static/images/uploads/A4-Img3.jpg
diff --git a/static/images/uploads/SSP/A5-Img1.jpg b/static/images/uploads/A5-Img1.jpg
similarity index 100%
rename from static/images/uploads/SSP/A5-Img1.jpg
rename to static/images/uploads/A5-Img1.jpg
diff --git a/static/images/uploads/SSP/A5-Img2.jpg b/static/images/uploads/A5-Img2.jpg
similarity index 100%
rename from static/images/uploads/SSP/A5-Img2.jpg
rename to static/images/uploads/A5-Img2.jpg
diff --git a/static/images/uploads/SSP/A6-Img1.jpg b/static/images/uploads/A6-Img1.jpg
similarity index 100%
rename from static/images/uploads/SSP/A6-Img1.jpg
rename to static/images/uploads/A6-Img1.jpg
diff --git a/static/images/uploads/SSP/A6-Img2.jpg b/static/images/uploads/A6-Img2.jpg
similarity index 100%
rename from static/images/uploads/SSP/A6-Img2.jpg
rename to static/images/uploads/A6-Img2.jpg
diff --git a/static/images/uploads/SSP/A6-Img3.jpg b/static/images/uploads/A6-Img3.jpg
similarity index 100%
rename from static/images/uploads/SSP/A6-Img3.jpg
rename to static/images/uploads/A6-Img3.jpg
diff --git a/static/images/uploads/SSP/A6-Img4.jpg b/static/images/uploads/A6-Img4.jpg
similarity index 100%
rename from static/images/uploads/SSP/A6-Img4.jpg
rename to static/images/uploads/A6-Img4.jpg
diff --git a/static/images/uploads/SSP/A6-Img5.jpg b/static/images/uploads/A6-Img5.jpg
similarity index 100%
rename from static/images/uploads/SSP/A6-Img5.jpg
rename to static/images/uploads/A6-Img5.jpg
diff --git a/static/images/uploads/SSP/A6-Img6.jpg b/static/images/uploads/A6-Img6.jpg
similarity index 100%
rename from static/images/uploads/SSP/A6-Img6.jpg
rename to static/images/uploads/A6-Img6.jpg
diff --git a/static/images/uploads/SSP/A6-Img7.jpg b/static/images/uploads/A6-Img7.jpg
similarity index 100%
rename from static/images/uploads/SSP/A6-Img7.jpg
rename to static/images/uploads/A6-Img7.jpg
diff --git a/static/images/uploads/SSP-Kotahi/img01.png b/static/images/uploads/sspKotahi-01.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img01.png
rename to static/images/uploads/sspKotahi-01.png
diff --git a/static/images/uploads/SSP-Kotahi/img02.png b/static/images/uploads/sspKotahi-02.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img02.png
rename to static/images/uploads/sspKotahi-02.png
diff --git a/static/images/uploads/SSP-Kotahi/img03.png b/static/images/uploads/sspKotahi-03.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img03.png
rename to static/images/uploads/sspKotahi-03.png
diff --git a/static/images/uploads/SSP-Kotahi/img04.png b/static/images/uploads/sspKotahi-04.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img04.png
rename to static/images/uploads/sspKotahi-04.png
diff --git a/static/images/uploads/SSP-Kotahi/img05.png b/static/images/uploads/sspKotahi-05.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img05.png
rename to static/images/uploads/sspKotahi-05.png
diff --git a/static/images/uploads/SSP-Kotahi/img06.png b/static/images/uploads/sspKotahi-06.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img06.png
rename to static/images/uploads/sspKotahi-06.png
diff --git a/static/images/uploads/SSP-Kotahi/img07.png b/static/images/uploads/sspKotahi-07.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img07.png
rename to static/images/uploads/sspKotahi-07.png
diff --git a/static/images/uploads/SSP-Kotahi/img08.png b/static/images/uploads/sspKotahi-08.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img08.png
rename to static/images/uploads/sspKotahi-08.png
diff --git a/static/images/uploads/SSP-Kotahi/img09.png b/static/images/uploads/sspKotahi-09.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img09.png
rename to static/images/uploads/sspKotahi-09.png
diff --git a/static/images/uploads/SSP-Kotahi/img10.png b/static/images/uploads/sspKotahi-10.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img10.png
rename to static/images/uploads/sspKotahi-10.png
diff --git a/static/images/uploads/SSP-Kotahi/img11.png b/static/images/uploads/sspKotahi-11.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img11.png
rename to static/images/uploads/sspKotahi-11.png
diff --git a/static/images/uploads/SSP-Kotahi/img12.png b/static/images/uploads/sspKotahi-12.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img12.png
rename to static/images/uploads/sspKotahi-12.png
diff --git a/static/images/uploads/SSP-Kotahi/img13.png b/static/images/uploads/sspKotahi-13.png
similarity index 100%
rename from static/images/uploads/SSP-Kotahi/img13.png
rename to static/images/uploads/sspKotahi-13.png
--
GitLab