Originally published at: https://pressbooks.org/blog/2018/01/17/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…
1 Like
Contributor Management:
If i have 5 authors in a book but 100 register users with no role of author. Will I have in contributor taxonomy 105 authors?
XHTML and EPUB Markup Changes:
<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>
So, if I have sections inside of the page and I need to use titles, Should I start with H3? as chapter title is H2.
If so, maybe is a good idea to delete the H1 and H2 from the text editor, and we will avoid mistakes.
XHTML and EPUB Markup Changes:
<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>
Is weird for me we have in a page title H2 and a subtitle as H2 too. The computer understan the relation between both? if the content belongs to the title or for google the content belongs to the subtitle?
it would be
1.- h2 (the title)
2.- h2 (the subtitle)
2.1.- (the content)
in my mind, in such relationshipt, the content belongs to the subtitle, not the title.
i do not understand very good the hierarchy (general speaking)
You understand it perfectly—it’s bad. We are dealing with some significant technical debt in our existing XHTML/EPUB output, but unfortunately we have a large number of themes built on this output. Our path forward is adopting HTMLBook semantic structure, styled with Buckram, and maintaining this old, non-semantic output as a fallback for themes which haven’t been updated to support the new semantic structure.
No, keep using <h1> elements for section headings within your chapters. That is correct. See:
1 Like
We will only be importing users into the Contributor list if they have write permissions within the book. So if you have subscribers, they will not be added to the contributor list.
2 Likes
For reference, here’s the markup a chapter will have in HTMLBook:
<section class="chapter" data-type="chapter">
<header>
<h1>Loomings</h1>
<p class="author" data-type="author">Herman Melville</p>
<p class="subtitle" data-type="subtitle">The First Chapter</p>
</header>
<p>Call me Ishmael.</p>
</section>
1 Like
Thanks for the details, I assume that it may be possible to make a custom change “Preview Changes in Web” back to “Preview” ?
Cheers,
Steve
Possible, but the reason we changed this is to reflect that the preview we can show is of the webbook version (not PDF/EPUB output). We’ve had some user feedback that the old “Preview” button was confusing; many users of Pressbooks use it for PDF and Ebook production only and so clarifying the type of preview was a request we were responding to.
Thanks,
Preview will work better for us as it is consistent with WordPress and is an intuitive button within a web browser context. The interface for the current PB has been excellent and intuitive for blogger / e-authors. Hence, a surprise to see such a major shift in the user interface design.
cheers,
steve
Addendum - Could ‘profiles’ be used as a way to provide alternative UI (e.g. WP versus PB) ? Perhaps an extreme accommodation of divergent UI for a plugin/framework on WordPress.
Thanks for writing this all up, Ned. I’ve just finished reading it carefully, and it all looks terrific. We’re very excited for 5.0’s release. Will there be anything similar forthcoming to describe some of the planned changes to Pressbooks Themes? Your diagram in the Slack channel was invaluable,
and having a short prose narrative/documentation document like this for the theme changes would be really helpful for us. I’m happy to help contribute to documentation and contribute writing/editing skills if they’d be of use …
Hi Steel, I’m planning on writing up and sharing something about themes next week!
2 Likes
Excellent. I’m looking forward to it.
Should those hosting PB themselves expect any new dependencies to support PB 5.0? Will there be any requirements on the server or db side to support the major version change? I didn’t see this in the write-up, and so assume not – but it’s worth asking!
Etienne
The only new requirement will be that if you are using Luther (the book theme in Pressbooks Book 1.x) you will need to install it from https://github.com/pressbooks/pressbooks-luther to continue using it when you upgrade. But I will write more about this in the discussion of themes next week.
Now, looks like we have several places for the creation of people under different categories, but all of them are contributors. Is a little complicate at first.
maybe by having just one place for the creation of Contributors and then, to be able to use it from any place…
Those buttons all link to the same place.
I know. that´s the issue. Looks like we have several categories of people. Not just one.
Context: someone wants to add a new person to the “Reviewer” list. Do we make them scroll up to the top of the page to find the one link they have to use to manage all contributors, or make them use the “Contributors” sidebar menu link? The idea with having a button by each category was ease of access to the contributor list no matter what you’re currently editing. Is it too confusing? The goal was convenience.