Repository navigation
Replies: 11 comments 10 replies
|
The documentation for VitalSource Bookshelf EPUB submission is at https://www.vitalsource.com/products/vitalsource-epub3-implementation-guide-vitalsource-vvstdocsepub3implementguide |
|
Thank you! I’ll add that to the documentation list |
|
@rickj I like the way VitalSource breaks out the navigation type footnotes by where in the EPUB the note is placed. Thank you! |
|
As an eLearning Developer, let me jump in here. I have created loads of learning materials. From a best practices outline point of view, I always have to ask the questions:
Subject: Notes in EPUB I agree with Brady that there are differences between:
Any design discipline, like eLearning, web, and EPUB creation, is about form (presentation) and function (structure and content). Notes are function. They are expanded descriptions of a word or concept that you want to make without breaking the flow of information in the document. Where the notes show up and how they are styled are form. In an outline of best practices, I would first define what we are discussing and how a reflowable EPUB document differs from its print equivalent. The EPUB medium presents advantages and limitations. One of the limitations is that a footnote, i.e., a side note at the bottom of a page, works great in print. It is a programming nightmare for a reflowable EPUB. And because the viewport is constantly changing, the footnote displays as a pop-up. Same function, different form. And so in my mind, if we denote a footnote in print with the attribute EPUB:TYPE="noteref" in EPUB, let's simply explain that the function is the same, the vocabulary and process shifts as we move into EPUB to adjust to the medium. I would ditch footnote in practice because the term "foot" is misleading and will cause confusion. Better to call it a note and be done with it. Same function, different context. It is NOT at the foot of the page. It is a pop-up, and how it displays is controlled by the reading system. The mechanics of using a number after the word, making it superscript, and linking that number to a named anchor (in an aside container) elsewhere in the document are standard. Internal links (named anchors) are one of the first things I learned as a web designer. I'm assuming that will work across reading systems since they are all based on XHTML or HTML5. In other words, hypertext is baked into the system. Audience: This is a best practices document. I don't know who my audience is going to be. Are they a seasoned coder wanting to know how to best apply markup to EPUB? Are they new to markup, and do they need handholding? Are they an author trying to figure things out? The W3C specs are very technical and have a programming or web design (markup familiar) audience. Best practices should be more tailored for a general design audience that may be familiar with markup. Maybe they aren't. If they aren't, I would provide an noteref that nudges them to a resource to give them the prerequisite knowledge. Our goal is to help guide an end user to the resources so they can understand how to create a successful EPUB experience when creating notes. If we do it right, everyone wins. Let's explain what it is, how it works in the field, and the best way to do it. |
People with some ebook production knowledge, but questions about the best way to implement notes
I’m not sure I understand this. Is it different than “What’s in it for them?”
Makes sense to me! I do think we should include terms that are familiar to people who make books. I don’t think we should banish the term “footnote” or “endnote” altogether. Especially if we explain that notes cannot appear at the bottom of a view screen.
Only some notes are pop ups. Some that are reached by navigating away from the current text and then back.
If we go too basic, the document could get very long. We could focus the discussion on how notes behave in an epub vs. print equivalent. |
|
Do not assume that reading systems handel footnotes and endnotes properly. At epubtest.org in the fundamental non-visual test books we test for this. We find that that an reading system will go to the link, but not deep link to the location exactly. Likewise, Going back is a problem. We have an article on this and a test book: |
|
@GeorgeKerscher I suspect that whether a RS functions properly is outside the scope of our document! [smile] |
|
In Thorium there is an option to turn off the popup footnotes and treate it like a normal link. I have selected not to have popup footnotes. I would like a consistent experience when following a link. We Also do not know about the accessibility of these popups, because the content may be larger than something simple. What happens in a popup when the content must scrol? Also, we are developing guidance for extended descriptions, which will probably very similar to an endnote. Here too, I want a consistent experience. Extended descriptions will in many cases contain tables and other complex HTML constructs. |
Right! And therein lies the confusion, using print-centric language for electronic delivery. Endnote makes sense. It is at the end of the document; regardless of whether that "document" is printed or electronic. Footnote does not make sense. It is not at the foot of the page/viewport. epub:type="noteref" is pretty clear. We just need to retrain authors/publishers that the equivalent of a footnote in print is a "note", or "noteref" in EPUB.
I'm referring to the scope of the article. Sometimes articles can get in the weeds, and the reader can forget what the focus is. The takeaway is "notes have a different behavior in EPUB than in print. They do the same job, but here is the difference."
I think this is the best approach. |
I fear retraining authors and publishers is way too big a job for this document
Understood, that is a perfect takeaway. |
Perhaps "retraining" was a poor choice of framing. I simply want to nudge their thinking of a note from a place in the view port, to the relationship between two pieces of content. In print, the 'footnote' is a spatial solution to a cognitive need—providing secondary info without turning the page. In a viewport, that same cognitive need is met by a 'note' that appears in context (pop-up) or at the end of the flow. We should teach users to think about the note's relationship to the text, rather than its traditional physical location. |
Right, and it should also have role="doc-noteref".
We should only be recommending the use of epub:type="footnote" plus role="doc-footnote". Although endnote won't be flagged by epubcheck, it's now deprecated for use.
Or whatever element contains the footnote, yes. Apple, for example, has different behaviours based on the element used. If you want the footnote to appear where it's placed in the markup, you use div or p. If you want it hidden, you use aside. |
|
@mattgarrish Thank you. And thank you for the Apple Documentation reference. Will the same best practices laid out in the Apple document apply to every reading system that supports EPUB:type="noteref"? |
I assume that's what this proposal has to work out. It's the difficulty of trying to create best practices after there are already implementations. Aren't the issues with footnotes mostly on the reading system side, though? There's a lot of inconsistency in how the pop-ups are created and what you can do with them as an author. The issue of whether the footnote is displayed by default or not is also an inconsistency in implementation, not authoring. |
Opening my umbrella, since what you have to say is always helpful.
Display inconsistency is an issue. I’m still early in my research and I see variations in the markup/code requested by RS. I hope to distill these down to the common elements in the next phase of the documentation. This might be a “which came first, the chicken or the egg?” situation. Are reading systems responding to a mix of HTML patterns by imposing overrides? Or are creators responding to implementation inconsistencies among reading systems? I’m willing to try outlining best practices on the creator side and see where it goes. |
I expect it's this. The basic authoring pattern for footnotes isn't complicated. You put a noteref semantic on the link and footnote semantic on the container. And then you cross your fingers. How the pop-up overlays are implemented differs between reading systems, so unless we get reading systems to all buy into one presentation method authors will still face rendering inconsistencies. The whole backlink ugliness came out of this because you couldn't know if you were going to click the note ref and get a pop-up and stay in page or end up transported off to where the note was authored and not be able to get back - or maybe you'd get to review the endnotes at the end of the section/book and have no way to find your way to where they are referenced. There have also been styling inconsistencies between reading systems because of the way that the pop-up overlays are implemented. Whether we can get consistent rendering across reading systems is going to influence the viability of any authoring patterns. |
|
This has been really helpful! I got a lot of good feedback on the outline and scope as well as more details. Next: I’ll do a rough draft in Google docs and share it for comments. Thanks @mattgarrish @rickj @GeorgeKerscher @dalerrogers |
|
The intent of the best practices document is to address frustration in the community about how best to make an ebook. Should I ask the CG if a best practices document is helpful even though we can’t guarantee results across all reading systems? |
|
For the point of view of an author / content creator, I can tell you that a best practices guide would be helpful. There is often a gap between theory and practice. Every web designer knows this. The EPUB community is going through its own version of the browser wars of the early 2000s. We want people to be successful with EPUB. Letting people know how it should work, with caveats, is a good thing, in my opinion. If you decide not to provide a free resource, maybe I'll just write a book. I think the need is there. |
Uh oh!
There was an error while loading. Please reload this page.
There is interest for “best practices” information for EPUB. See issue 2690. Several respondents to our HTML survey expressed a desire for clear instructions as well. Here is how we might structure this document. Once we have a pretty solid (75% right) outline, I will fill in the technical details and put that up for review.
Proposed Outline
Definitions
Types of Presentation in Reading Systems
Roles of Reading Systems and Authors
Accessibility Considerations
Sample Markup
Instructions for Setting Up Footnotes with Word Processor
Instructions for Setting Up Footnotes with HTML Editor
Disclaimers
Reading System support may change at anytime with no notice
Invitation to Comment on Github (?)
Does this look like a useful and accurate outline?
All reactions