riven 1.1.4 → 1.3.0

data/doc/chapters/2-setup/2-installation.md

@@ -0,0 +1,17 @@
+## 2.2. Install Riven
+
+The installation of Riven is pretty simple. Just run:
+
+```bash
+$ gem install riven
+```
+
+And you're done!
+
+After that you should have a `riven` command:
+
+```bash
+$ riven -V
+```
+
+That's it!

data/doc/chapters/2-setup/index.md

@@ -0,0 +1,6 @@
+# 2. Setup Riven
+
+In this chapter we'll tackle the setup of Riven. You'll learn everything you need to know regarding the installation and especially the prerequisites and pitfalls.
+
+<<[ 1-prerequisites.md ]
+<<[ 2-installation.md ]

data/doc/chapters/3-basics/1-single-file.md

@@ -0,0 +1,19 @@
+## 3.1. A single file
+
+Let's start small and transform a single file into your first beautiful PDF!
+
+Create a new markdown file where ever you want and name it `awesome.md`. Put some markdown into the file just like this:
+
+```markdown
+# Hello World!
+
+**This** is my first Riven generated PDF!
+```
+
+Now we compile the PDF with a simple Riven call:
+
+```bash
+$ riven awesome.pdf
+```
+
+You should get a PDF file called `awesome.pdf`. Open it and admire your first PDF.

data/doc/chapters/3-basics/2-multiple-files.md

@@ -0,0 +1,65 @@
+## 3.2. Many at once
+
+Now we know how to convert a single file into a PDF document. But usually we have more then one file. For example one
+file for each chapter. Riven may take a bunch of markdown files and compile them into a single PDF file.
+
+In order to use that feature, we need some more markdown files:
+
+`chapter-1.md`:
+
+```markdown
+# Chapter 1
+
+Hello World!
+```
+
+
+`chapter-2.md`:
+
+```markdown
+# Chapter 2
+
+Another example
+```
+
+`chapter-3.md`:
+
+```markdown
+# Chapter 3
+
+Last but not least
+```
+
+Now you can merge all these files into a single PDF with the following command:
+
+```bash
+$ riven -o awesome.pdf chapter-1.md chapter-2.md chapter-3.md
+```
+
+You'll get a single PDF file, just as in chapter 3.1., which contains all three chapters and the regarding content. The
+`-o` param determines the name of the generated PDF file.
+
+
+Riven is also able to guess the PDF file name if all markdown files are located in one directory. So let's create
+a directory called `awesome` and put our three markdown files into it. Now you should have a file structure like this:
+
+```bash
+$ ls -1
+awesome/
+
+$ ls -1 awesome/
+chapter-1.md
+chapter-2.md
+chapter-3.md
+```
+
+The following command will generate exactly the same PDF file as the command we used before, but you don't have to
+provide a PDF file name. Riven will take the directory name as the PDF file name.
+
+```bash
+$ riven awesome/
+```
+
+You'll receive a `awesome.pdf` file like before.
+
+Consider that Riven will merge the markdown files of the directory in alphabetical order.

data/doc/chapters/3-basics/3-structured-files.md

@@ -0,0 +1,55 @@
+## 3.3. Structure your files
+
+In the two previous chapters you learned how to convert a single file or a bunch of files into a PDF. In this chapter
+you'll learn a nice mixed way how to structure bigger documents with many markdown files without the need to pass all
+those files to the riven command or to ensure the alphabetical order is the order you want.
+
+The magical feature of Riven which allows us to bring a clean tidiness in your files, is called *include directive*.
+It's a markdown syntax which is not part of the original markdown language, but a feature of the Riven Extended
+Markdown - or REM. REM is a superset of the GitHub Flavored Markdown introduced by Riven in order to provide some
+additional features. The include directive allows you to define another markdown file. Riven will merge the content of
+that markdown file into the outer markdown file by replacing the include directive.
+
+The include syntax looks like that:
+
+`_<<[ file ]`
+
+where `file` is the path to another markdown file.
+
+**Here's an example:**
+
+`a.md`:
+
+```markdown
+Hello World!
+
+_<<[ b.md ]
+
+Bye World!
+```
+
+`b.md`:
+
+```markdown
+This content is **included**!
+```
+
+If you call
+
+```bash
+$ riven -o a.pdf a.md
+```
+
+Riven will merge the two files like that:
+
+```markdown
+Hello World!
+
+This content is **included**!
+
+Bye World!
+```
+
+This feature allows you to organize your document over many markdown files and subdirectories. Take a look at
+https://github.com/phortx/riven/tree/master/doc to see a good example for the usage of includes and how to structure
+a document.

