#2637 updated docs for managing a typeset file

openlibhums · Dec 9, 2021 · 42434b3 · 42434b3
1 parent e16e9ea
commit 42434b3
Show file tree

Hide file tree

Showing 8 changed files with 72 additions and 6 deletions.
diff --git a/docs/source/editor/typesetting.rst b/docs/source/editor/typesetting.rst
@@ -178,4 +178,55 @@ Authors are able to upload supplementary files to Janeway as part of their submi
 .. tip:: You should create the supplementary file object in advance of sending the article for typesetting where possible and notify the typesetter (if you use external typesetters). They will be able to see the file record and the DOI that has been assigned to it.
 
 .. figure:: ../nstatic/typesetting/supp_files.gif
-   :class: with-border
+   :class: with-border
+
+Managing Typeset Files/Galleys
+------------------------------
+Once a typesetter or production manager has uploaded typeset files into Janeway they become manageable within the system. To manage a typeset file/galley press the Edit icon on the relevant table row.
+
+.. figure:: ../nstatic/typesetting/editor/typeset_files.png
+   :class: with-border
+An XML typeset file with missing figure files.
+
+
+File Detail
+^^^^^^^^^^^
+.. figure:: ../nstatic/typesetting/editor/file_details.png
+   :class: with-border
+
+The file label is displayed on the main article page and is displayed in the format "Download Label". If you set the label to XML it will read "Download XML".
+
+.. tip:: When uploading a PDF, XML or HTML file Janeway will set the label for you automatically if you leave it blank.
+
+You can also mark a typeset file as not for public consumption by unchecking the "Public" field in this section.
+
+Replacing the Typeset File
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. figure:: ../nstatic/typesetting/editor/edit_typeset_file.png
+   :class: with-border
+
+If you need to upload a new version of the typeset file you can do so from within the Edit Typeset File screen. Browse for the new file and click Upload. The old version of the file is retained. Alternatively you could mark this file as not public and upload a new typeset file if you wanted to keep two separate file records.
+
+Image/Figure Files
+^^^^^^^^^^^^^^^^^^
+HTML and XML files that are uploaded will be scanned by Janeway to detect graphic, figure or img tags. If tags are found that have no corresponding Image file will report on the main typesetting page as having missing images. (see figure at the top of this section for an example). You can load up images against a typeset file by editing it and scrolling to the Image File section.
+
+.. figure:: ../nstatic/typesetting/editor/image_files.png
+   :class: with-border
+
+For each missing image file Janeway will present you with a block where you can either upload a new image file or select an existing one from the images already linked to the article.
+
+.. tip:: For typeset files with a large number of images you can also create a zip archive and place an image (with a name matching those in the file) and upload it using the Zip Uploader. Janeway will unzip the archive and assign the images based on their name.
+
+CSS File
+^^^^^^^^
+If a given article requires special styling you can upload a CSS file alongside it and Janeway will output it on the article page.
+
+.. warning:: The CSS uploaded here should only target elements inside the <article> block otherwise it could break general styling of the site.
+
+XSL File
+^^^^^^^^
+Janeway's XSL Transformation process uses a version controlled XSL (Extensible Stylesheet Language) file. When you upload a JATS XML file to Janeway it marks the file as using the current XSL file. This means that as we make changes to the XSL file it will only affect future files uploaded and not any back content.
+
+.. warning:: Changing a XML file's XSL may cause it to render differently. It is only recommended that you do this before sending it for Proofreading.
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,21 +6,25 @@
 Janeway Documentation
 =====================
 
+Janeway is a digital platform for publishing scholarly articles online, from submission and review to editing, production and final publication. This guide, whilst not exhaustive, provides various guides for setting up an install of Janeway, configuring journals and running articles through the workflow
+
 This guide has been written to avoid using language like "easy", "just" or "simply". A massive shout out to Emma Barnes and her awesome site https://www.justsimply.dev/
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 4
    :caption: Contents
 
-   installation
    faq
    workflow
    manager
    imports
    styling
    published
+   installation
    changelog
 
+Janeway is developed and maintained and supported by a team at Birkbeck, University of London and the Open Library of Humanities.
+
 ..
    # Indices and tables
    :ref:`genindex`

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -3,7 +3,7 @@ Installation Guide
 There are a number of ways to get Janeway up and running. For development we recommend you use Docker with Postgres as the DB_VENDOR. A Lando configuration is also included.
 
 Running Janeway with Docker and docker-compose
----------
+----------------------------------------------
 1. Install ``docker``, ``docker-compose`` and ``GNU Make``.
 2. From the /path/to/janeway directory run ``make install``.
 3. A docker environment will be provisioned, and shortly after the janeway isntall script will run. Follow the instructions on screen to complete the installation.

diff --git a/docs/source/nstatic/typesetting/editor/edit_typeset_file.png b/docs/source/nstatic/typesetting/editor/edit_typeset_file.png
diff --git a/docs/source/nstatic/typesetting/editor/file_details.png b/docs/source/nstatic/typesetting/editor/file_details.png
diff --git a/docs/source/nstatic/typesetting/editor/image_files.png b/docs/source/nstatic/typesetting/editor/image_files.png
diff --git a/docs/source/nstatic/typesetting/editor/typeset_files.png b/docs/source/nstatic/typesetting/editor/typeset_files.png
diff --git a/docs/source/typesetter.rst b/docs/source/typesetter.rst
@@ -100,20 +100,31 @@ When uploading a new Galley (now referred to as 'Typeset Files'), there is now a
 
    Screenshot of the new file upload box
 
-When uploading an XML or HTML file with image files, Janeway will detect them and prompt the typesetter to upload them.
+Image Files
+^^^^^^^^^^^
+
+When a typeset file in the XML or HTML format is uploaded that has image links Janeway will detect them and prompt the typesetter to upload them. Image filenames should match those within the XML or HTML.
 
 .. figure:: nstatic/typesetting/images_missing.png
 
-At this point, just hit the edit button and upload each image on the box matching the filename from the XML/HTML file:
+At this point, press the edit button and upload each image on the box matching the filename from the XML/HTML file:
 
 .. figure:: nstatic/typesetting/typesetter_images.png
 
+If an XML or HTML file has a large number of images it is often faster to use the zip uploader. Create a .zip archive file and within it place each of the image files. The image filename must match the link in the typeset file otherwise it will not import them.
+
+Source Files
+^^^^^^^^^^^^
+
 If any intermiadate files have been used for the production of the Files (such as Adobe In Design files), they can be uploaded under the 'Source Files' section
 
 .. figure:: nstatic/typesetting/source_files.png
 
    Screenshot of the source files form
 
+Finishing Up
+^^^^^^^^^^^^
+
 Before you can complete the task, Janeway will warn you of any potential problems it detects with your files, such as potential missing images on the XML/HTML files or Typeset Files that have not yet been corrected.
 
 .. figure:: nstatic/typesetting/images_missing_warning.png