oreillymedia / asciidoctor-htmlbook Goto Github PK

Please specify a copyright license for this project to make it clear under what conditions it can be (re)used. The Asciidoctor uses the MIT license, so it’d be great if you’ll use it too.

Right now, AsciiDoctor generates <p> elements within <div>s for admonitions (notes, tips, warnings) when Admonition Block markup is used. For example, this AsciiDoc:

[NOTE]
====
Here is a note
====

Generates the following HTML:

<div data-type="note">
<p>Here is a note</p>
</div>

But if instead of Admonition Block markup, you use this analogous Admonition Paragraph (see http://www.methods.co.nz/asciidoc/userguide.html#X28) markup:

NOTE: Here is a note

Or this analogous Admonition Paragraph markup:

[NOTE]
Here is a note

It converts without <p> elements:

<div data-type="note">Here is a note
</div>
</section

Would it be possible to change AsciiDoctor handling so that <p> elements are always added within admonitions in HTMLBook output, regardless of whether Admonition Block or Admonition Paragraph markup is used? This would be valuable as having AsciiDoctor consistently generate <p> elements with admonition <div>s would make it easier to style the HTML with CSS.

Hello,

We had an RT ticket come in about this, so I did some testing and found that height and scale attributes are getting dropped during conversion, but width attributes are being conserved. Here's my test, htmlbook generated on Atlas:

The asciidoc markup:

[[some_id]]
.has a width attribute
image::images/bitaddress.png[width="2in"]

[[some_id2]]
.has a height attribute
image::images/bitaddress.png[height="2in"]

[[some_id3]]
.has a scale attribute
image::images/bitaddress.png[scale="2"]

The htmlbook markup:

<figure id="some_id">
<img src="images/bitaddress.png" alt="bitaddress" width="2in"/>
<figcaption>has a width attribute</figcaption>
</figure>

<figure id="some_id2">
<img src="images/bitaddress.png" alt="bitaddress"/>
<figcaption>has a height attribute</figcaption>
</figure>

<figure id="some_id3">
<img src="images/bitaddress.png" alt="bitaddress"/>
<figcaption>has a scale attribute</figcaption>
</figure>

Let me know if I can provide any other info.

Thanks,
Chris

Preface contribution (and probably chapter contribution) needs handling.

The asciidoc markup would be something like:
[au="Author", auaffil="And a Job Title etc"]

For your convenience: http://chimera.labs.oreilly.com/books/1230000000065/ch04.html#_chapter_contributors

Hi @sarahs,

I think there's a bug in the inline image template; see this line:

https://github.com/oreillymedia/asciidoctor-htmlbook/blob/master/htmlbook/inline_image.html.erb#L1

The end quote for the alt attribute is misplaced; it comes at the very end of the entire img tag. I believe this markup:

<img src="<%= image_uri(@target) %>" alt="<%= attr 'alt' %><%= attr?('width') ? %( width="#{attr 'width'}") : nil %><%= attr?('height') ? %( height="#{attr 'height'}") : nil %><%= attr?('role') ? %( #{attr 'role'}) : nil %>"/>

Should instead be this:

<img src="<%= image_uri(@target) %>" alt="<%= attr 'alt' %>"<%= attr?('width') ? %( width="#{attr 'width'}") : nil %><%= attr?('height') ? %( height="#{attr 'height'}") : nil %><%= attr?('role') ? %( #{attr 'role'}) : nil %>/>

Could you take a look?

Thanks,
Sanders

If no gent ext is specified in AsciiDoc for an XREF, can we leave the text nodes of HTMLBook XREF elements empty when converting to HTMLBook. In other words, can we convert this:

See <<the_id>>

to:

See <a data-type="xref" href="#the_id"/>

Instead of what we're doing now, which appears to be:

See <a data-type="xref" href="#the_id">[#the_id]</a>

Downstream, the HTMLBook XSL stylesheets will handle adding the appropriate gentext if an XREF has no text node, so I think it makes most sense to defer to having it handled there, so we can avoid replicating existing functionality.

If AsciiDoc XREFs do have gentext specified, we should preserve that, though. For example, if you've got:

See <<the_id, Awesome Chapter>>

It should be converted to:

See <a data-type="xref" href="#the_id">Awesome Chapter</a>

Let me know if you have any questions about this.

Thanks,
Sanders

To work around bug in Atlas UI where switching from Code->Visual editor drops self-closing tags. Default should continue to be:

<a data-type="xref" href="#paintpot_app"></a>

But param would enable:

<a data-type="xref" href="#paintpot_app">#paintpot_app</a>

Is it possible to configure our AsciiDoctor templates to not do any inline markup processing on id references in XREFs, and just treat them literally.

In other words, can we ensure the following:

In <<Strings__Text__and_Blobs>>

Is converted to:

<a data-type="xref" href="#Strings__Text__and_Blobs">

Instead of:

See <<the_id, Chapter 10>> for more info

Hello,

The 'numbered' attribute in code listings is causing trouble.

The asciidoc markup:

[[vagrantfile_minimal]]
.Minimal configuration for Vagrant

====
[source,ruby,numbered]
----
Vagrant.configure(2) do |config|
  config.vm.box = "data-science-toolbox/data-science-at-the-command-line"
end
----
====

The (invalid) htmlbook markup:

<pre data-type="programlisting" data-code-language="ruby"><table class="pyhltable"><tr><td class="linenos"><div class="linenodiv">1
2
3</div></td><td class="code"><span class="tok-no">Vagrant</span><span class="tok-o">.</span><span class="tok-n">configure</span><span class="tok-p">(</span><span class="tok-mi">2</span><span class="tok-p">)</span> <span class="tok-k">do</span> <span class="tok-o">|</span><span class="tok-n">config</span><span class="tok-o">|</span>
  <span class="tok-n">config</span><span class="tok-o">.</span><span class="tok-n">vm</span><span class="tok-o">.</span><span class="tok-n">box</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;data-science-toolbox/data-science-at-the-command-line&quot;</span>
<span class="tok-k">end</span>
</td></tr></table></pre>
</div>

-Chris

I think we may need to double-check handling for dedications? I had this in the AsciiDoc source:

[dedication]
== Dedication

Dedication text here

And it got converted to the following in HTMLBook:

<section data-type="chapter" id="_dedication">
<h1>Dedication</h1>


<p>Dedication text here</p>
</section>

There should be a data-type="dedication" on the above <section>.

When I try to run to convert an AsciiDoc file in my folder (dubliners, in case):

ruby scripts/convert_book.rb dubliners

I run into the following error:

Failed to parse source, uninitialized constant Tilt (NameError)

in the context of the full error message:

/usr/local/lib/ruby/gems/2.2.0/gems/asciidoctor-1.5.2/lib/asciidoctor.rb:1362:in `rescue in load': asciidoctor: FAILED: <stdin>: Failed to parse source, uninitialized constant Tilt (NameError)
    from /usr/local/lib/ruby/gems/2.2.0/gems/asciidoctor-1.5.2/lib/asciidoctor.rb:1281:in `load'
    from /usr/local/lib/ruby/gems/2.2.0/gems/asciidoctor-1.5.2/lib/asciidoctor.rb:1458:in `convert'
    from scripts/convert_book.rb:12:in `block in <main>'
    from scripts/convert_book.rb:9:in `glob'
    from scripts/convert_book.rb:9:in `<main>'

I'm running

ruby 2.2.0p0 (2014-12-25 revision 49005) [x86_64-darwin13]

on OS X 10.9.5

with the following gems:

asciidoctor (1.5.2)
bigdecimal (1.2.7, 1.2.6)
bundler (1.9.3)
diff-lcs (1.2.4)
faraday (0.9.1)
highline (1.7.1, 1.6.21)
io-console (0.4.3)
json (1.8.2, 1.8.1)
librarian (0.1.2)
librarian-ansible (1.0.6)
mini_portile (0.6.2)
minitest (5.5.1, 5.4.3)
multipart-post (2.0.0)
nokogiri (1.5.10)
power_assert (0.2.3, 0.2.2)
psych (2.0.13, 2.0.8)
rake (10.4.2)
rdoc (4.2.0)
rspec (2.14.1)
rspec-core (2.14.6)
rspec-expectations (2.14.3)
rspec-mocks (2.14.3)
test-unit (3.0.9, 3.0.8)
thor (0.19.1)
thread_safe (0.3.5)
tilt (2.0.1, 1.4.1)

I get the same problem regardless what AsciiDoc file I have in dubliners.

I'm a newbie rubyist, so I might be simply making a rookie error. Please advise. Thanks in advance.

Hello,

In the case where more than one file has a section name "Summary" or something of the like (with no formal ID declared), this results in htmlbook files with duplicate section ids that need to be manually changed.

-Chris

Hello,

The glossary markup after an asciidoc to htmlbook conversion is the following:

<section data-type="chapter" id="glossary">

The htmlbook spec says it should be this:

<section data-type="glossary">

Right now, HTMLBook backends don't support markup like the following, which contains a repeated callout ref:

---
print "Hello World" <1>
print "Hello World Again" <2>
print "Hello World" <1>

---

<1> Standard print statement
<2> Redundant

Adding support for the above is pretty easy if we drop support for link bidirectionality for callout markers (which doesn't work anyway if there's not a 1-to-1 correspondence between markers in listings and markers in callouts below) and just have the callout markers in the listing link to the callout entries below the listing.

Conversion drops colophon heading markup, resulting in a file with just <p>s

We've had a report from an Atlas user that document attributes and macros are not working in v2. We should test these two features and see if we can reproduce, and fix if needed.

@rdhyee and I are building ebooks from asciidoc sources. HTMLBook spec says to use <ol> but the default outline function outputs <ul>. @rdhyee patched this by overriding the outline ruby method.

In this issue from asciidoctor @mojavelinux suggests a better way of calling outline and shows how the <ul> behavior of asciidoc can be overridden.

Right now it looks like comments in AsciiDoc:

// This is an AsciiDoc comment

Are dropped as part of the conversion to HTMLBook. Possible to preserve them as XML comments. In other words, can we convert the above to:

<!-- This is an AsciiDoc comment -->

Do you have a plan to release asciidoctor-htmlbook as a ruby gem? So that people can install via gem and use in command line.

And what's the License for this repo?

In the README.md, there is the line:

htmlbook-autogen - a set of templates that can only be used with the orm_asciidoctor gem. This provides some autogeneration abilities.

Is the reference to orm_asciidoctor out-of-date? I can't find such a gem.