riven 1.1.4 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 041073e77332410b3beec7c6f5e2510020034e95
-  data.tar.gz: 6e39be4418714492d5ca7f2c99c0dd0bd3f11b72
+  metadata.gz: 1db4e60b13dcba67d9b6bd7fd7708f395a6d26c2
+  data.tar.gz: b285fa0211720e1c5ab51192cc2cf87843880fa8
 SHA512:
-  metadata.gz: 9d112db24fac421b1d166f181c7660368931eacfe7e5158c2c61997585c26eff6764626af9e0080ffc6c178e39634e18671b19abd14cf017d26677a3cb6a207a
-  data.tar.gz: 594129231909ba0208df4cf014534660faf61dff2751d5b6eb6b4a480f87f2eb662b56226e3659e7eb741901c9cb1688055062251aee9ebd9aa66afa0a3ee257
+  metadata.gz: 7d9c706678b7e24eab37c4d24f038c7e6124dbcb652fc26d720abe12681fc92c0a5334ded8cb52cdd7542ba7251fcd762eb94155d2f48f2d7e610ae8ac27264b
+  data.tar.gz: be65f9e746417996f225a886ab531c99e4871d90f15f8f1bb8fd75c866b9b520541c22986f7db1391e6b42ae461e5f2edbec79753511e3c23a36a6fc60ea2cb7

data/.gitignore

@@ -17,7 +17,6 @@ build/
 ## Documentation cache and generated files:
 /.yardoc/
 /_yardoc/
-/doc/
 /rdoc/
 
 ## Environment normalisation:
@@ -32,3 +31,6 @@ build/
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
+
+# RubyMine
+/.idea

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    riven (1.1.2)
+    riven (1.2.0)
       coderay (~> 1.1)
       redcarpet (~> 3.2)
 
@@ -10,7 +10,7 @@ GEM
   specs:
     coderay (1.1.0)
     rake (10.4.2)
-    redcarpet (3.3.1)
+    redcarpet (3.2.3)
 
 PLATFORMS
   ruby
@@ -19,6 +19,3 @@ DEPENDENCIES
   bundler (~> 1.8)
   rake (~> 10.4)
   riven!
-
-BUNDLED WITH
-   1.10.3

data/README.md

@@ -1,172 +1,39 @@
 # Riven
 
-Converts GitHub Flavored Markdown files to PDFs! Write documentations, books, reports and documents with your editor.
-Publish them as PDF! It's that simple and even more powerful.
+Riven converts Markdown files into PDF documents! Write documentations, books, reports, everything with your
+favorite text editor and publish them as PDF - It's that simple and even more powerful.
 
+**Feature highlights:**
 
