paru 0.2.4.3 → 0.2.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c1b0bdd09190def2f416be363cec8c5dc2e51106
-  data.tar.gz: fb2184d30afb43207c81ce1a681b39a58dea2343
+  metadata.gz: 49f91b95228c398d4ed7e752c9780d4a56bdb128
+  data.tar.gz: 6096c105a736e686a02e2fc16f1d1985c55dfb05
 SHA512:
-  metadata.gz: 006cfa8e6e18ad4ee4596c27e23bac083a8afa820e0e31744632417f1e2d9beae70047623b8db4a01b64ad28823e746cc4c8b9fbd10ad6c9326dd9b731c15224
-  data.tar.gz: ee5d944ce20ba48171b51f6700587c7cb264f0c7a8ea807fcc51002e642980a6823b30dbb5c652fa9051cbfb74fa1d68fabcbd51d0811147d62c1cf9558753c0
+  metadata.gz: 5cf262bca810cbae0f4dffae889de6cc4d53fcc466cc6ea3ad342484aef86a54878933cca5e120fac569b6938d92e5d1c14627f412546349b8bae898a282f77f
+  data.tar.gz: a79687986c7709c5489efdb59bca496669d3ae1dd7b31397e64a9b5092d1f3b55a673c41463e68e400814066e49483c1db74243775e802affc85a4ffbaea9154

data/bin/do-pandoc.rb

@@ -51,6 +51,11 @@ if metadata.has_key? "pandoc" then
     pandoc = Paru::Pandoc.new
     to_stdout = true
     metadata["pandoc"].each do |option, value|
+      if value.is_a? String then
+          value = value.gsub '\\', ''
+      elsif value.is_a? Array then
+          value = value.map {|v| v.gsub '\\', '' if v.is_a? String}
+      end
       pandoc.send option, value
       to_stdout = false if option == "output"
     end

data/lib/paru.rb

@@ -20,4 +20,7 @@ module Paru
     require "paru/pandoc"
     require "paru/error"
     require "paru/filter"
+
+    # Paru's current version
+    VERSION = [0, 2, 4, 4]
 end

data/lib/paru/filter.rb

@@ -70,24 +70,132 @@ module Paru
 
 
     # Filter is used to write your own pandoc filter in Ruby. A Filter is
