Posted on Leave a comment

The Problem with H1

H1 and Content Boundaries on the Web and EBook Publications

There is a problem embedded in epub, which is that it is normally composed of several html documents, one per chapter. However, for parsers to create epubs properly (such as Pandoc), they do it based on H1, so that each H1 signifies the beginning (and title) of a new html document (which is a chapter).

However, as we know an HTML document itself (especially regarding the web) should only have one H1. Therefore if the native (single) document being edited is itself a book, then the single document will have multiple H1s embedded within it.

This means there is a basic disconnect of a book being an ODT file or HTML file or even a PDF vs. being an Ebook.

Baker & Taylor require epubs to have only one H1, which is itself the title of the work, and everything else H2 (e.g., chapter headers). However, the spec and common use has an H1 for each chapter.


The good news here is that once a piece of software has parsed the document and has a copy in memory, it's relatively trivial to change all the H1s to H2s, H2s to H3s (and back), so this won't be a problem to deal with, and in UX Write it won't be something the user has to do manually.

Using a single H1 for the book title only is stupid IMHO. That's what the title tag in HTML is for, or you can define a custom CSS class called "title". H1 as far as I'm concerned should be for chapters.

But again, this problem is easy to get around in software, and I could perhaps provide some options for EPUB export where you can specify how you want to handle things like this.

Pushing the problem from H1 to Meta Title gives the same problem: An epub ebook has multiple html documents (one per chapter). On the web, there should be one and only one H1 (for Google's purposes, and possibly in the HTML spec). The Meta Title is not (necessarily) displayed to the user (though browsers traditionally put it into the browser title bar as well), whereas the H1 does get displayed to the user, so these definitely have two different uses in terms of user/display.

The problem I see comes when people what to explicitly tag H1, H2, etc., and your application decides if/when it will do overrides. This is (partially) what I mean by having semantics (markup via markdown/copymarkup) be primary. By not having this and dealing with HTML export/native file format, you put all the control into your application, but take it away from the user and the documents.

Further, I believe that documents themselves should not be the top level, but collections of documents (libraries). This is what Scrivener allows for, where you can define which part of a document collection tree is the top level for an export/compilation.

What this allows for is people to have a single editor instance and navigate across multiple documents, books and book elements. This is very fast when wanting to bounce around between various documents. Granted it can slow down on load and save if the entire structure is written out, but that is not much of a problem in Scrivener.

This helps further define things such that a book is not a single document, but a collection of documents (the idea of "book" being a container). Not only does this work with epub thinking but also website thinking. A website is a collection of documents, but not a document itself (it is an address). Also, this idea helps out that each web page itself has an address, as well as meta title and h1. In essence this means that a web page is a chapter in a web site (book).

This means that epubs and websites are on the same page, as it were, whereas the pdf and odt is (or rather, can be) at odds insofar as a single instance can be a collection of chapters (and accompanying images, including usually a cover image).

Yes I've been having a look at the EPUB spec and realised this is something I'll have to deal with, particularly if I have support for opening existing EPUB files and editing them (as opposed to just exporting).

My understanding was that H1 was intended for top-level sections of a document, where "top-level section" can have different meanings depending on the type of document. For example in a book this would be chapter (or for a really large book, possibly even part), and for a smaller article this would be section. In LaTeX for example there is the book class and the article class; in the former you have \part{...} and \chapter{...} commands, and \section{...} and \subsection{...}. The article class only has the latter two.

So it becomes a matter of mapping what is in the file to the different levels of headings, and this could be different for different file formats (or variations thereof). For example when importing a LaTeX file, and it would look at what the document class is to determine whether H1 is chapter or part, and or whether H1 should be section instead.

Fortunately there are two things which work in our favour regarding this:

  1. The H* tags are semantic only; their appearance can be customised totally. So you could quite reasonably use H2 as the tag for chapters, but have the style name as displayed in the UI as "Chapter", with H3 displayed as "Section" and H1 as "Title". This way the user wouldn't have to think in terms of the HTML tag names but rather their meaning. Also the outline navigator could be configured to start at H2 instead of H1 in this case. So there's potential providing flexibility here as to how the different levels are presented in the UI vs. what specific tag names are used in the file.

  2. As I mentioned before, it's possible to "push up" or "pull down" the different heading tags by renumbering on load/save, if necessary. This is something which could be provided as an option to the user, or perhaps configured in a template/profile where you set up how you want your epub file structured (including single file vs. multiple files), depending on publisher's requirements.

To date, UX Write has been designed around the concept of working with everything within a single document. It's certainly capable of doing this in terms of performance, but with EPUB this throws a bit of a spanner in the works because some EPUB books use separate files. Also I've had a few people raise the desire to view individual sections by themselves, similar to what you have in Scrivener. So it might be worthwhile expanding this to allow you to work with multiple files that are all in the one "package", much like Scrivener does. For some types of writing you just want a single document, but for others (esp. books) you want multiple documents packaged together. So it would be good to support both approaches.

I'd be very keen to get your input on the UI for this, what sort of options should be provided, and how we could come up with something that gives the right level of control to authors about how their document is structured. And perhaps with the market research work we've discussed part of what you could do is present some UI mockups to various authors and get their input. What do you think?

Yes, I am interested in doing work in this area. It is a problem area I am working out myself as a "lead user".

For me the key is to work out problems in the areas mentioned that will not cause problems in other areas, or indeed that can help lead to solutions in those areas.

For example: self-publishers also have needs to have a website. Some of their content (usually a few chapters) are hosted on their website. Exporting the document to support markdown and/or html is fairly straightforward if the epub is taken as the model (one html page per chapter). Also, conceptually, the idea that a website is a book and a web page is a chapter does make some sense (though some web page "articles" are multi-page, that is usually for advertising revenue or attention-tracking or SEO rather than readability/usability).

Also, the ability to edit on the website and have those changes pushed back into the source documents (or some kind of synchronization) would be helpful (though not essential).

Another issue: when using Google Docs for collaboration with writers and editors, we always created one document per chapter for editing purposes. So this makes sense as well.

As far as I know, most content management for documents are collections of files, in some kind of nested folder structure. Most are too much trouble to deal with, other than making files available in the cloud for backup and sharing (Dropbox, etc.).

The Calibre ebook library software, which is tedious to use (essentially a searchable but single list as a collection, but using tags and authors for grouping purposes, kind of like another itunes) does have the advantage of being able to import multiple versions, create multiple versions, and transfer ebooks between a desktop and an ebook reader device.

Leave a Reply