Introducing pressbooks/ideas 💡

I’m always looking for better ways to keep track of feature suggestions from members of the Pressbooks Open Source community, which within our small and very active team can often get lost in the shuffle. Messages in Slack can fly by before we make note of them, and often threads in the forum include a number of ideas which should be evaluated as standalone feature suggestions but get lost in a broader discussion.

So, borrowing from the WP-CLI project where I first saw this implemented, I’ve created a GitHub repo for ideas from Pressbooks users. If you have an idea for Pressbooks that you’d like to suggest to our team, you can open an issue. We will evaluate your ideas on a regular basis for inclusion in our sprints and longer-term roadmap. You can check on the status of your idea by visiting the idea board.

I’m looking forward to seeing what emerges! As always we welcome feedback and discussion in the forum.

Sprint Preview: Feb 19 – Mar 2

This year will be a busy one for the Pressbooks team, so we’ve decided to share publicly what we’re working towards in our two-week sprints. We hope this will give you a better sense of what’s going behind the scenes, and help you plan your own development schedule!

Our sprint running February 19 – March 2 will focus on:

    • Interactive content styling
      We have completed our first pass implementation of interactive content support, and will be finalizing the styling of the messages injected in place of unsupported content in exports. This work is slated for release in 5.1 and is supported by eCampus Ontario.
    • Plugin Compatibility Checker
      This feature will identify plugins that are (in)compatible with available updates based on their plugin headers. A warning will inform Pressbooks administrators about extensions that haven’t been updated for compatibility with new releases.
    • Theme Development
      We will also be continuing our theme development work, using the theme conversion process to identify improvements and potential new SCSS components in Buckram.
    • Pressbooks 5, Aldine 1.0 & Book 2.0 (including McLuhan) release
      We plan to release the above early in the second week of this sprint, and to deploy to our hosted networks soon after.

Are you working on related goals? Let us know in the Pressbooks Forum!

Pressbooks 4.5.1

We tagged Pressbooks 4.5.1 on GitHub on January 25th — apologies for the late release notes! This is a minor maintenance release in preparation for Pressbooks 5, and provides some forward-compatibility for those who will not be ready to upgrade to Pressbooks 5 right away.

Pressbooks 4.5.1 requires WordPress 4.9.2.

  • [FIX]: Disallow dangerous file types from upload via the Import form (9bcebf1)
  • [FIX]: Handle author objects containing multiple authors during clone operations for forward-compatibility with Pressbooks 5 (9231ffa, b0e03c4, 035c1b9)

Sprint Preview: Feb 5–16

This year will be a busy one for the Pressbooks team, so we’ve decided to share publicly what we’re working towards in our two-week sprints. We hope this will give you a better sense of what’s going behind the scenes, and help you plan your own development schedule!

Our sprint running February 5 – 16 will focus on:

    • Release testing of Pressbooks 5, Aldine 1.0 & Book 2.0 (including McLuhan)
      Our team will be working through the final testing before release, slated for Feb 14th (pending anything unexpected).
    • First pass implementation of interactive content support
      Building off a product specification finalized in the previous sprint, we’ll be working on the first iteration of interactive content support across all formats. This development is supported by eCampus Ontario.
    • Jacobs 1.0
      We’ll be letting our new team member Daniel loose on finalizing Jacobs, one of two new Open Source themes ideal for Open Textbook creation (supported by eCampus Ontario). Daniel has joined the Pressbooks team for three months to help us transition our themes to the new structure.

Are you working on related goals? Let us know in the Pressbooks Forum!

GitHub Housekeeping

A quick note from the dev team: we are working to improve our GitHub issue management. With this in mind, we’re closing stale issues which have not seen any activity in the last 60 days. This does not mean that they will not be revisited — many of them are on our roadmap, in fact! We just want to reflect what we are actually working on.

Sprint Preview: Jan 22–Feb 2