-    # almost always created and immediately executed via the +run+ method as
-    # shown in the following examples:
-    #
-    # @example Identity filter
-    #     Paru::Filter.run do
-    #         # nothing
-    #     end
-    #
-    # @example Remove horizontal lines
-    #     Paru::Filter.run do
-    #       with "HorizontalRule" do |rule|
-    #           if rule.has_parent? then
-    #               rule.parent.delete rule
-    #           else
-    #               rule.outer_markdown = ""
-    #           end
-    #       end
-    #     end
+    # almost always created and immediately executed via the +run+ method. The
+    # most simple filter you can write in paru is the so-called "identity":
+    #
+    # {include:file:examples/filters/identity.rb}
+    #
+    # It runs the filter, but it makes no selection nor performs an action.
+    # This is pretty useless, of course—although it makes for a great way to
+    # test the filter functionality—, but it shows the general setup of a
+    # filter well.
+    #
+    # = Writing a simple filter: numbering figures
+    #
+    # Inside a {Filter#run} block, you specify *selectors* with *actions*. For
+    # example, to number all figures in a document and prefix their captions
+    # with "Figure", the following filter would work:
+    #
+    # {include:file:examples/filters/number_figures.rb}
+    #
+    # This filter selects all {PandocFilter::Image} nodes. For each
+    # {PandocFilter::Image} node it increments the figure counter
+    # +figure_counter+ and then sets the figure's caption to "Figure" followed
+    # by the figure count and the original caption.  In other words, the
+    # following input document
+    #
+    #     ![My first image](img/horse.png)
+    #
+    #     ![My second image](img/rabbit.jpeg)
+    #
+    # will be transformed into
+    #
+    #     ![Figure 1. My first image](img/horse.png)
+    #
+    #     ![Figure 2. My second image](img/rabbit.jpeg)
+    #
+    # The method {PandocFilter::Node#inner_markdown} and its counterpart
+    # {PandocFilter::Node#outer_markdown} are a great way to manipulate the
+    # contents of a selected {PandocFilter::Node}. No messing about creating
+    # and filling {PandocFilter::Node}s, you can just use pandoc's own
+    # markdown format!
+    #
+    # = Writing a more involved filters
+    #
+    # == Using the "follows" selector: Numbering figures and chapters
+    #
+    # The previous example can be extended to also number chapters and to
+    # start numbering figures anew per chapter. As you would expect, we need
+    # two counters, one for the figures and one for the chapters:
+    #
+    # {include:file:examples/filters/number_figures_per_chapter.rb}
+    #
+    # What is new in this filter, however, is the selector "Header + Image"
+    # which selects all {PandocFilter::Image} nodes that *follow* a
+    # {PandocFilter::Header} node. Documents in pandoc have a _flat_ structure
+    # where chapters do not exists as separate concepts. Instead, a chapter is
+    # implied by a header of a certain level and everything that follows until
+    # the next header of that level.
+    #
+    # == Using the "child of" selector: Annotate custom blocks
+    #
+    # Hierarchical structures do exist in a pandoc document, however. For
+    # example, the contents of a paragraph ({PandocFilter::Para}), which
+    # itself is a {PandocFilter::Block} level node, are {PandocFilter::Inline}
+    # level nodes. Another example are custom block or {PandocFilter::Div}
+    # nodes.  You select a child node by using the +>+ selector as in the
+    # example below:
+    #
+    # {include:file:examples/filters/example.rb}
+    #
+    # Here all {PandocFilter::Header} nodes that are inside a
+    # {PandocFilter::Div} node are selected. Furthermore, if these headers are
+    # of level 3, they are prefixed by the string "Example" followed by a
+    # count.
+    #
+    # In this example, "important" {PandocFilter::Div} nodes are annotated by
+    # putting the string *important* before the contents of the node.
+    #
+    # == Using a distance in a selector: Capitalize the first N characters of
+    # a paragraph
+    #
+    # Given the flat structure of a pandoc document, the "follows" selector
+    # has quite a reach. For example, "Header + Para" selects all paragraphs
+    # that follow a header. In most well-structured documents, this would
+    # select basically all paragraphs.
+    #
+    # But what if you need to be more specific? For example, if you would like
+    # to capitalize the first sentence of each first paragraph of a chapter,
+    # you need a way to specify a sequence number of sorts. To that end, paru
+    # filter selectors take an optional *distance* parameter. A filter for
+    # this example could look like:
+    #
+    # {include:file:examples/filters/capitalize_first_sentence.rb}
+    #     
+    # The distance is denoted after a selector by an integer. In this case
+    # "Header +1 Para" selects all {PandocFilter::Para} nodes that directly
+    # follow an {PandocFilter::Header} node. You can use a distance with any
+    # selector.
+    #
+    # == Manipulating nodes: Removing horizontal lines
+    #
+    # Although the {PandocFilter::Node#inner_markdown} and
+    # {PandocFilter::Node#outer_markdown} work in most situations, sometimes
+    # direct manipulation of the pandoc document AST is useful. These
+    # {PandocFilter::ASTManipulation} methods are mixed in
+    # {PandocFilter::Node} and can be used on any node in your filter. For
+    # example, to delete all {PandocFilter::HorizontalRule} nodes, can use a
+    # filter like:
+    #
+    # {include:file:examples/filters/delete_horizontal_rules.rb}
+    #
+    # Note that you could have arrived at the same effect by using:
+    #
+    #     rule.outer_markdown = ""
+    #
+    # 
+    #
+    # == Manipulating metadata: 
+    #
+    # One of the interesting features of the pandoc markdown format is the
+    # ability to add metadata to a document via a YAML block or command line
+    # options. For example, if you use a template that uses the metadata
+    # property +$date$+ to write a date on a title page, it is quite useful to
+    # automatically add the date of _today_ to the metadata. You can do so
+    # with a filter like:
+    #
+    # {include:file:examples/filters/add_today.rb}
+    #
     class Filter
 
         # Run the filter specified by block. In the block you specify

data/lib/paru/filter/document.rb

@@ -25,8 +25,11 @@ module Paru
         require_relative "./meta"
         require_relative "./version"
 
+        # Pandoc type version key
         VERSION = "pandoc-api-version"
+        # Pandoc type meta key
         META = "meta"
+        # Pandoc type block key
         BLOCKS = "blocks"
 
         # The current pandoc type version

data/lib/paru/filter/link.rb

@@ -29,7 +29,7 @@ module Paru
         # @!attribute attr
         #   @return [Attr]
         #
-        # @!attribute targer
+        # @!attribute target
         #   @return [Target]
         class Link < Inline
             attr_accessor :attr, :target

data/lib/paru/filter/meta_map.rb

@@ -50,6 +50,16 @@ module Paru
                 end
             end
 
+            # Set a value with a key
+            #
+            # @param key [String] the key to set
+            # @param value
+            #   [MetaBlocks|MetaBool|MetaInline|MetaList|MetaMap|MetaString|MetaValue]
+            #   the value to set
+            def []=(key, value)
+                @children[key] = value
+            end
+
             # Does this MetaMap node have key?
             #
             # @param key [String] the key to find

data/lib/paru/filter/str.rb

