Styling the Word Files for Publication - ESTS-Variants/varianTeX GitHub Wiki

The web publication platform OpenEdition uses (Lodel) does not just require that we upload files in docx format (when not using TEI-XML), the documents also need to be styled in a very particular way, using specific (Lodel-created) Word ‘styles’. This means that we need to 1) download the styles, and attach them to our documents; and 2) format the documents so that all the information is in the right order, the relevant styles are applied to each section, etc.

Lodel provides documentation for this, that will form the basis of our walk through these steps below:

The description below will advance through the steps found across those pages that are relevant for our workflow, and adding some missing information here and there.

Our setup is one where the editor works on a Mac, and has Word 2016 installed. Specifically, the version of Word installed is Version 16.91 , installed through a (work-provided) Microsoft 365 subscription. So that is the setup used in the description below. If you have a different setup, you should consult the relevant documentation linked above.

Step 1: Installing the templates

1.1 Download the templates

First, download the latest release of the templates, which at the time of writing can be downladed here: Release Modèles 5.5 · OpenEdition. Unzip, and remember where you put the folder.

1.2 Open the target folder

In Finder, click on the Go tab to show a drop-down menu of locations. If Library is not one of them, press the Alt key. Click on Library. From there, follow the path: GroupContainers/UBF8T346G9.Office/User Content/Templates.

1.3 Copy the relevant template in the target folder

From the downloaded folder, copy the oe_template_en.dotm (see 1.1) into the target folder (see 1.2).

1.4 Attach the template

  1. Open the file you want to start editing (e.g., the docx. file you generated using pandoc in the previous step in the pipeline) [LINK]
  2. Click on the Tools tab, and choose Templates and Add-ins...
  3. Click on Attach…, and select the relevant template (see 1.3)
  4. Make sure you tick the Automatically update document styles checkmark.

In your ‘ribbon’ (the area at the top of your Word window with tabs like Home, Insert, Draw, etc.), you should now see a new ‘tab’ to your ‘ribbon’ in Word, called LodelStyles. This means that 1.4.3 worked (regardless of whether you completed 1.4.4).

It can be handy to now visualise the Styles Pane, so you have an overview of the styles you’re using in the document. To do that, go to Home in your ribbon, then click on the Styles Pane icon. Then, at the bottom, in the List option, pick Styles in use. This should also list a Clear Formatting option among your styles that may come in handy at some point.

Also useful at this point is to visualise the formatting marks in Word, so you know there’s no hidden marks you aren’t aware of, such as section breaks, page breaks, line breaks etc. It will also visualise the difference between regular spaces (as: •) and non-breakable spaces (as: °), which you may need in step 2.2 below. On my Mac the shortcut to visualise the formatting in Word was Cmd+8. If that does not work for you, consult the internet.

[!WARNING] Step 1.4.4 is currently not mentioned in the Lodel documentation.

Not having ticked this checkmark, some styles I tried to apply (e.g. Title) were not changing the look of the text fields, while others (e.g. Author Description) threw an error and asked me to debug. After ticking the box, everything worked fine.

Step 2: Add and style the metadata

2.1 Title [REQUIRED]

The first line in your document should be the title of the contribution. If you followed our instructions for converting your .tex files to .docx with pandoc [LINK], this should already be the case.

Select the title. Then, in the ribbon, go to LodelStyles > Dublin Core Metadata and select Title. You will probably immediately see the difference in formatting. The style will now also show up in your Styles pane if you revealed that in the previous step. This will be the case for all styles applied below.

2.2 Authors and their Author Descriptions [REQUIRED]

In our journal, all authors always have author descriptions (short bios). This means that we need to split them up, rather than list all authors in a single metadata line.

For each author:

  1. Start a new line, with just the author name, following the Firstname Lastname format.
  2. Select the author’s name, and in the ribbon, go to Lodelstyles > Dublin Core Metadata and select Author.
  3. Start a new line, where you complete the author’s short bio.
  4. Select the short bio, and in the ribbon go to Lodelstyles > Dublin Core Metadata and select Author Description.
  5. Repeat steps 1-4 until there are no authors left.