This year will be a busy one for the Pressbooks team, so we’ve decided to share publicly what we’re working towards in our two-week sprints. We hope this will give you a better sense of what’s going behind the scenes, and help you plan your own development schedule!

Our sprint running January 22 – February 2 will focus on:

    • Preparations for Pressbooks 5
      Our team will be thoroughly testing Pressbooks 5 to ensure its readiness for release.
    • First cut of chapter import using the Pressbooks REST API
      We’ll be developing a feature that allows the import of individual chapters directly from a Pressbooks book. This development is supported by eCampus Ontario.
    • Product specification process for interactive content support
      The demand for interactive content, such as H5P, PHET simulations, iFrames, etc. has been steadily increasing, especially in the OER community. Our product team will be working on a product specification to best handle interactive content (audio and video) across all formats. This development is supported by eCampus Ontario.
    • New Open Textbook themes
      We’ll be testing and finalizing Jacobs and McLuhan, two new Open Source themes ideal for Open Textbook creation, in preparation for their upcoming release. The development of these themes has been supported by eCampus Ontario.
    • Book 2.0 (contains McLuhan) and Aldine 1.0
      Continued testing and review of the new webbook (Book 2.0, which contains McLuhan) and new network homepage and catalog (Aldine 1.0) themes in preparation for release. The development of these themes has been supported by Ryerson University.

Are you working on related goals? Let us know in the Pressbooks Forum!

Pressbooks 5: Developer Guide

Pressbooks 5 will introduce some significant changes to the ways we store and retrieve data within the book, a new export module, modifications to two existing export modules, and some changes to the filesystem for user generated content. This post outlines these key changes and the migration paths that we’ve built in to facilitate the upgrade to Pressbooks 5.

Data Changes

Content Visibility

In Pressbooks 4.x and earlier, the visibility of content across different media is controlled by a combination of custom post metadata and core post status. For front matter, back matter and chapters, the pb_export post meta value determines whether or not they appear in exports, while their post status (draft, pending, private, or publish) determines their visibility in the webbook.

In an effort to better conform to WordPress best practices and streamline the user experience, we’re using the post status as the source of truth for whether front matter, chapters, and back matter appear in web, exports, or both. We’ve added a new web-only post status, and content visibility will now be determined as follows:

Post Status Web + REST API Exports
draft hidden hidden
web-only visible hidden
private hidden visible
publish visible visible

In terms of the user interface, we’re changing this:

A mockup of the Export Settings & Publish panels in Pressbooks 4.x.

To this:

A mockup of the Status & Visibility panel for a new chapter in Pressbooks 5. A mockup of the "Status & Visibility" panel for an existing chapter in Pressbooks 5.

Note that we’re changing the primary action button from "Publish" for new content and "Update" for existing content to "Create" and "Save", respectively.

Your front matter, back matter and chapters will be automatically updated when you visit your book after updating to Pressbooks 5.

Contributor Management

Pressbooks 4.x lets you add a single author and multiple contributing authors, editors, and translators in your Book Information and lets you add a single author for each front matter, back matter, or chapter. Pressbooks 5 imports all your existing authors (and Pressbooks users who are assigned to your book) and creates entries in a new contributor taxonomy. Then, it repopulates new relevant metadata fields with a list of contributors that match your book’s existing contributors. For example, if you have an author named Alice X and two editors named Bob Y and Eve Z, your Book Information will contain the following in Pressbooks 4.x:

Field Value
pb_author 'Alice X'
pb_editor ['Bob Y', 'Eve Z']

In Pressbooks 5, your Book Information will contain the following:

Field Value
pb_authors 'alice-x'
pb_editors ['bob-y', 'eve-z']

The values saved in Book Information are the slugs of entries in the contributor taxonomy. Also, for backwards-compatibility, the new field names are pluralized so that any third-party code that looks for the old fields will still be able to retrieve them for the time being.

