Invalid epub:type being rendered

[jxramos]

Combing through some more ePub validation issues with the 2.2.20 release I'm finding these various renderings of the epub:type attribute that appears to be following some default fallback rule that injects the class id also into the type attribute which is invalid according to the standard. There's a handful of valid choices to choose from with the EPUB 3 Structural Semantics Vocabulary, although I'm not entirely sure which one was intended or how to get asciidoc to define this information.

File	Line	Position	Message	Source
OEBPS/document-30415480.xhtml	70	60	Undefined property: 'sect2'.	<section class="sect2" title="git clone" epub:type="sect2">
OEBPS/document-30415480.xhtml	119	61	Undefined property: 'sect2'.	<section class="sect2" title="git commit" epub:type="sect2">
OEBPS/document-30415480.xhtml	195	58	Undefined property: 'sect2'.	<section class="sect2" title="git log" epub:type="sect2">
OEBPS/document-30415480.xhtml	415	59	Undefined property: 'sect2'.	<section class="sect2" title="git fsck" epub:type="sect2">
OEBPS/document-30415480.xhtml	420	61	Undefined property: 'sect2'.	<section class="sect2" title="git reflog" epub:type="sect2">
OEBPS/document-30815420.xhtml	47	58	Undefined property: 'sect1'.	<section class="sect1" title="Libgit2" epub:type="sect1">
OEBPS/document-30815420.xhtml	156	73	Undefined property: 'sect2'.	<section class="sect2" title="Advanced Functionality" epub:type="sect2">
OEBPS/document-30815420.xhtml	366	60	Undefined property: 'sect2'.	<section class="sect2" title="Porcelain" epub:type="sect2">
OEBPS/document-30951860.xhtml	44	67	Undefined property: 'sect2'.	<section class="sect2" title="gitk and git-gui" epub:type="sect2">
OEBPS/document-30951860.xhtml	92	77	Undefined property: 'sect2'.	<section class="sect2" title="GitHub for Mac and Windows" epub:type="sect2">
OEBPS/document-30951860.xhtml	135	63	Undefined property: 'sect3'.	<section class="sect3" title="Installation" epub:type="sect3">
OEBPS/document-30951860.xhtml	185	58	Undefined property: 'sect3'.	<section class="sect3" title="Summary" epub:type="sect3">
OEBPS/document-30951860.xhtml	240	62	Undefined property: 'sect1'.	<section class="sect1" title="Git in Bash" epub:type="sect1">

[jxramos]

Taking the first example, I believe this may not be a problem with the asc file but rather a possible bug in the asciidoc rendering...

If you look at the rendered xhtml...