[!IMPORTANT] If your author has a first or last name that consists of multiple space-separated parts, make sure that those parts are not separated by regular spaces (•), but as unbreakable spaces (°).

So, for example: a person called Firstname La St. Name where Firstname is their first name, and La St. Name is their last name should (with formatting marks turned on) be visualised as Firstname•La°St.°Name).

[!TIP] Both on a Mac and Windows computer, the keyboard shortcut to add and non-breakable space (visualised as a light °) would be Alt+Shift+SPACE.

[!IMPORTANT] The non-breakable space is different from the so-called ‘degree symbol’, which is produced by typing Alt+Shift+8 (on my Mac).

Both symbols look pretty much the same, but you can distinguish a non-breakable space from the degree symbol because the former will be visualised in a lighter colour (same as the paragraph symbol, space symbol etc. with formatting symbols turned on), while the degree symbol will be rendered in the default font colour (usually black). A non-breakable space sign will also disappear when you stop visualising formatting marks, while the degree symbol will remain.

Generating author descriptions from the .tex

In our journal, we have a separate back/authors.tex file where we store author descriptions. In the print/PDF version of our journal, those are printed at the back of the volume.

If you want to use that file to generate your author descriptions from this file for ease of use, you can convert it in Word, like we did with the other .tex files [LINK]. To do so:

  1. Move the authors.tex file to the root of the journal directory.

  2. Remove everything before the first author bio, and replace it with:

\documentclass{article}
\title{}
\author{}
\begin{document}
\maketitle

  1. At the end of the file, add `\end{document}

  2. In the terminal (cd’d to the journal folder), enter pandoc authors.tex -o authors.docx

[!TIP] Our author descriptions are formatted in such a way that they start with the name, surrounded by a \paragraph{} command.

You may want to remove this before using pandoc, or use the Clear Formatting option on the name in the Styles Pane afterwards.

2.3 Language [REQUIRED]

On a next line, use the ISO 639-1 standard abbreviation for the (main) language in which the contribution is written. For example: en for essays written in English (the only main language permitted in Variants).

Select the language abbreviation, and in the ribbon, go to Lodelstyles > Dublin Core Metadata and select Language.

2.4 Abstract [OPTIONAL]

Contributions that have an abstract (e.g. all essays and work in progress contributions), that abstract will be the first paragraph (or couple of paragraphs, but this is bad practice, and should be avoided — please ask authors for concise 200w max single paragraph abstracts) of the running text. Some contributions (e.g. preface, introduction, review) will not have an abstract.

When you do have an abstract:

  1. Make sure it immediately follows the Language line (2.3), on the first next line
  2. Delete any space markers pandoc may have added at the start (2em) or end (1em) of the document
  3. Select the abstract
  4. In the Styles Pane, select All styles for the List option.
  5. Find the Abstract style, and apply it

[!NOTE] The Abstract style is not found in the usual place (anywhere under the LodelStyles ribbon tab).

[!IMPORTANT] If your abstract starts with the word Abstract: (or something similar), this should also be removed.

2.5 Keywords [OPTIONAL]

Our goal is to develop a controlled vocabulary for keywords, to improve their functionality of linking content on our journal website. In the meantime, authors may have provided keywords of their own, or you may find relevant keywords for the contribution (e.g. in our index).

If you have keywords, they come after the abstract. For your keywords, make sure your

  • list them as comma separated values;
  • remove the word Keywords: or similar if it is part of the line;
  • do not start the list with a capital letter, and do not end the list with a full stop;
  • do not use quotation marks, or word separators (such as dashes); and
  • do not capitalise common nouns.

Then:

  1. Select the keywords
  2. In the Styles Pane, select All styles for the List option (if it isn’t there yet from styling the abstract).
  3. Find the Keywords style, and apply it

[!NOTE] Like with Abstract, the Keywords style is not found in the usual place (anywhere under the LodelStyles ribbon tab).

2.6 Page Numbers [REQUIRED]

Next, add another line, where you add the page numbers for the contribution. These are the page numbers as they appear in the finalised PDF version of the journal volume. We number preface materials (preface, introduction) with small roman numerals, and start arabic numerals with the essays. Do not use abbreviations for numbering (e.g. p. or pp.) — those will be provided by the platform.

Select the page numbers, go to LodelStyles > Dublin Core Metadata and choose Page Numbering.

2.7 Publication dates

Directly after the page numbers come the publication dates for the print and digital publications. Use the first of the month in which the digital publication will be published. Since we currently have no physical print copy of the book, we count the PDF as the print copy, and use the same date for both.

For example:

01 December 2024
01 December 2024

The styles for these publication dates can be found by going to LodelStyles > Dublin Core Metadata. First, use date of publication (print), then (on the next line) use date of online publication.

2.8 Acknowledgements, dedications, errata [OPTIONAL]

If a text has one of these, it should be added before the text, as part of the metadata, rather than at the end. Their styles can be found under LodelStyles in the ribbon, after clicking on paratext.

Step 3: Style the text

3.1 Headings

You can find the styles for different level headings under LodelStyles in the ribbon, after clicking on outline. Make sure that headings:

  • Are in lower case except for the initial (and other spelling-required capital letters)
  • Do not end in a full stop

3.2 Normal text

You can find the styles for regular paragraphs under LodelStyles in the ribbon, after clicking on text, and selecting Normal.

If a paragraph should not be intended at the beginning (e.g. because it is still part of the previous paragraph which was only broken up because of a block quote, table, etc.), use the Not Indented Paragraph style (right under Normal) instead.

Normal formatting (e.g. italics, bold, etc.) can be used in the Normal and Not Indented Paragraph styles.

3.3 Quotes

To present poems, quotes, lists, etc., replace paragraph breaks () with manual line breaks ↲ Shift+Enter. This avoids too much space between lines. This space is defined in the site layout.

The use of paragraph breaks in quotations should be limited to a specific structuring function of the passage, as it may be useful in a poetic text in stanzas, in a quotation followed by its translation, etc.

3.4 Illustrations and Tables

Illustrations and tables themselves are styled as Normal text. Their captions etc. are styled as follows:

  1. First comes the title of the illustration uses the Illustration Title style) and is placed above the illustration or table;
  2. then comes the illustration or table (styled as Normal);
  3. followed by the caption (styled with Illustration caption) below the illustration;
  4. and/or the credits (style Credits Illustration), also below the illustration.

All these styles can be found under LodelStyles in the ribbon, after clicking on `text.

Step 4: Style the bibliography [USUALLY REQUIRED]

In our pipeline, the bibliography should already be formatted automatically right after the text of the contribution, without a ‘Bibliography’ heading. This is as it should be.

Format the bibliography with the Bibliography style, which can be found under LodelStyles > Paratext.

[!IMPORTANT] If repeating authors have been replaced by –––, remove this formatting and repeat the author’s name instead.

That way the platform can process the references and provide links to DOIs etc. where relevant.

[!NOTE] You may want to check the references after the upload, to make sure (for example) that there are no double DOIs in references (e.g. when you provided a DOI, and the platform recognised the reference and added one too).

Bibliographies are more or less required, since essays should place their research in the relevant literature in the field. This is not necessarily the case, however, with the preface, introduction, reviews, and potentially vignette contributions.

Step 5: Style the appendix [OPTIONAL]

Appendices come after the bibliography. You can style them with the Appendix style, found under LodelStyles > Paratext.

Like with the bibliography, do not start this section with an Appendix heading. This will be provided automatically by the platform.

If you attach multiple appendices, however, you can distinguish them by using title headings (e.g., Appendix A, Appendix B, etc.).