data/doc/chapters/3-basics/4-config-file.md

@@ -0,0 +1,63 @@
+## 1.4. The config file
+
+If you take a look at the Riven help (`riven -h`), you'll see that riven supports a bunch of command line options. It
+can be a bit painful to remember all those parameters in order to regenerate your PDF from time to time. So it's
+recommended to setup a config file for riven where you can set all your settings instead of passing them to the `riven`
+command. This can you save you a lot of time.
+
+A Riven config file is a simple YAML file, like you may know from Rails or Symfony. But they're really easy to
+understand, so no panic if you never heard of it before.
+
+An example riven.yml looks like that:
+
+```yml
+pdf_output_file: example.pdf
+cover_file: cover.md
+css_file: style.css
+generate_toc: true
+toc_headline: 'Contents'
+dump_html: false
+dump_cover_html: false
+verbose: false
+files:
+  - index.md
+```
+
+You may provide as many files as you want under the `files` section. Each file gets one line. For example:
+
+```yml
+files:
+  - index.md
+  - chapter-1.md
+  - chapter-2.md
+  - chapter-3.md
+```
+
+Riven searches for a `riven.yml` in the current directory. But if you config file is located in another directory, you
+should pass it via the `-C` param. However if you structure your document like this:
+
+```bash
+$ ls -1
+
+chapters/
+cover.md
+index.md
+riven.yml
+style.css
+```
+
+it will be pretty easy to generate your PDF, since you just have to call `riven` without any params:
+
+```bash
+$ riven
+```
+
+It will use the `riven.yml` from the current directory and load all settings from it.
+
+You're also allowed to mix up command line parameters and the config file. For example you can override the stylesheet:
+
+```bash
+$ riven -s another_style.css
+```
+
+The command line params will override the settings from the `riven.yml`.

data/doc/chapters/3-basics/index.md

