Appearance and Design

# 12 Standard Practices and Workarounds

Last update: October 4, 2022

# Audio

• When embedding audio from Kaltura, change the display size of the media player by changing the height value in the embed link to 70.
• When a book provides an audio version of the chapter, that audio file should:
• Be embedded at the beginning of the chapter.
• Be preceded by this sentence: Click play on the following audio player to listen along as you read this section.
• For all other uses of audio:
• Put the audio player and the transcript inside the same shaded textbox.
• The transcript should immediately follow the audio player.

Styles for Transcripts

• Heading: Title of the Audio Clip Transcript
• Each speaker starts on a new line. Bold their name, followed by a colon. Example –  Josie: Transcripts are useful.
• Descriptions of non-speech sounds and tones of voice should be in square brackets and in italics: [Muffled radio in the background]

# Fill-in-the-Blank Spaces

You can use `aria-label="blank"` so an underline that indicates a fill-in-the-blank space is read as “blank” by a screen reader:

• HTML: `Fill in <span style="text-decoration: underline;" aria-label="blank"> </span>.`
• Result: Fill in the         .
Note that you will have to copy and paste the `aria-label="blank"` into the HTML so it doesn’t get stripped out when switching between the text and visual editor.

# Editing Marks

The following will allow you to mark text as crossed out or deleted in a way that is accessible to people using screen readers.

• Signify text that has been crossed out: `<span role="deletion">The deleted text.</span>`
• Signify text that has been inserted: `<span role="insertion">The inserted text.</span>`

`/*Editing Marks*/`
`[role="insertion"] {`
`color: #1215b0;`
`text-decoration: underline;`
`}`
`[role="deletion"] {`
`color: #be0000;`
`text-decoration: line-through;`
`}`

It would look as follows:

• This is the deleted text.
• This is the inserted text

# H5P Activities (Offline Copies)

There are two options for providing offline copies of H5P activities in export/print formats.

1. Providing them in the back matter of the book where students can navigate to.
2. Providing them directly where the original H5P activity appears.

## Provide in Back Matter

Offline copies of H5P activities can be created and added to the back matter of the book. See the Math for Trades: Volume 1 book for an example of how to set this up:

## Provide Directly In-Text

When exported as a PDF, the H5P would be rendered as:

If you don’t want this message in your PDF, go to the Text(HTML) and put the H5P code in a div class as `<div class="h5p"> [h5p id="#"] </div>`.

Then in the Custom CSS for PDF, add the following code:
``` .h5p{ display: none; } ```
Similarly, after providing the print equivalent of the H5P in text, wrap them with `<div class="pdf"> print equivalent of H5P </div>`. Then in the Custom CSS for Web, add the following code so they don’t display redundantly with the H5P in the web book:
``` .pdf:not(body#tinymce.wp-editor .pdf){ display: none; }```

# Images

• Always insert the image full size in Pressbooks initially. You can scale it down after if it’s too big. This ensures the image will display clearly in all export formats.
• Generally, images should not link to their media file. The only time they should link to the media file is if the image cannot be printed large enough to be visible in the PDF. That way students can navigate to the link to view it full size. (For an example, see the Times Table image in this chapter: Multiplying Whole Numbers.)

# LaTeX (Math)

Math content can be written in Pressbooks using LaTeX, a math mark-up language, and rendered via MathJax. Here are the basics of writing math equations:

• Each equation needs to be contained within short codes: ` `
• In the editor, you will only see the LaTeX. To see what it displays as, save and view the webbook. Check the webbook often to ensure the equations are displaying correctly.

Here are some common things you will likely need:

Common LaTeX Symbols
Symbol Name LaTeX
$\times$ Multiplication \times
$\div$ Division \div
$x^2$ Superscript x^2
$=$ Equals =
$+$ Plus +
$-$ Minus
$\%$ Percent \%
$:$ ratio :
$3\text{ metres}$ Text 3\text{ metres}
$\frac{1}{2}$ Fractions \frac{1}{2}
$\longrightarrow$ Long Right Arrow \longrightarrow
$\cancel{41}$ Strike through a number or word \cancel{41}
$\$ Dollar sign \\$
$1\hspace{0.50cm}2$ Space 1\hspace{0.50cm}2

## LaTeX bugs

Math Bugs
Known Bugs Work Around
> and < signs break LaTeX equations in the PDF. See GitHub issues #1918 – need to follow up with Steel about this Write these equations in plain text rather than LaTeX.

# Links (Internal) – Print PDF

Add `class="internal"` to all internal links. This ensures that web addresses for internal links will not display in the Print PDF (which is a setting we have enabled for external links via the CSS, see Custom Styles).

If it is easier for links to opt in rather than opt out, you can use a class to specific which links you do want to be inserted in the Print PDF. That CSS is documented under Custom Styles > PDF > Optional.

1. Using the Search and Replace tool, search for `a href="https://pressbooks.bccampus.ca/bookurl`
2. Replace with the following: `a class="internal" href="https://pressbooks.bccampus.ca/bookurl` (Preview the replacement before confirming to ensure you aren’t forgetting a backslash or inserting a space.)

1. If the text uses same-page links, search for `a href="#`
2. Replace with the following: `a class=internal" href="#` (Preview the replacement before confirming to ensure you aren’t forgetting a backslash or inserting a space.)

In addition, links do not need to be provided for media attributions in export formats. As such, these can be marked as internal too. This is something that may need to be done manually, but you can search and replace the common sites that are included in the media attributions.

1. For example, searching for things like `<a href="https://creativecom`, `<a href="https://pexels`, `<a href="https://pixabay`,

# Lists

The following can be used to customize lists. This is especially useful when you have sublists that are not numbering how you want them.

• Lowercase letters:` <ol type="a">`
• Capital letters:` <ol type="A">`
• Roman numerals: `<ol type="I">`
• To start numbering from the number “3”: `<ol start="3">`
• Two columns: `<ul class="twocolumn">`
• Three columns: `<ul class="threecolumn">`

# Spelling

All of our books should use Canadian spelling. If you are unsure about the correct spelling, check the Canadian Oxford Dictionary.

Here are common words that are spelled differently in Canada vs. the U.S. that we can use the search-and-replace feature in Pressbooks to correct.

• behavior – behaviour
• center – centre (Note that “center” is also used in the HTML. Be careful not to replace that.)
• centered – centred
• color – colour (Note that “color” is also used in the HTML. Be careful not to replace that.)
• labor – labour
• liter – litre
• meter – metre
• neighbor – neighbour

# Embedded Videos

Embed videos whenever possible. This will be true for most videos hosted in YouTube and Kaltura. When embedding videos, be sure to do the following:

• Before the embedded video, include the following statement: Watch the video [Name of Video (# minutes)].[1]
• Attribute the video according to the the Attributions procedures for videos.

# Webbook Chapter and Part URLs

Chapter and Part permalinks should match the name of the section but should exclude references to “chapter,” “part,” or the particular number. This makes it easier for people adapting the content in the future if they use a different numbering system. It also means if chapters are deleted/moved around, you don’t have to edit all of the permalinks.

The chapter URL should not exceed four words. If the chapter title is longer, it is okay if the URL does not match the chapter title exactly. Select a URL that represents the topic of the chapter.

For example:

• Title: Chapter 2 Learning Preferences
• URL: /learning-preferences/

1. Use the name and length of the video to the nearest minute as the link text. Link to the video source in YouTube or Kaltura.