@@ -21,8 +21,13 @@ module Paru
         require_relative "./inline"
 
         # A Str node represents a string
+        #
+        # @!attribute string
+        #   @return [String] the value of this Str node.
         class Str < Inline
 
+            attr_accessor :string
+
             # Create a new Str node based on the value
             #
             # @param value [String]

data/lib/paru/pandoc.rb

@@ -22,32 +22,69 @@ module Paru
     require "yaml"
 
     # Pandoc is a wrapper around the pandoc document converter. See
-    # <http://pandoc.org/README.html> for details about pandoc.  This file is
-    # basically a straightforward translation from the pandoc command line
-    # program to a ruby class, giving a Rubyesque API to work with pandoc.
+    # <http://pandoc.org/README.html> for details about pandoc.  The Pandoc
+    # class is basically a straightforward translation from the pandoc command
+    # line program to Ruby. It is a Rubyesque API to work with pandoc.
+    #
+    # For information about writing pandoc filters in Ruby see {Filter}.
+    #
+    # Creating a Paru pandoc converter in Ruby is quite straightforward: you
+    # create a new Paru::Pandoc object with a block that configures that
+    # Pandoc object with pandoc options. Each command-line option to pandoc is
+    # a method on the Pandoc object. Command-line options with dashes in them,
+    # such as "--reference-docx", can be called by replacing the dash with an
+    # underscore. So, "--reference-docx" becomes the method +reference_docx+.
+    #
+    # Pandoc command-line flags, such as "--parse-raw", "--chapters", or
+    # "--toc", have been translated to Paru::Pandoc methods that take an
+    # optional Boolean parameter; +true+ is the default value. Therefore, if
+    # you want to enable a flag, no parameter is needed.
+    #
+    # All other pandoc command-line options are translated to Paru::Pandoc
+    # methods that take either one String or Number argument, or a list of
+    # String arguments if that command-line option can occur more than once
+    # (such as "--include-before-header" or "--filter").
+    #
+    # Once you have configured a Paru::Pandoc converter, you can call
+    # +convert+ or +<<+ (which is an alias for +convert+) with a string to
+    # convert. You can call +convert+ as often as you like and, if you like,
+    # reconfigure the converter in between!
     #
-    # @example Convert the markdown string 'hello *world*' to HTML
-    #     converter = Paru::Pandoc.new
-    #     converter.configure do
-    #         from "markdown"
-    #         to "html"
-    #     end
-    #     converter.convert 'hello *world*'
     #
-    # @example Convert markdown to HTML, written in a more commonly used shorthand
+    # @example Convert the markdown string 'hello *world*' to HTML
     #     Paru::Pandoc.new do
-    #         from markdown
-    #         to html
+    #         from 'markdown
+    #         to 'html'
     #     end << 'hello *world*'
     #
+    # @example Convert a HTML file to DOCX with a reference file
+    #     Paru::Pandoc.new do
+    #         from "html"
+    #         to "docx"
+    #         reference_docx "styled_output.docx"
+    #         output "output.docx"
+    #     end.convert File.read("input.html")
+    #
+    # @example Convert a markdown file to html but add in references in APA style
+    #     Paru::Pandoc.new do
+    #         from "markdown"
+    #         toc
+    #         bibliography "literature.bib"
+    #         to "html"
+    #         csl "apa.csl"
+    #         output "report_with_references.md"
+    #     end << File.read("report.md")
+    #
     #
     class Pandoc
 
-        # Gather information about pandoc. It runs `pandoc --version` and extracts
-        # pandoc's version number and default data directory.
+        # Gather information about the pandoc installation. It runs +pandoc
+        # --version+ and extracts pandoc's version number and default data
+        # directory. This method is typically used in scripts that use Paru to
+        # automate the use of pandoc.
         #
-        # @return [Hash] Return a Hash with the :verion and :data_dir of the
-        #   pandoc installation
+        # @return [Hash{:version => String, :data_dir => String}] Pandoc's
+        #   version, such as "1.17.0.4" and the data directory, such as "/home/huub/.pandoc".
         def self.info()
             output = ''
             IO.popen('pandoc --version', 'r+') do |p|
@@ -63,10 +100,10 @@ module Paru
             }
         end
 
-        # Create a new Pandoc converter, optionally configured by block
+        # Create a new Pandoc converter, optionally configured by a block with
+        # pandoc options. See {#configure} on how to configure a converter.
         #
-        # @param block [Proc] an optional configuration block. See #configure
-        #   for how to configure a Pandoc converter
+        # @param block [Proc] an optional configuration block.
         def initialize(&block)
             @options = {}
             configure(&block) if block_given?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paru
 version: !ruby/object:Gem::Version
-  version: 0.2.4.3
+  version: 0.2.4.4
 platform: ruby
 authors:
 - Huub de Beer