You’ll be able to edit the display names of these contributors in one place — the new Contributors page, which is a standard WordPress taxonomy management page — and you’ll be able to quickly and easily select from your list of contributors to add assign authors throughout your book (if you have a book that consists of chapters with different authors, and you also want to include credits for all the authors in your Book Information, this will make maintaining that information much easier). In future releases of Pressbooks, we will be able to add metadata to contributors, including profile pictures, author websites, and more, for display on your webbook cover page or individual front matter, back matter, and chapters.

We’re also adding a new class, \Pressbooks\Contributors\, and some other related functions to retrieve arrays or formatted lists of contributors.

The migration of your book’s contributor data will happen automatically when you visit your book after updating to Pressbooks 5.

Licenses

In the same way that we’re moving contributor data to a contributor taxonomy, we’re moving the available licenses into a new license taxonomy. That way, if you need to add a custom license for your book, it will immediately be available in all chapters, front matter, and back matter as well as your Book Information. This migration will happen automatically when you visit your book after updating.

Export Changes

HTMLBook Preview

In Pressbooks 5, we’ve introduced a new HTMLBook export module as a proof of concept. We’re excited about the potential of adopting and advancing this proposed standard for the semantic representation of books on the web, and we will be actively developing our export module in the months to come. We’re also working with the creators of HTMLBook to expand and improve the standard (to begin with, we’re proposing the addition of new front matter and back matter types and of new block elements, including educational textboxes).

At this time, our HTMLBook exporter is not production-ready, but we will be using it as a testbed to refine our best practices for coding export modules in Pressbooks.

XHTML and EPUB Markup Changes

We’re making a change to the way we mark up our XHTML and EPUB exports, but only for themes that use our SCSS component library, Buckram. In Pressbooks 4.x, chapter subtitle and author elements are not wrapped in the same container as the chapter number and title:


<div class="chapter standard" id="chapter-1">

  <div class="chapter-title-wrap">

    <h3 class="chapter-number">1</h3>

    <h2 class="chapter-title">Loomings</h2>

  </div>

  <div class="ugc chapter-ugc">

    <h2 class="chapter-author">Herman Melville</h2>

    <h2 class="chapter-subtitle">The First Chapter</h2>

    <p>Call me Ishmael.</p>

  </div>

</div>

This makes it very difficult to reliably style the first page of front matter, back matter, and chapters.

In Pressbooks 5, books that use Buckram-based themes will now have the following markup:


<div class="chapter standard" id="chapter-1">

  <div class="chapter-title-wrap">

    <h3 class="chapter-number">1</h3>

    <h2 class="chapter-title">Loomings</h2>

    <h2 class="chapter-author">Herman Melville</h2>

    <h2 class="chapter-subtitle">The First Chapter</h2>

  </div>

  <div class="ugc chapter-ugc">

    <p>Call me Ishmael.</p>

  </div>

</div>

This change will only impact themes using Buckram, which include our open source Clarke theme and the premium Asimov theme (the latter only available to Pressbooks EDU or Pressbooks.com users). We are thoroughly testing these Buckram-based themes to ensure that this change does not affect existing books. If you have built a theme using Buckram, we suggest you test your theme as well once this issue has been closed.

Filesystem Changes

In Pressbooks 4.x, all export files, (S)CSS and other user-generated files are stored in subfolders of your book’s uploads directory. We’re moving them all into a pressbooks folder to prevent conflicts between our files and any other files that plugins may generate. This will happen without the need for any intervention on your part.

Pressbooks 4.5.0, Pressbooks Book 1.12.0, and Clarke 2.1.1

We tagged Pressbooks 4.5.0Pressbooks Book 1.12.0, and Clarke 2.1.1 on GitHub yesterday and deployed them across our hosted networks. Here’s what’s changed:

Pressbooks 4.5.0