@@ -0,0 +1,17 @@
+# 3. Learn the basics
+
+Now as Riven is up and running, let's have some fun and start writing! In this chapter you'll learn the basics and how
+to use Riven to generate PDFs.
+
+However if you're looking for an good example: You're actually reading one! This documentation is generated with Riven
+and you can read the markdown source code at the [doc directory](https://github.com/phortx/riven/blob/master/doc/) in
+the GitHub repository of riven. The [generated PDF](https://github.com/phortx/riven/blob/master/doc/riven.pdf) can be
+found in that directory too.
+
+If you want to learn markdown, you should take a look at the
+[Learn Markdown book from GitBook](https://gitbookio.gitbooks.io/markdown/content/) which can be read online.
+
+<<[ 1-single-file.md ]
+<<[ 2-multiple-files.md ]
+<<[ 3-structured-files.md ]
+<<[ 4-config-file.md ]

data/doc/chapters/4-advanced-usage/1-css.md

@@ -0,0 +1,34 @@
+## 4.1. Style your PDF
+
+Riven allows you to style your PDF via CSS rules. This feature makes it possible to change colors, fonts, margins and
+many more.
+
+However please consider that this is a PDF, so the capabilities of the layouting via CSS is limited. Not every CSS rule
+you know will work.
+
+In order to use a CSS file, you have to create a `style.css` for example and pass it to the `-s` param of riven:
+
+```bash
+$ riven -s style.css documentation.md
+```
+
+Some hints:
+
+- Every text paragraph is wrapped into a `<p>` tag
+- The headlines will be transformed to `<h1>`, `<h2>`, `<h3>` ... tags, where `#` is `<h1>`, `##` is `<h2>` and so on
+- Quotes (`>`) are transformed to a `<blockquote>` tag
+- Bold text is transformed to a `<strong>` tag
+- `<hr>` tags are used for horizontal lines (`-----`)
+- Unordered lists are transformed to `<ul>` and `<li>` tags and ordered lists are transformed to `<ol>` and `<li>` tags.
+  Nested lists are `<ul>` tags within a `<li>` tag
+- Inline fixed width text (backticks) is transformed to `<code>` tags
+- Multiline code blocks are transformed into `<pre>` tags
+
+To style the cover page, you can use the `.cover-page` CSS class. The following example will change the h1 color on the
+cover page to red:
+
+```css
+.cover-page h1 {
+  color: red;
+}
+```

data/doc/chapters/4-advanced-usage/2-table-of-contents.md

@@ -0,0 +1,11 @@
+## 4.2. Automatic Table of Contents
+
+For an automatic generated table of contents after the cover page, you can add the `-t` param and pass a headline for
+the table of contents:
+
+```bash
+$ riven -t "Contents" -c documentation/cover.md documentation/
+```
+
+Riven will generate a table of contents for all headlines. The user can click on the entries to jump directly to the
+regarding headline.

data/doc/chapters/4-advanced-usage/3-cover.md

@@ -0,0 +1,10 @@
+## 4.3. Cover pages
+
+To start your PDF with a nice cover page, define a cover markdown file and pass it to the `-c` param. Riven will prepend
+that file before all other files and doesn't attach a page number.
+
+```bash
+$ riven -c documentation/cover.md documentation/
+```
+
+It can be helpful to use HTML within the cover page to have more control over it's layout.

data/doc/chapters/4-advanced-usage/4-syntax-highlighting.md

@@ -0,0 +1,23 @@
+## 4.4. Syntax highlighting
+
+Riven comes with syntax highlighting for code blocks:
+
+```markdown
+` ``ruby
+  def foo
+    puts 'bar'
+  end
+` ``
+```
+
+(Ignore the whitespace between the backticks)
+
+This code sample will produce the following field in the PDF:
+
+```ruby
+  def foo
+    puts 'bar'
+  end
+```
+
+The syntax highlighting is powered by [coderay](https://github.com/rubychan/coderay) and Riven is using a [github theme](https://github.com/pie4dan/CodeRay-GitHub-Theme).

data/doc/chapters/4-advanced-usage/index.md

@@ -0,0 +1,10 @@
+# 4. Advanced topics
+
+In this last chapter we'll tackle all advanced features of Riven like the styling of the PDF with CSS, the table of
+contents, cover pages and syntax highlighting of code snippets.
+
+
+<<[ 1-css.md ]
+<<[ 2-table-of-contents.md ]
+<<[ 3-cover.md ]
+<<[ 4-syntax-highlighting.md ]

data/doc/cover.md

@@ -0,0 +1,37 @@
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+
+![riven](img/cover.png)
+
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+
+# Official Riven Manual
+## Write Markdown. Get a nice PDF. Have fun.
+
+
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+<br />
+
+
+> powered by Benjamin Kammerl  |  visit *[github.com/phortx/riven](https://github.com/phortx/riven)*  |  MIT license

data/doc/index.md

@@ -0,0 +1,4 @@
+<<[ chapters/1-what-is-riven/index.md ]
+<<[ chapters/2-setup/index.md ]
+<<[ chapters/3-basics/index.md ]
+<<[ chapters/4-advanced-usage/index.md ]

data/doc/riven.yml

@@ -0,0 +1,10 @@
+pdf_output_file: riven.pdf
+cover_file: cover.md
+css_file: style.css
+generate_toc: true
+toc_headline: 'Contents'
+dump_html: false
+dump_cover_html: false
+verbose: true
+files:
+  - index.md

data/doc/style.css

@@ -0,0 +1,21 @@
+body {
+  color: #555;
+}
+
+h1 {
+  color: #337AB7;
+  font-weight: normal;
+}
+
+h2 {
+  font-weight: 500;
+}
+
+.cover-page h1 {
+  background-color: #337AB7;
+  color: #fff;
+}
+
+.cover-page blockquote {
+  background-color: #eee;
+}

data/lib/riven/config.rb

@@ -0,0 +1,122 @@
+module Riven
+  class Config
+    attr_accessor \
+      :pdf_output_file,
+      :cover_file,
+      :css_file,
+      :generate_toc,
+      :toc_headline,
+      :dump_html,
+      :dump_cover_html,
+      :verbose,
+      :dir_given,
+      :config_file,
+      :files
+
+
+    #
+    # Constructor with the default values
+    #
+    public def initialize
+      @pdf_output_file = nil
+      @cover_file = nil
+      @css_file = nil
+      @generate_toc = false
+      @toc_headline = 'Contents'
+      @dump_html = false
+      @dump_cover_html = false
+      @verbose = false
+      @dir_given = false
+      @config_file = nil
+      @files = []
+    end
+
+
+    #
+    # Overrides the value in the current config if the value of the other config is not the default value
+    #
+    public def merge(another_config)
+      @pdf_output_file = another_config.pdf_output_file if another_config.pdf_output_file != nil
+      @cover_file = another_config.cover_file           if another_config.cover_file != nil
+      @css_file = another_config.css_file               if another_config.css_file != nil
+      @generate_toc = another_config.generate_toc       if another_config.generate_toc != false
+      @toc_headline = another_config.toc_headline       if another_config.toc_headline != 'Contents'
+      @dump_html = another_config.dump_html             if another_config.dump_html != false
+      @dump_cover_html = another_config.dump_cover_html if another_config.dump_cover_html != false
+      @verbose = another_config.verbose                 if another_config.verbose != false
+      @dir_given = another_config.dir_given             if another_config.dir_given != false
+      @config_file = another_config.config_file         if another_config.config_file != nil
+      @files = another_config.files                     if another_config.files != []
+    end
+
+
+    #
+    # Prints the current config
+    #
+    public def print
+      puts
+      puts "Using config file #{config_file}" if config_file != nil
+      puts
+      puts 'Riven configuration:'
+      puts "    - pdf_output_file: #{@pdf_output_file}"
+      puts "    - cover_file:      #{@cover_file.path}"
+      puts "    - css_file:        #{@css_file}"
+      puts "    - generate_toc:    #{@generate_toc}"
+      puts "    - toc_headline:    #{@toc_headline}"
+      puts "    - dump_html:       #{@dump_html}"
+      puts "    - dump_cover_html: #{@dump_cover_html}"
+      puts "    - verbose:         #{@verbose}"
+      puts "    - dir_given:       #{@dir_given}"
+      puts "    - config_file:     #{@config_file}"
+
+      puts '    - files:'
+
+      @files.each do |file|
+        puts "        - #{file.path}"
+      end
+
+      puts
+    end
+
+
+    #
+    # Setter for @css_file
+    #
+    public def css_file=(file)
+      @css_file = File.expand_path(file)
+    end
+
+
+    #
+    # Setter for @cover_file
+    #
+    public def cover_file=(file)
+      @cover_file = Riven::MarkupFile.new(file)
+    end
+
+
+    #
+    # Setter for @files
+    #
+    public def files=(files)
+      @files = files.map { |file| Riven::MarkupFile.new(file) }
+    end
+
+
+    #
+    # Parses a riven config yml file and constructs a Config object
+    #
+    def self.parse(config_file)
+      require 'yaml'
+      config = Riven::Config.new
+      config.config_file = config_file
+      parsed = YAML::load(File.open(File.expand_path(config.config_file)))
+
+      parsed.each do |key, value|
+        config.send(:"#{key}=", value)
+      end
+
+      config
+    end
+  end
+end