<section class="sect2" title="git clone" epub:type="sect2">
<h3 id="_git_clone">git clone</h3>
<p>The <code class="literal">git clone</code> command is actually something of a wrapper around several other commands.
It creates a new directory, goes into it and runs <code class="literal">git init</code> to make it an empty Git repository, adds a remote (<code class="literal">git remote add</code>) to the URL that you pass it (by default named <code class="literal">origin</code>), runs a <code class="literal">git fetch</code> from that remote repository and then checks out the latest commit into your working directory with <code class="literal">git checkout</code>.</p>
<p>The <code class="literal">git clone</code> command is used in dozens of places throughout the book, but we&#8217;ll just list a few interesting places.</p>
<p>It&#8217;s basically introduced and explained in <a id="xref-_git_basics_chapter#_git_cloning" href="_git_basics_chapter.epub#_git_cloning" class="xref">[_git_basics_chapter#_git_cloning]</a>, where we go through a few examples.</p>
<p>In <a id="xref-_git_on_the_server#_getting_git_on_a_server" href="_git_on_the_server.epub#_getting_git_on_a_server" class="xref">[_git_on_the_server#_getting_git_on_a_server]</a> we look at using the <code class="literal">--bare</code> option to create a copy of a Git repository with no working directory.</p>
<p>In <a id="xref-_git_tools#_bundling" href="_git_tools.epub#_bundling" class="xref">[_git_tools#_bundling]</a> we use it to unbundle a bundled Git repository.</p>
<p>Finally, in <a id="xref-_git_tools#_cloning_submodules" href="_git_tools.epub#_cloning_submodules" class="xref">[_git_tools#_cloning_submodules]</a> we learn the <code class="literal">--recurse-submodules</code> option to make cloning a repository with submodules a little simpler.</p>
<p>Though it&#8217;s used in many other places through the book, these are the ones that are somewhat unique or where it is used in ways that are a little different.</p>
</section>
<section class="sect2" title="git clone" epub:type="sect2">
<h3 id="_git_clone">git clone</h3>
<p>The <code class="literal">git clone</code> command is actually something of a wrapper around several other commands.
It creates a new directory, goes into it and runs <code class="literal">git init</code> to make it an empty Git repository, adds a remote (<code class="literal">git remote add</code>) to the URL that you pass it (by default named <code class="literal">origin</code>), runs a <code class="literal">git fetch</code> from that remote repository and then checks out the latest commit into your working directory with <code class="literal">git checkout</code>.</p>
<p>The <code class="literal">git clone</code> command is used in dozens of places throughout the book, but we&#8217;ll just list a few interesting places.</p>
<p>It&#8217;s basically introduced and explained in <a id="xref-_git_basics_chapter#_git_cloning" href="_git_basics_chapter.epub#_git_cloning" class="xref">[_git_basics_chapter#_git_cloning]</a>, where we go through a few examples.</p>
<p>In <a id="xref-_git_on_the_server#_getting_git_on_a_server" href="_git_on_the_server.epub#_getting_git_on_a_server" class="xref">[_git_on_the_server#_getting_git_on_a_server]</a> we look at using the <code class="literal">--bare</code> option to create a copy of a Git repository with no working directory.</p>
<p>In <a id="xref-_git_tools#_bundling" href="_git_tools.epub#_bundling" class="xref">[_git_tools#_bundling]</a> we use it to unbundle a bundled Git repository.</p>
<p>Finally, in <a id="xref-_git_tools#_cloning_submodules" href="_git_tools.epub#_cloning_submodules" class="xref">[_git_tools#_cloning_submodules]</a> we learn the <code class="literal">--recurse-submodules</code> option to make cloning a repository with submodules a little simpler.</p>
<p>Though it&#8217;s used in many other places through the book, these are the ones that are somewhat unique or where it is used in ways that are a little different.</p>
</section>

and the corresponding asc source, nothing really stands out with respect to defining any epub:type attribute.

==== git clone

The `git clone` command is actually something of a wrapper around several other commands.
It creates a new directory, goes into it and runs `git init` to make it an empty Git repository, adds a remote (`git remote add`) to the URL that you pass it (by default named `origin`), runs a `git fetch` from that remote repository and then checks out the latest commit into your working directory with `git checkout`.

The `git clone` command is used in dozens of places throughout the book, but we'll just list a few interesting places.

It's basically introduced and explained in <<_git_basics_chapter#_git_cloning>>, where we go through a few examples.

In <<_git_on_the_server#_getting_git_on_a_server>> we look at using the `--bare` option to create a copy of a Git repository with no working directory.

In <<_git_tools#_bundling>> we use it to unbundle a bundled Git repository.

Finally, in <<_git_tools#_cloning_submodules>> we learn the `--recurse-submodules` option to make cloning a repository with submodules a little simpler.

Though it's used in many other places through the book, these are the ones that are somewhat unique or where it is used in ways that are a little different.

I did a cursory look into the asciidoc documentation and found this seemingly relevant section...
http://asciidoc.org/userguide.html#_sections

8.4.1. Section markup templates
Section markup templates specify output markup and are defined in AsciiDoc configuration files. Section markup template names are derived as follows (in order of precedence):

From the title’s first positional attribute or template attribute. For example, the following three section titles are functionally equivalent:

[[terms]]
[glossary]
List of Terms
-------------

["glossary",id="terms"]
List of Terms
-------------

[template="glossary",id="terms"]
List of Terms
-------------
When the title text matches a configuration file [specialsections] entry.

If neither of the above the default sect<level> template is used (where <level> is a number from 1 to 4).

In addition to the normal section template names (sect1, sect2, sect3, sect4) AsciiDoc has the following templates for frontmatter, backmatter and other special sections: abstract, preface, colophon, dedication, glossary, bibliography, synopsis, appendix, index. These special section templates generate the corresponding Docbook elements; for HTML outputs they default to the sect1 section template.

So maybe this can be managed by defining these sections in the configuration file they reference in the documentation?

[jnavila]

Before going further in the investigation, have you tried the latest revision in master from asciidoctor-epub3? Some large fixes have been done and the book compiles correctly with these fixes.

You'll also need to update the Gemfile in the repo mine has:

source 'https://rubygems.org'

gem 'rake'
gem 'asciidoctor', '1.5.6.1'

gem 'json'
gem 'awesome_print'

gem 'asciidoctor-epub3', '1.5.0.alpha.8.dev'
gem 'asciidoctor-pdf', '1.5.0.alpha.16'

gem 'coderay'
gem 'pygments.rb'
gem 'thread_safe'
gem 'epubcheck'
gem 'kindlegen'

As you can see the version for asciidoctor-epub3 is a dev version i.e. a tag from a local copy of the asciidoctor-epub3 repo. This can be updated with bundle install. With these changes, epubcheck passes with no errors.

[jxramos]

Nice, I could very well be out of sync with an old deployment, I had evaluated the 2.1.20 deployment at
https://github.com/progit/progit2/releases/download/2.1.20/progit.epub

And the current master gem file is definitely out of spec with yours

I tried to follow some of the recent PRs but didn't see anything addressing these maters beyond the last relevant one at #932.

When are all these fixes targeted for release?

[jnavila]

I'm in touch with the main developer of asciidoctor. A new alpha release should hit the gem repos soon (hopefully). After that, I'll push an updated Gemfile here to level the build system.

[deoren]

@jxramos @jnavila I had issues uploading the 2.1.20 version of the epub to Google Play Books (GPB) and eventually landed here. Thanks to your notes, this is how I changed my Gemfile to build an epub that passes http://validator.idpf.org checks and successfully uploads to GPB without issue:

ubuntu@ubuntu-1604-virtual-machine:~/Desktop/progit2$ git diff
diff --git a/Gemfile b/Gemfile
index d7bd912..4ecffb4 100644
--- a/Gemfile
+++ b/Gemfile
@@ -1,13 +1,13 @@
 source 'https://rubygems.org'
 
 gem 'rake'
-gem 'asciidoctor', '1.5.0'
+gem 'asciidoctor', '1.5.6.1'
 
 gem 'json'
 gem 'awesome_print'
 
-gem 'asciidoctor-epub3', '1.0.0.alpha.2'
-gem 'asciidoctor-pdf', '1.5.0.alpha.5'
+gem 'asciidoctor-epub3', :git => 'https://github.com/asciidoctor/asciidoctor-epub3'
+gem 'asciidoctor-pdf', '1.5.0.alpha.16'
 
 gem 'coderay'
 gem 'pygments.rb'

There is probably a better way, but I wanted to share in case this was helpful for anyone else that lands here.

[jnavila]

Has all of this been fixed? Can we close?

[deoren]

Ditto here: Acknowledging your question, but deferring to the OP (responding just in case you were including me in the question).

[jxramos]

Yes indeed, looks like she's a real winner in the validation and Google Play Books spaces...
https://github.com/progit/progit2/releases/tag/2.1.35