-Feature highlights:
-
-- Riven Extended Markdown featuring includes: Structure you work!
+- Riven Extended Markdown (it's GitHub Flavored Markdown but with more features!)
+- Include directives: Structure your document!
 - Generates well readable, optimized, beautiful looking PDFs
 - Style your PDF via CSS
 - Define a special and nice looking cover page
 - Auto generated table of contents
-- Syntax Highlighting with GitHub like theme
-- Page numbers
+- Syntax Highlighting with GitHub theme
+- Page footer with page numbers
 - Smart directory based file merging and output file naming
 
 
-## Prerequisites
-
-You need `wkhtmltopdf` in order to generate PDFs, since that's the PDF generator backend for riven. You should use the
-QT patched version of `wkhtmltopdf` to get all the features of riven. You may also use the version without patched qt,
-but that will disable the following features of riven: Page numbers, table of contents, covers.
-
-- If you got Arch Linux, you can just install the packages `wkhtmltopdf-static`and `icu48` from the AUR.
-
-- If you got another Linux Distribution (like Ubuntu) or OSX you have compile `wkhtmltopdf` from the sources. See http://natepinchot.com/2014/01/31/building-static-wkhtmltopdf/. This may take some time: On my i7, 16GB RAM, SSD
-Notebook it took about 20 minutes.
-
-- Otherwise, you should download `wkhtmltopdf` from the [official website](http://wkhtmltopdf.org/downloads.html).
-
-After that, make sure you can execute the `wkhtmltopdf` command in your shell:
-
-```bash
-$ wkhtmltopdf -V
-```
-
-If it works, everything is nice and you may proceed with the next step. If not, please make sure, `wkhtmltopdf` is
-correctly installed and the executable is within your `PATH`.
-
-
-## Installation
-
-Simple as usual:
-
-```bash
-$ gem install riven
-```
-
-
-## Usage
-
-Riven is designed to create documents out of a bunch of markdown files. So it may take a single markdown file or a
-directory with some markdown files inside. Consider that the files are merged in alphabetical order if you provide a
-folder. Just take a look at the following examples.
-
-
-### Single file to PDF
-
-This will take your `example.md` and generate a `example.pdf` in the same directory:
-
-```bash
-$ riven example.md
-```
-
-
-### Multiple files
-
-This will take your `example-1.md` and `example-2.md` and generate a `awesome.pdf` in the same directory:
-
-```bash
-$ riven -o awesome.pdf example-1.md example-2.pdf
-```
-
-
-### A directory
-
-This will take your `documentation` directory with all it's files and generate a `documentation.pdf` (the name is
-guessed from the directory name, but you may also specify a output file name via the `-o` param) in the same
-directory:
-
-```bash
-$ ls
-documentation/
-
-$ ls documentation/
-chapter-1-preface.md
-chapter-2-general.md
-chapter-3-admin-gui.md
-chapter-4-commandline-interface.md
-chapter-5-api.md
-
-$ riven documentation/
-
-$ ls
-documentation.pdf
-documentation/
-```
-
-
-### Structure via includes
-
-You may also structure your document via includes. Just define a main file and you may define as many include directives
-within that file and any other files (even in subdirectories) as you want.
-
-**index.md**
-
-```md
-## Just a example
-
-This is a include:
-
-<<[ another_file.md ]
-```
-
-**another_file.md**
-
-```md
-More **content** in this file.
-```
-
-Generate the PDF via:
-
-```bash
-$ riven -o awesome.pdf index.md
-```
-
-
-## Additional Features
-
-### Custom CSS
-
-You may give riven an additional CSS file with the `-s` param:
-
-```bash
-$ riven -s doc.css documentation/
-```
-
-unfortunately this CSS doesn't affect the table of contents currently, sorry for that.
-
-
-### Cover
-
-You may give riven a cover MD file via the `-c` param, which will be prepended and not provided with a page number.
-
-```bash
-$ riven -c documentation/cover.md documentation/
-```
-
+## Example PDF
 
-### Syntax highlighting
+The Riven manual itself is generated by Riven.
+**[See the result](https://github.com/phortx/riven/blob/master/doc/riven.pdf)**!
 
-Syntax highlighting just works as usual:
 
-<pre lang="no-highlight">
-```ruby
-  def foo
-    puts 'bar'
-  end
-```
-</pre>
+## Documentation
 
-The syntax highlightning is powered by [coderay](https://github.com/rubychan/coderay) and is using a [github theme](https://github.com/pie4dan/CodeRay-GitHub-Theme).
+Read the user manual of Riven:
 
+- [Online Version on GitHub](https://github.com/phortx/riven/blob/master/doc/chapters/)
+    - [Chapter 1: What is Riven?](https://github.com/phortx/riven/blob/master/doc/chapters/1-what-is-riven/)
+    - [Chapter 2: Setup Riven](https://github.com/phortx/riven/blob/master/doc/chapters/2-setup/)
+    - [Chapter 3: Learn the basics](https://github.com/phortx/riven/blob/master/doc/chapters/3-basics/)
+    - [Chapter 4: Advanced topics](https://github.com/phortx/riven/blob/master/doc/chapters/4-advanced-usage/)
+- [PDF Version](https://github.com/phortx/riven/blob/master/doc/riven.pdf)
 
-### Table of Contents
 
-For an automatic generated table of contents after the cover, just add the `-t` param and provide a headline for the table of contents:
+## Contribute
 
-```bash
-$ riven -t "Contents" -c documentation/cover.md documentation/
-```
+Riven just started and there's a lot to do. Contributions are welcome! Feel free to send pull requests :)

data/bin/riven

@@ -13,35 +13,34 @@ Riven::Wkhtmltopdf.check_installation
 
 
 ## Step 2: Parse command line options
-options = Riven::OptParser.options
-files = Riven::OptParser.files(options)
+config = Riven::OptParser.get_config
 
 
 ## Step 3: Change dir if directory is given to ensure the image pathes work
-unless options[:dir_given] === false
+unless config.dir_given === false
   working_dir = Dir.pwd
-  Dir.chdir options[:dir_given]
+  Dir.chdir config.dir_given
 end
 
 
 ## Step 4: Generate HTML for cover
-unless options[:cover_file] === ''
-  cover_markup = Riven::MarkupFile.read_cover(options[:cover_file])
+unless config.cover_file === ''
+  cover_markup = Riven::MarkupFile.read_cover(config.cover_file)
 end
-cover_generator = Riven::HTMLGenerator.new('_riven_cover_tmp_file.html', cover_markup || '', options)
+cover_generator = Riven::HTMLGenerator.new('_riven_cover_tmp_file.html', cover_markup || '', config)
 
 
 ## Step 5: Generate HTML for main document
-markup = Riven::MarkupFile.read_all(files, options[:cover_file])
-generator = Riven::HTMLGenerator.new('_riven_tmp_file.html', markup, options)
+markup = Riven::MarkupFile.read_all(config.files, config.cover_file)
+generator = Riven::HTMLGenerator.new('_riven_tmp_file.html', markup, config)
 
 
 ## Step 6: Determine PDF file name
-output_file = options[:output_file]
+output_file = config.pdf_output_file
 
 if output_file.empty?
-  unless options[:dir_given] === false
-    output_file = options[:dir_given] + '.pdf'
+  unless config.dir_given === false
+    output_file = config.dir_given + '.pdf'
   else
     puts "No output file name given. Please specify output file name via -o param."
     generator.close!
@@ -50,12 +49,12 @@ if output_file.empty?
   end
 end
 
-puts "Output file: #{output_file}" if options[:verbose]
+puts "Output file: #{output_file}" if config.dir_given
 
 
 ## Step 7: Generate the PDF file from HTML file
-output = Riven::Wkhtmltopdf.generate_pdf(generator.html_file, cover_generator.html_file, output_file, options)
-puts output if options[:verbose]
+output = Riven::Wkhtmltopdf.generate_pdf(generator.html_file, cover_generator.html_file, output_file, config)
+puts output if config.verbose
 
 
 ## Step 8: Close the generators
@@ -64,13 +63,13 @@ cover_generator.close!
 
 
 ## Step 9: Dump the HTML code if requested
-puts generator.html if options[:dump_html]
-puts cover_generator.html if options[:dump_cover_html]
+puts generator.html if config.dump_html
+puts cover_generator.html if config.dump_cover_html
 
 
 ## Step 10: If we changed the directory before, the PDF file is now located in the wrong directory,
 ## so wie have to move it
-unless options[:dir_given] === false
+unless config.dir_given === false
   require 'fileutils'
   FileUtils.mv output_file, working_dir + '/' + output_file
 end

data/doc/chapters/1-what-is-riven/1-scenario-a.md

@@ -0,0 +1,12 @@
+## 1.1. Scenario A: You want to write a book
+
+You are a bit familiar with Linux or OSX. Maybe you even know what markdown is, but it's okay if you don't know markdown.
+And you want to write a book for some reason. Maybe a subject book, maybe a novel or maybe some fanfiction for whatever
+you like. But you have no idea of LaTeX and you don't want to write it in LibreOffice or some other kind of office
+suite for some reason. Maybe because you want to have full control over all formatings and you love a text editor like
+atom, sublime editor or vim. You also know HTML and CSS maybe, but you don't want to use it since it's to much code to
+write and you have to test to it too often in you browser while writing.
+
+What you want is just a very simple and lean tool chain which let's you write a very minimalistic markup in your
+favorite text editor and compiles everything in a beautiful, readable and stylish PDF (and mobi, epub etc in the
+future). And if something doesn't fit your requirements, you just change it via CSS or configuration.

data/doc/chapters/1-what-is-riven/2-scenario-b.md

@@ -0,0 +1,8 @@
+## 1.2. Scenario B: Your a coder and want to document your software
+
+You have a software project, you're familiar with Linux or OSX, HTML, CSS, Markdown and others. And you want to document
+your software in a plain text readable format. But you also want a very simple and lean tool chain which compiles
+everything in a beautiful, readable and stylish PDF (and mobi, epub etc in the future). And if something doesn't fit
+your requirements, you just change it via CSS or configuration. Also you want to use your favorite text editor like atom, sublime editor or vim but don't want to write the documentation in HTML and CSS since it's to much code to write and you
+have to test to it too often in you browser while writing. And you don't want to write it in LibreOffice or some other
+kind of office suite for some reason. For example because you're working in a team and you're using some kind of version control system like git. Therefore a plain text format is much more beneficial then a binary blob.

data/doc/chapters/1-what-is-riven/3-what-is-riven-not.md

@@ -0,0 +1,16 @@
+## 1.3. What is Riven not?
+
+Now you may have a clue what Riven is. But it's maybe even more important to understand what riven actually is **not**.
+Well Riven is neither a editor like atom nor a typesetting system like TeX nor a markup language like markdown or
+reStructuredText nor a office suite nor a web based service like [Lit Lift](http://www.litlift.com/) or
+[Fast Pencil](http://www.fastpencil.com/). It's just a command line tool which transforms markdown files into PDF
+documents (and HTML, mobi, ePub etc in the future). So it's more comparable with the
+[sphinx documentation generator](http://sphinx-doc.org/).
+
+Also Riven doesn't run on windows machines. Sorry for that.
+
+Additionally Riven lacks some features you may know from sphinx. For example HTML site generation is not there (yet!)
+and Riven is (yet!) not able to generate man pages, ePub and mobi formats. But those features are planned and will be
+added in the future. Also Riven intentionally doesn't generate chapter numeration like you may know from sphinx. You
+have to do it on your own (and you can just omit it if you don't like it or even mix it up). But maybe there will be an
+option in the future which makes Riven to auto generate chapter numbers for you.

data/doc/chapters/1-what-is-riven/4-why-was-riven-created.md

@@ -0,0 +1,35 @@
+## 1.4. Why was Riven created?
+
+I've two hobbies. Ok I got more hobbies, but only two of them are relevant for Riven.
+
+One is programming. I code a lot. Additionally it's my job so I code even more. And a good programmer documents
+his software. In my company we're working on a high innovative CMS with a very versatile framework which allows us to
+implement nearly every kind of project. We had to document that framework in some way for the other developers who
+would use it and implement the customer projects based on the CMS. One requirement to the documentation was portability.
+It should be readable on the PC, on Tablets and it should be printable. As we started to write the documentation, we
+used OpenOffice and saved it as a ODT file which is basically a ZIP-File with some XML within. In order words: We had a
+big binary file in our git repository. It doesn't took a long time until we had merge conflicts due the fact that up to
+three people have been working on the document at the same time. And merging a big binary blob doesn't make fun. So I
+wanted to switch to another tool chain to write the documentation. The obvious suggest was HTML of course. But to write
+HTML is much work, we didn't want to do that. We know HTML, since we're web developers, but we wanted a solution which
+would be more lean and allows a faster workflow without much testing. Of course we could have used our CMS, but we
+wanted to have the documentation in our git repository. However we wanted to use plain text to write your documentation
+and we wanted a PDF as a result. Unfortunately there wasn't any good comparable tool that time.
+
+My second hobby is Pen and Paper. Dungeons and Dragons, you know (Cthulu, Aborea and Pathfinder to be exact). And I was
+writing a campaign. I was writing that campaign in markdown, because I love my editor and I wanted to use git to manage
+everything since GitLab renders markdown nicely. Now I needed a build chain to produce a PDF in order to have one
+document which can be printed or sent via mail.
+
+For these both use cases I hacked the initial proof of concept version of a md2pdf ruby script, which worked pretty
+well. But I wanted some additional features like styling of the PDF via CSS, a cover page, syntax highlighting and some
+other stuff. So the script started to grow to a bigger project. After some time I've renamed it to riven, since, well, it
+sounds cool. And yes it's reference to the Myst series.
+
+In order to keep even big documents structured and clear, riven 1.1.0 introduced the *include* syntax, which allows
+a better split up of the content over many files, subdirectories and allows an easier refactoring of the chapters.
+
+Riven solved both use cases very well. I'm using riven to write both large Pen and Paper campaings and some small
+documents. Either quick or within weeks of hard work. Both cases produce a nice PDF. Today the CMS framework
+documentation of my company includes over 200 PDF pages generated out of 9500 lines of markdown, which are changed on a
+weekly basis and Riven does a nice job.

data/doc/chapters/1-what-is-riven/5-how-can-i-support-riven.md

@@ -0,0 +1,7 @@
+## 1.5. How can I support Riven?
+
+Riven is a MIT licensed Open Source project hosted on GitHub. Just vist https://github.com/phortx/riven. You'll find
+the issues section there containing all bugs and feature requests. Also you can fork the project to send pull requests.
+Feel free to contribute code, documentation or bugfixes!
+
+If you find any bugs, please open a new issue in the issue tracker and I'll try to fix it.

data/doc/chapters/1-what-is-riven/index.md

@@ -0,0 +1,15 @@
+# 1. What is Riven?
+
+In one sentence: Riven is a command line tool, which converts a bunch of markdown files into a PDF file.
+
+**The question is: Why would you do that?**
+
+There are several scenarios where the usage of a tool like Riven would make a lot of sense for you. Let's take a look
+at some of them:
+
+<<[ 1-scenario-a.md ]
+<<[ 2-scenario-b.md ]
+
+<<[ 3-what-is-riven-not.md ]
+<<[ 4-why-was-riven-created.md ]
+<<[ 5-how-can-i-support-riven.md ]

data/doc/chapters/2-setup/1-prerequisites.md

@@ -0,0 +1,49 @@
+## 2.1. Prerequisites
+
+Riven comes with some dependencies, which you have to statisfy before you can start to use it. But no panic it's not
+that hard.
+
+First of all you'll need [wkhtmltopdf](https://github.com/wkhtmltopdf/wkhtmltopdf/) in order to generate PDFs, since
+that's the PDF generator backend of Riven. And you should use the QT patched version of `wkhtmltopdf` to get all the
+features of riven. You may also use the version without patched qt, but that will disable the following features of
+riven: Page numbers, table of contents and covers.
+
+All right, Let's go ...
+
+- If you got Arch Linux, you can just install the packages `wkhtmltopdf-static`and `icu48` from the AUR and you're done.
+  Pretty easy, isn't it?
+
+- If you got another Linux Distribution (like Ubuntu) or OSX you have to compile `wkhtmltopdf` from the sources. See
+  http://natepinchot.com/2014/01/31/building-static-wkhtmltopdf/ for details. This may take some time: On my i7 it takes
+  about 20 minutes.
+
+- Otherwise, you can download `wkhtmltopdf` from the [official website](http://wkhtmltopdf.org/downloads.html).
+
+I know, that part is somewhat uncomfortable and this will change in the future. Either wkhtmltopdf will be automatically
+installed with the gem or riven comes with a Docker container. However, the installation will be easier in the future.
+
+After wkhtmltopdf is compiled, make sure you can execute the `wkhtmltopdf` command in your shell:
+
+```bash
+$ wkhtmltopdf -V
+```
+
+If it works, everything is nice and you may proceed with the next step. If not, please make sure, `wkhtmltopdf` is
+correctly installed and the executable is within your `PATH`.
+
+In the second step, we need ruby. I recommend you to use [RVM](https://rvm.io) to install Ruby. It's pretty simple:
+
+```bash
+$ gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
+$ \curl -sSL https://get.rvm.io | bash -s stable
+$ rvm install 2.2.3
+$ rvm --default use 2.2.3
+```
+
+After that you should be able to use ruby:
+
+```bash
+$ ruby -v
+```
+
+If so, we're ready to install Riven in the next chapter!