A Light on the Hill

Preparing the electronic order of service

Since the advent of COVID-19 and our return to worship in person, the electronic order of service has been encouraged rather than a paper copy. Four versions are produced, web page, PDF, ePUB and mobi. This provides a good selection for all devices and allows for large print. This document sets out how to produce each of these versions from a source order of service in DOCX format.

What you will need

  • A word processor – Microsoft Word or LibreOffice – used to convert from DOCX to PDF
  • Pandoc – used to convert from DOCX to Markdown and then to HTML, ePub
  • An editor that gives a markdown preview. Atom or Visual Studio Code work ok.
  • Kindlegen or Calibre – used to convert from ePub to Mobi
  • ImageMagick – used to programatically process images.

Preparation of the DOCX file

You may need to adjust the imagesif you encounter problems later on. In most cases can be safely skipped

  • Crop all images to the actual size used. If the images haven’t been cropped you’ll get strange results at the Markdown stage
  • Replace any inappropriately formatted images. If you get giant PDF, ePub etc then look at this step for
    • “real world”, ie. natural scenes like trees, people, embedded as PNG files should be changed to JPG
    • drawings, cartoon images, musical scores composed of solid colours should be embedded as PNG not JPG. If a vector format is available (preferably SVG over EMF) then use that over PNG as it has “infinite” resolution. Note that exports from Sibelius as SVG use fonts for note shapes and so on. The fonts “OpusStd” and “OpusSpecialStd” must be installed on the recipient PC to view it. To avoid issues convert those glyphs to outlines in the SVG.
    • JPG images with quality set super high, or even just too high for a reasonably sized image file, the following Imagemagick command will give a reasonable picture and file size (strips any metadata and set JPEG quality to 80)
      • convert -strip -interlace Plane -sampling-factor 2x2 -quality 80 input-file output-file.jpg

Preparation of the PDF file

Really easy. Simply open the DOCX file in a word processor and Save as PDF. If using Microsoft Word on OSX use the “Use Microsoft online services option”. Usual size is 100 to 250 Kbyte. If there is a very large (ie full page image) may go to 400Kbyte.

Preparation of the Markdown file

This is the most complex stage of the process and there are many steps. Pandoc flavoured markdown with inline html is used.

Tips:

  • Make sure you are using a pandoc previewer that uses pandoc rather than the inbuilt Visual Code markdown-it markdown-previewer. If you don’t it won’t render the inline html. In Markdown Previewer Enhanced, make sure you have the pandoc previewer turned on.
  • Lint your markdown using the markdownlint extension. Don’t forget to add a .markdownlint.json file to the current (project) directory to avoid warnings about inline html.
    {
    "MD033": false
    }
  • If you need a QR code, then qrencode command line utility is handy, use margins set to zero to allow them to be set by your stylesheet etc, e.g.
    qrencode -o bpuc.svg -m 0 -t SVG https://www.bpuc.org

Conversion from DOCX

Use the pandoc program to produce a rough markdown file and extract any images into a directory named “media”.

pandoc -o output_file.md --extract-media=. input_file.docx

At the very top of the markdown file insert the following yaml code to create metadata for eBooks, changing the date in two places preserving the date format.

---
title: Order of Service - 25th August 2021
creator:
- role: author
  text: Brougham Place Uniting Church
subject: Religion & Spirituality
language: en-AU
date: 2021-08-25
...

After styles for the downstream programs directly after the yaml insert. Note the use of the “oservice” div class to stop styling to the order of service leaking to the rest of the page,

<style>
.point24 {
    font-size:1.33rem;
}
.point16 {
    font-size:0.88rem;
}
.smallcaps {
    font-variant:small-caps;
}
.musicack {
    font-size:0.88rem;
    font-style:italic;
}
.infoitem {
    font-size:0.78rem;
    font-style:italic;
}

.oservice {
    font-family: Perpetua,Baskerville,Big Caslon,Palatino Linotype,Palatino,URW Palladio L,Nimbus Roman No9 L,serif;
}

.oservice h2 {
  margin-top:2rem;
  margin-bottom:1rem;
  font-size:1rem;
  font-weight:normal;
  font-style:normal;
}

.oservice p {
  padding-left:2.2rem;
  margin-top:1rem;
}

.oservice ol > li > p {
  margin-top:1rem;
  padding-left:0rem;
}

.oservice h3 {
  margin-top:1rem;
  margin-bottom:1rem;
  font-size:1rem;
  font-weight:normal;
  font-style:normal;
  font-variant:small-caps;
  padding-left:2.2rem;
}