NOTICE: Pressbooks >= 4.5 requires PHP 7.0 or greater.
NOTICE: Pressbooks >= 4.5 requires WordPress 4.9.1.

  • [FEATURE] Switching to a new theme will now update some PDF theme options to match the theme’s values (see #456, #984).
  • [FEATURE] Add initial support to PDF and Ebook theme options for themes which skip lines between paragraphs by default (see #985).
  • [CORE ENHANCEMENT] Use standard build tools package pressbooks-build-tools for asset handling, upgrade Stylelint (see #1000).
  • [CORE ENHANCEMENT] Require PHP 7.0 or greater (see #935, #987).
  • [CORE ENHANCEMENT] Add exclude and include support to Pressbooks\Utility\rcopy()(see #990).
  • [CORE ENHANCEMENT] Improve Theme Lock feature in preparation for Pressbooks 5.0 (see #995).
  • [CORE ENHANCEMENT] Add Prettier for SCSS and JS formatting (see #991).
  • [CORE ENHANCEMENT] Optimize subsection parsing (see #992).
  • [CORE ENHANCEMENT] Optimize __UNSET__ style (see #999).
  • [CORE ENHANCEMENT] Optimize unit testing (see #997).
  • [FIX] Replace ‘Sites’ with ‘Books’ throughout Pressbooks interface (see #993).
  • [FIX] Replace ‘Exotic formats’ with ‘Other formats’ on the Export page (see #996).
  • [FIX] Fix bug related to #42574 which prevented widget editing on the root blog (#998).
  • [FIX] Fix type mismatch in \Pressbooks\Licensing class (see 23ee4ff)
  • [FIX] Fix typo in EPUB exporter — the acronym is OEBPS (Open eBook Publication Structure) (props @bdolor; see #988).

Pressbooks Book 1.12.0

  • [CORE ENHANCEMENT] Updated Ekatra fonts (for the Gujarati language) to the latest version.
  • [FIX] Fixed an issue where invisible parts would appear in the webbook TOC (props to Michael Shiflet for the bug report).

Clarke 2.1.1

  • Fixed incorrect fonts in description.

Pressbooks 4.4.0, Pressbooks Book 1.11.0, Clarke 2.1.0, and Donham 1.7.0

We tagged Pressbooks 4.4.0Pressbooks Book 1.11.0, Clarke 2.1.0 and Donham 1.7.0 on GitHub today and deployed them across our hosted networks. Here’s what’s changed:

Pressbooks 4.4.0

NOTICE: Pressbooks >= 4.4 requires WordPress 4.9.

  • [FEATURE] You can now assign Thema subject categories to your book on the Book Information page (see #978).
  • [FEATURE] Part slugs are now editable (props to @colomet for the suggestion; see 3f5eca2).
  • [CORE ENHANCEMENT] Pressbooks now uses WordPress’ included CodeMirror scripts and styles for our Custom Styles editor (see #980).
  • [CORE ENHANCEMENT] Added the pb_global_components_path filter which lets book themes override the global components path to point to their own bundled components libraries (see #982).
  • [CORE ENHANCEMENT] Added the pb_pre_export action to allow tweaks prior to an export routine (see 5302eea).
  • [CORE ENHANCEMENT] Our app() function now matches Laravel 5.4’s function signature (see cdcb9e8).
  • [FIX] Importing a Word document with multiple images now works properly (props to @rootl for the bug report; see #288 and #977).
  • [FIX] Chapters will now correctly inherit their book’s license in the API (see #979).
  • [FIX] Chapters will no longer show raw content in the API if they are password-protected (see #975).
  • [FIX] Uploading an image to the user catalog no longer causes an error (props to @emasters for the bug report; see #983).

Pressbooks Book 1.11.0

  • [FEATURE] Add parameter to pressbooks_copyright_license() to allow hiding custom copyright license (see #50).
  • [CORE ENHANCEMENT] Remove WordPress generator meta tag (see 6c621ad).

Clarke 2.1.0

  • Preparations for Book 2.0 compatibility.

Donham 1.7.0

  • Preparations for Book 2.0 compatibility.