Friday, April 6, 2012

Admonitions in Git-Scribe

‹prev | My Chain | next›

None of my books include admonition icons, which are the little icons next to NOTE / WARNING / IMPORTANT sections. I have never really given this too much thought, but this seems like it might be a nice touch. If nothing else, it might help to make these sections more obvious.

In the git-scribe source these are explicitly disabled:
    def do_pdf
      # ...
      strparams = {'callout.graphics' => 1,
                   'navig.graphics' => 1,
                   'admon.textlabel' => 1,
                   'admon.graphics' => 0,
                   'page.width' => '7.5in',
                   'page.height' => '9in'}
      # ...
    end
It seems a simple enough matter to turn them on with 'admon.graphics' => 1, but first, I will try a simple, command-line test case to verify that this works at all.

The other day, I figured out that the following will generate HTML for a single chapter in Dart for Hipsters:
a2x -f xhtml -v dom.asc
The admon.graphics option looks to be off by default because the result of that command is icon-less NOTEs:



The admin.graphics option needs to be sent to the xsltproc sub-command via --xsltproc-opts:
a2x -f xhtml -v --xsltproc-opts='--stringparam admon.graphics 1' dom.asc
With that, I have my icons:


So, I ought to be ready to try the option in git-scribe:
    def do_pdf
      # ...
      strparams = {'callout.graphics' => 1,
                   'navig.graphics' => 1,
                   'admon.textlabel' => 1,
                   'admon.graphics' => 1,
                   'page.width' => '7.5in',
                   'page.height' => '9in'}
      # ...
    end
But, when I run git-scribe gen pdf, I get lots of icon-not-found errors:
...
[ERROR] FONode - Image not found: images/icons/note.png
[ERROR] render - Image not found: images/icons/note.png
[ERROR] FONode - Image not found: images/icons/important.png
[ERROR] FONode - Image not found: images/icons/note.png
...
And, indeed, the FO document is refering to that path:
<fo:block>
  <fo:external-graphic
     width="auto"
     height="auto"
     content-width="36pt"
     src="url(images/icons/note.png)"/>
</fo:block>
To fix, I copy the image icons into the output directory along with the stylesheets and book content that is already copied when prepping the output directory:
    def prepare_output_dir(dir='output')
      FileUtils.mkdir_p(dir)
      FileUtils.cp_r "#{@wd}/book/.", dir, :remove_destination => true

      FileUtils.mkdir_p("#{dir}/stylesheets")
      FileUtils.cp_r File.join(SCRIBE_ROOT, 'stylesheets'), dir

      FileUtils.mkdir_p("#{dir}/images/icons")
      FileUtils.cp_r File.join(SCRIBE_ROOT, 'docbook-xsl/images/.'),
                     "#{dir}/images/icons"
    end
Now, when I git-scribe gen pdf, I get my icons:



Well, not quite my icons. It seems that the docbook icons included with git-scribe are not nearly as pretty as the AsciiDoc icons. So, I copy the AsciiDoc icons included in my normal Ubuntu install into git-scribe:
➜  git-scribe git:(master) ✗ mkdir icons
➜  git-scribe git:(master) ✗ cp -r /usr/share/xml/docbook/stylesheet/docbook-xsl/images/. icons 
Then I can update prepare_output_dir to copy these icons instead of the ones bundled in the docbook:
    def prepare_output_dir(dir='output')
      FileUtils.mkdir_p(dir)
      FileUtils.cp_r "#{@wd}/book/.", dir, :remove_destination => true

      FileUtils.mkdir_p("#{dir}/stylesheets")
      FileUtils.cp_r File.join(SCRIBE_ROOT, 'stylesheets'), dir

      FileUtils.mkdir_p("#{dir}/images/icons")
      FileUtils.cp_r File.join(SCRIBE_ROOT, 'icons'),
                     "#{dir}/images"
    end
With that, I have pretty icons in my PDF output:


I also add these images to the epub (and maybe the mobi) before calling it a night. Up tomorrow? Who knows?


Day #348

2 comments:

  1. It certainly looks nice - looks like your fork might be winning #ftw?

    ReplyDelete
    Replies
    1. Upstream has limited syntax highlighting, so it really depends on need. And really, if I were winning, I would better positioned to get pull requests sent back to the real project :-\

      Delete