.oservice li {
    padding-left:0.5rem;
    list-style-position:outside;
}
.oservice ol {
    padding-left:1.5rem;
}
.oservice a:link {
  color:#0000EE;
}
.oservice a:visited { 
  color: #551A8B;
}
p.ackblock {
    padding-left:2.2rem;
    margin-top:1rem;
    text-align:right;
    font-size:0.78rem;
    font-style:italic;
}
p.indent {
    padding-left:2.2rem;
    margin-top:1rem;
}
p.doubleindent {
    padding-left:4.4rem;
    margin-top:1rem;
}
p.indentunindent {
    padding-left:3.2rem;
    margin-top:1rem;
    text-indent:-2.1rem;
}

p.itemclose {
    margin-bottom:0rem;  
}
p.indentclose {
    padding-left:2.2rem;
    margin-top:0rem;
}

p.poetryfirstlevel{
    padding-left:4.2rem;
    text-indent:-2rem;
    margin-bottom:0;
    margin-top:0;
}
p.poetrysecondlevel{
    padding-left:5.2rem;
    text-indent:-2rem;
    margin-bottom:0;
    margin-top:0;
}
p.poetrythirdlevel{
    padding-left:6.2rem;
    text-indent:-2rem;
    margin-bottom:0;
    margin-top:0;
}
p.dindentfirstlevel{
    padding-left:6.4rem;
    text-indent:-2rem;
    margin-bottom:0;
    margin-top:0;
}
p.dindentsecondlevel{
    padding-left:7.4rem;
    text-indent:-2rem;
    margin-bottom:0;
    margin-top:0;
}
p.dindentthirdlevel{
    padding-left:8.4rem;
    text-indent:-2rem;
    margin-bottom:0;
    margin-top:0;
}
p.enditem {
    margin-top:5rem;
    padding-left:2rem;
    padding-right:2rem;
    text-align:center;
}
</style>

Then after that place a div block around the remainder of the markdown code in the file and a fixed trailer for the logos at the end.

<div class="oservice">
...
Markdown code
...
<p><span style="float:left">![](UCemblemRGB.svg){width="1.34375in" height="1.34375in"}</span><span style="float:right">![](BPUC_colour.svg)</span></p>

