WebBook format

[MurakamiShinyu]

I'm thinking we can adopt WebBook Level 1 (Unofficial Proposal Draft by Daniel Glazman) as our web book format. It can be compatible with EPUB3 and the expanded (unzipped) contents can be viewed as normal web pages from the top index.html (or index.xhtml) page. Also it can be viewed with Vivliostyle.

The GitHub repository of WebBook: https://github.com/therealglazou/webbook

There is an EPUB-compatible WebBook sample: https://github.com/therealglazou/webbook/blob/master/samples/moby-dick-WebBook-AND-epub301.epub

The expanded (unzipped) version of the sample is not found there, so I made a fork of the repository and put expanded samples in the sample-expanded branch:

https://github.com/MurakamiShinyu/webbook/tree/samples-expanded/samples/expanded/moby-dick-WebBook-AND-epub301

Also, I set it as GitHub Pages: https://murakamishinyu.github.io/webbook/samples/expanded/moby-dick-WebBook-AND-epub301/
(= https://murakamishinyu.github.io/webbook/samples/expanded/moby-dick-WebBook-AND-epub301/index.xhtml )

This can be viewed with Vivliostyle: https://vivliostyle.org/viewer/#src=https://murakamishinyu.github.io/webbook/samples/expanded/moby-dick-WebBook-AND-epub301/&bookMode=true&renderAllPages=false

(Note: &renderAllPages=false is specified for quick loading)

This is same as (with index.xhtml): https://vivliostyle.org/viewer/#src=https://murakamishinyu.github.io/webbook/samples/expanded/moby-dick-WebBook-AND-epub301/index.xhtml&bookMode=true&renderAllPages=false

Also, the EPUB .opf file package.opf can be specified: https://vivliostyle.org/viewer/#src=https://murakamishinyu.github.io/webbook/samples/expanded/moby-dick-WebBook-AND-epub301/OPS/package.opf&bookMode=true&renderAllPages=false

In this way, it starts with the cover page. The reading order is as listed in the spine in the OPF.

In this sample, no stylesheets for paged media (of for Vivliostyle) are specified, but we can add such stylesheets with print or vivliostyle media types, and can make the page layout for PDF.

(Note: Vivliostyle supports print media type (@media print, or <link> with media="print", and also vivliostyle media type (@media vivliostyle) for specifying Vivliostyle specific non-standard CSS features)

[mrchristian]

Hi Shinyu,

This is all very exciting. I love the idea and what is also interesting is that maybe we can keep with the integrity of the Webbook format, i.e., a complete package of content for the book, but also use this same package to not only generate a Vivlio rendering, but also maybe a website rendering. If the website rending is not possible then at least serving as a single source that can be reprocessed as a website.

Apologies for taking so long to get back, had a lot to do and took some time to understand what the webbook does.

Also, the EPUB .opf file package.opf can be specified: https://vivliostyle.org/viewer/#src=https://murakamishinyu.github.io/webbook/samples/expanded/moby-dick-WebBook-AND-epub301/OPS/package.opf&bookMode=true&renderAllPages=false

In this way, it starts with the cover page. The reading order is as listed in the spine in the OPF.

Great this picking up of the .OPF

In this sample, no stylesheets for paged media (of for Vivliostyle) are specified, but we can add such stylesheets with print or vivliostyle media types, and can make the page layout for PDF.

(Note: Vivliostyle supports print media type (@media print, or <link> with media="print", and also vivliostyle media type (@media vivliostyle) for specifying Vivliostyle specific non-standard CSS features)

@rqpe - This is a note for you Raquel about how to organise the styles.

Questions about the Webbook

Referring to the Webbook specs: Abstract and Requirements http://glazman.org/e0/webbook.html#intro

1. What I don't understand is how will the browser read the .wbook or .epub compatible ZIP archive file?
2. To make a presentable WebBook, besides following the webbook specs my understanding is that the only additional dependency would be to style with CSS?
3. I assume your pointing to WebBook is as a packaging methodology for a web book compatible with Vivliostyle. If in addition I wanted to use this to generate a website like our Hugo or Jekyll sites, but maybe with less or no framework overhead, what do you think would be a good option for this? @djavco

Thank you.

I'm going to think more about this

All best

Simon

[MurakamiShinyu]

@mrchristian:

1. What I don't understand is how will the browser read the .wbook or .epub compatible ZIP archive file?

I understand that the zip archive file format .wbook or .epub is not for reading with web browser directly (without a web app or extension), and we should place non-zipped contents on Web. The 2nd item of Requirements seems to imply that: "2. the contents of a WebBook instance can be placed inside a Web site’s directory and are directly readable by a Web browser using the URL for that directory".

It seems the description "A WebBook instance is a [ZIP] container.…" in WebBook instances is for packaged (zipped) WebBook instance. I think there will be use cases of both packaged and non-packaged WebBook.

The WebBook spec was proposed as an alternative to Web Publications and its packaged format Packaged Web Publications. The main differences between WebBook and Web Publications are that WebBook does not use manifest file such as Publication Manifest and can be compatible with EPUB3. (Note: W3C stopped standardizing Web Publications last year. See the "Status of This Document" section. WebBook was made as a unofficial proposal draft a year and a half earlier.)

2. To make a presentable WebBook, besides following the webbook specs my understanding is that the only additional dependency would be to style with CSS?

I thinks so.

3. I assume your pointing to WebBook is as a packaging methodology for a web book compatible with Vivliostyle. If in addition I wanted to use this to generate a website like our Hugo or Jekyll sites, but maybe with less or no framework overhead, what do you think would be a good option for this?

Yes, using WebBook as a website will be a good option.

[mrchristian]

I'll read the webbook standard in more detail to understand how the format can be used to make a website where the following can be added; menu, navigation, headers, footers, and maybe other features as option in the way that openbookpublishers do with their EPUB to website renderer https://github.com/OpenBookPublishers/epublius

I am still trying to clarify how the reading order and navigation menu are formatted with webbook. But this involves me needing to the spec in more detail.

I'm still trying to understand if webbook used doc-nav or OPF manifest. http://glazman.org/e0/webbook.html#navigation-document-navdata

I am focused on the manifest issue because of multi-format output concerns when we want to have different reading orders in different formats, i.e., ebook we out frontmatter at the rear, and in print-on-demand PDF we want frontmatter at the front, OR in some formats we don't want to include items in some outputs, or have them excluded from navigation. But these non-default manifest options I think are out of scope for the webbook as an output format.

But just to say I'm really grateful to be made aware of technical ways to deal with questions I have been coming up against.

Great that we can consider the webbook as a website building format.

[mrchristian]

I would say to should adopt using the webbook format for packaging as some sort of standalone standardised approach is needed and it looks pretty interoperable so no long term lockin problems. It can be something we at least use and explore the concepts it is advocating.

[MurakamiShinyu]

I'll read the webbook standard in more detail to understand how the format can be used to make a website where the following can be added; menu, navigation, headers, footers, and maybe other features as option in the way that openbookpublishers do with their EPUB to website renderer https://github.com/OpenBookPublishers/epublius

I didn't know Epublius, I'll see it. Maybe such website renderer is useful to make a decent website with webbook. However since the WebBook format is based on very standard website structure, i.e., the "index.html" is the primary entry page that contains navigation menu with links to other web pages inside the website, probably, adding a small JavaScript code for making sidebar menu etc. will work, just like the WebBook spec itself (same as W3C CSS specs) having Pop Out Sidebar generated from the TOC by a JavaScript code.

I'm still trying to understand if webbook used doc-nav or OPF manifest.

For WebBook, the OPF is necessary only to make a EPUB3-compatible WebBook.

Currently Vivliostyle does not fully conform to the WebBook spec. The spec says "Except in documents with no navigation data or an empty one, the navigation document is not included in the reading order by default, and WebBook-capable User Agents would skip it when displaying the book from the start." but Vivliostyle does not skip the navigation document.

If Vivliostyle conforms to this spec, https://vivliostyle.org/viewer/#src=https://murakamishinyu.github.io/webbook/samples/expanded/moby-dick-WebBook-AND-epub301/index.xhtml&bookMode=true and https://vivliostyle.org/viewer/#src=https://murakamishinyu.github.io/webbook/samples/expanded/moby-dick-WebBook-AND-epub301/OPS/package.opf&bookMode=true will have same result (starting with the cover page).

But these non-default manifest options I think are out of scope for the webbook as an output format.

Indeed. The WebBook Level 1 was proposed as a simpler alternative to Web Publications that requires JSON-LD based Publication Manifest. However I think Publication Manifest is still useful and can coexist with WebBook. Vivliostyle supports Publication Manifest, too (see https://github.com/vivliostyle/vivliostyle.js/pull/511).

When a manifest file (e.g., manifest.jsonld) is specified to Vivliostyle, Vivliostyle renders pages using Reading Order in the manifest, same as OPF case. Also, if "index.html" (or .xhtml) file has a link to the manifest file, (e.g., <link href="manifest.jsonld" rel="publication"/>), Vivliostyle uses the manifest.

Multiple reading order is possible with multiple manifest files (or EPUB OPF and manifest.jsonld file).

[MurakamiShinyu]

for the publication manifest file name, "publication.json" may be better. I found a related topic in a W3C spec discussion:

"Renamed the required manifest.jsonld to publication.json https://github.com/w3c/pwpub/issues/43

RESOLVED: go with publication.json

and the related W3C note: Lightweight Packaging Format (LPF) W3C Working Group Note 19 March 2020 https://www.w3.org/TR/lpf/

(it seems the LPF and the "WebBook Level 1" packaged .wbook have same purpose. The difference is with/without using JSON manifest).

[mrchristian]

this looks really powerful, great stuff.

Would it mean we follow this spec? https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#manifest.json

This would help solve other wider questions we have about including translations and potentially dealing with file structures for revisions, dictionaries, metadata assets and the like

[MurakamiShinyu]

Would it mean we follow this spec? https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#manifest.json

This "manifest.json" on "Mozilla > Add-ons > Browser Extensions > Anatomy of an extension" seems to be for Mozilla Browser Extensions and not relevant to the publication manifest. The file name "manifest.json" may be used for many different manifest specs, so using "publication.json" will be better for the publication manifest to avoid confusion. (and "manifest.webmanifest" for Web App Manifest)

[mrchristian]

Yes, sorry I realised after sending that I had picked up the wrong link. So for the webbook we would use something based on Publication Manifest W3C Proposed Recommendation 01 October 2020 https://www.w3.org/TR/pub-manifest/ and call it publication.jsonld - The LD part is also good as in my Open Science circles LD is an important part of our datascape

[MurakamiShinyu]

Yes, I think we should adopt the W3C spec Publication Manifest. On "publication.json" vs "publication.jsonld", I prefer "publication.json" with same reason as the decision in W3C quoted in https://github.com/Health-Sprints/obp/issues/3#issuecomment-711144968.