<p class="point24" style="text-align:center;clear:both">[www.bpuc.org](https://www.bpuc.org/)</p>

</div>

Preparation of images

Each of the images from the DOCX file will be placed in the media directory. Copy these and transform into the appropriate format according the instructions on preparation of the DOCX file above. If the transformation of the image results in an image that is roughly the same size as the original then don’t transform, just copy.

Alternatively the images can be created directly in Canva in the wanted sizes and overlays.

These images should be used in the Markdown document and placed alongside (ie in the same directory) as the markdown document.

Featured image

The Watson WordPress theme requires a 608×400 pixel (1x size) or 1216×800 (2x size, preferred) pixel image. The larger one works better as the theme reuses the featured image on the carousel. Ideally this would be an SVG but the background “real world” picture bloats the size of the file, even in transit on serving when compressed so of late a 1216×800 WEBP has been used. Further work could be done on SVG(z) or maybe AVIF in future.

Reduce the quality of the file (PNG from Canva) to just above 100Kbyte works fine and remove headers similar to above e.g.

# Vary the quality parameter to get a file just above 100Kbyte, valid values are 1-100.
magick convert input.png -strip -quality 80 yyyymmddfeatured.webp

YouTube image

This is done in Canva easily. Size is 1280×720 pixels. Download as PNG with a 2MB file size limit to avoid fuzziness of text as much as possible. YouTube will convert the PNG file itself as required.

Editing the detail

Add in the appropriate codes to the markdown (mysterious handwaving process here)

Poetry

It is important to maintain the line breaks in poetry. The Lord’s Prayer is presented in a standard way for the printed version, however when line width is unlimited, there should be a line break (e.g. breathe here) in the last line between “glory are yours” and “now and forever”. Alter the markdown version to have a line break here. At some point it might be able to hint as to suggested line breaks but that isn’t supported in markdown/html easily.

Testing the result

Produce all the different output formats and make sure they look OK.

Preparation of the HTML file

Simply use Pandoc to convert Markdown to HTML. Use ascii to avoid Unicode weirdness and standalone so you can easily view in a browser for checking

pandoc --standalone -o output.html --ascii input.md

Preparation of the ePUB file

Use Pandoc with no defaults

pandoc -o output.epub input.md

After this step you should validate the output file using epubcheck to catch any malformed markdown that might trip up an E-reader.

Preparation of the Mobi file

Using kindlegen

kindlegen input.epub

Uploading to the website

Now you should have the following files to upload

  • PDF version
  • ePub version
  • mobi version
  • each of the images used

The html code can just be copy/pasted into WordPress directly as a Custom HTML block. Grab everything including the style sheet inserted above but not the </body> at the end of the document, nor any images. Images should be inserted as WordPress Image blocks and centred. If there are images through the file then use a custom html block after each image. The Style section only needs to appear in the first custom HTML block.

Creating the page and post of the week

Each week a post and a page are created for each service. The following steps should be taken with each on creation.

Post on Front page

In case there are comments the current page is renamed to be old (previous week) and then the old page cloned to be the current page. This process will give inconsistent results for readers until the cloned page is published.

  • From the list of posts, sort by date and select the most recent (ie last weeks service)
  • Press quick edit and make the following changes:
    • Change the “slug” to be worship-online-month-dD
    • Change the date”, “hour” and “minute of the post the same as the start of the service so that date ordering works.
    • Uncheck the “Show in featured slider” box
    • Press the “Update” button
  • Press “clone” on the page you just edited to make a copy
  • Press quick edit on this new “Draft” page and make the following changes:
    • Change the “title” to be of the form Worship online – month dD
    • Change the “slug” to be worship-online
    • Check the “Show in featured slider” box
    • Press the “Update” button
  • Upload the featured image to the Media Library
  • On the current page (worship-online)
    • Change the Youtube embedded link to this weeks Youtube URL
    • Change the Youtube button link to the same Youtube URL
    • Change the Newsletter button link to this weeks MailChimp URL
    • Change the Newsletter link to the same MailChimp URL
    • Change the Featured post Image to the appropriate one for this week
    • Press the “Publish” button (twice if it is the first edit)

Order of Service Page

In case there are comments the current page is renamed to be old (previous week) and then the old page cloned to be the current page. This process will give inconsistent results for readers until the cloned page is published.

  • From the list of pages, select the current page https://www.bpuc.org/orders-of-service/order-of-service-this-week/ with a name of the form Order of Service – dD[th|st|nd|rd]-month-YYYY/
  • Press quick edit and make the following changes:
    • Change the “slug” from order-of-service-this-week to order-of-service-dD[th|st|nd|rd]-month-YYYY
    • Change the “date”, “hour” and “minute of the post the same as the start of the service so that date ordering works.
    • Press the “Update” button
  • Press “clone” on the page you just edited to make a copy
  • Press quick edit on this new “Draft” page and make the following changes:
    • Change the “title” to be of the form Order of Service – dD[th|st|nd|rd]-month
    • Change the “slug” to be order-of-service-this-week
    • Press the “Update” button
  • Upload to the media library
    • the full size image for the week
    • PDF version of the order of service
    • ePub version of the order of service (may be done later)
  • Edit the new page and:
    • Replace the top image with this weeks image
    • Change the links for ePub and PDF to this weeks image (easiest done in HTML view, make sure you have the uploaded month in the URL)
    • Change the custom HTML block to this weeks order of service. If not yet ready make it blank until done.
    • Press the “publish” button (twice if this is the first time the page is edited)

Adjustments to previous weeks post

Once the new order of service page is in place, edit last weeks post press edit and:

  • Change the link to the order of service (two places) to be of the form order-of-service-dD[th|st|nd|rd]-month-YYYY

Changes for Holy Week and Christmas

In these two festival times there are extra services not on Sundays that use a different naming convention and there are other steps that need to be taken.

Filenames are left the same as yyyymmdd with an optional suffix of a single letter if there are two services in one day, e.g. Christmas Eve on a Sunday use 20231224e could be used.

The titles of the pages should just be the name of the service instead of the date, e.g. Maundy Thursday.

The slugs (URLs) should be the name of there service with the year appended, instead of the date for the main page, e.g. good-friday-2022. Similarly for an order of service the service and year suffix should be applied as well, e.g. order-of-service-good-friday-2022. Easter Sunday or Christmas on a Sunday is a special case. The slug should initially be worship-online as for any Sunday service and then change to name of service and the year when the next week is done, e.g. christmas-day-2020 or easter-sunday-2023.

For the summary page for Christmas or Easter, include the name of the year in the title to reassure the reader that they are reading a current page. Also include the day of the week and the date, e.g. Christmas Day (Wednesday 25th December 2024) when giving the name of a service. The URL for the page should just be christmas or easter and the page remain there permanently.

Extra banners for quick access on the day for the extra services should be added in the WordPress theme. Appropriate colours, e.g. Black, Red, Gold may be used but be careful that sufficient contrast for accessibility is maintained between the text and the background. These should be triggered by an expression that first checks the month and then the day of the month.