legal_markdown 0.1.1

data/.gitignore

@@ -0,0 +1,18 @@
+test.md
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in legal_markdown.gemspec
+gemspec
+
+gem "rake"

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Watershed Legal Services, PLLC
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,189 @@
+# Introduction
+
+This gem will parse YAML Front Matter of Markdown Documents. Typically, this gem would be called with a md renderer, such as [Pandoc](http://johnmacfarlane.net/pandoc/), that would turn the md into a document such as a .pdf file or a .docx file. By combining this pre-processing with a markdown renderer, you can ensure that both the structured content and the structured styles necessary for your firm or organization are more strictly enforced. Plus you won't have to deal with Word any longer, and every lawyer should welcome that. Why? Because Word is awful. 
+
+Gitlaw is markdown agnostic at this point and needs to be called independently of any markdown renderer. It is easy enough to build it into your work flow by editing the way that your markdown renderer is called. For instance you can call this file just before pandoc builds it. I use Sublime Text 2 with the Pandown plugin to build my Pandoc files. So what I would do is [..TODO..].
+
+## What Does the Gem Allow For?
+
+This gem was built specifically to empower the creation of structured legal documents using markdown, and a markdown renderer. This gem acts as a middle layer by providing the user with structured headers and mixins that will greatly empower the use of md to create and maintain structured legal documents.
+
+## How to Install This Gem?
+
+It is very simple. But first you must have ruby installed on your system. (Google it) Once you have ruby installed then you simply go to your terminal and type: `$> gem install legal_markdown`. 
+
+## How to Use This Gem?
+
+After the gem has finished its installation on your system then you can simply type `$> legalmd [filename]` where the filename is the file (in whatever flavor of markdown you use). The gem will parse the file and output the same filename. If you prefer to output as a different filename (which will allow you to keep the YAML front-matter), then you simply type `$> legalmd [input-filename] [output-filename]`. 
+
+# YAML Front-Matter
+
+[YAML](http://www.yaml.org/spec/1.2/spec.html) is about the easiest thing to create. At the top of your file (it MUST be at the top of the file) you simply put in three or more hyphens like so: `---` on a single line. Then on the next line you simply put in the `field` followed by a `:` (colon) followed by the `value`. For each line you put the `[field]: [value]` until you have filled everything in that you need. After you have put in all your YAML front-matter then you simply put in a single line with three more hyphens `---` to signal to the gem that it is the end of the fields. So this would look like this:
+
+    ```yaml
+    ---
+    title: My Perfect Contract
+    author: Watershed Legal Services
+    date: 2013-01-01
+    ---
+    ```
+
+## A Few Signals to the Parser
+
+### Leaving the YAML Front-Matter
+
+The gem will normally strip out the YAML front-matter as most markdown renderers will not be sure what to do with such content. Indeed, pandoc will end up drawing a table with the data still there. However, because some could potentially want to use this gem in combination with something like [Jekyll](https://github.com/mojombo/jekyll/) or any other system that could use the YAML front-matter there is a special trigger that tells legal_markdown to leave the YAML front-matter in the file. Legal_markdown will still make the necessary changes to the text of the file but it will not strip out the YAML front-matter in the process of making those changes. 
+
+To leave the YAML front-matter there simply pass the `value` of `true` to the `field` called `leave_yaml_front_matter`; this is how it would look in the above example. 
+
+    ```yaml
+    ---
+    title: My Perfect Contract
+    author: Watershed Legal Services
+    date: 2013-01-01
+    leave_yaml_front_matter: true
+    ---
+    ```
+
+If you do not add the `true` value to the field then the default which is set to false will be triggered and the YAML Front-Matter will be stripped.
+
+### Some Pandoc-Specific Fields
+
+There are a few fields that will be treated uniquely. The three fields in the example above (title: , author: , and date: ) will be replaced with the Pandoc fields as appropriate. Perhaps later we can (as a community) build out this functionality for other renderers but for now I've only built it to use Pandoc. If you don't use Pandoc then you can simply omit these fields and there will be no problem. 
+
+# Mixins
+
+Mixins are straight-forward they are simple markers that can be used throughout the text to identify certain things (Court) or (Company) or (Client) to identify a few. This allows for the creation and utilization of templates that can be reused by simply updating the YAML front-matter.
+
+Mixins are structured in the form of **double curly** brackets (this was taken from IFTTT). So, for a `{{court}}` mixin, the YAML front-matter would look like this:
+
+    ```yaml
+    {{court}}: Regional Court of Hargeisa
+    ```
+
+Mixins can also be used to set up clauses in the alternative in your templates which can be turned on or off within a specific document simply by updating the YAML mixin to false. Example of a `{{provision12a}}{{provision12b}}` alternative structuring for a contract template. Within the template the YAML front-matter would be structured something like this:
+
+    ```yaml
+    {{provision12a}}: "For the purposes of this Agreement"
+    {{provision12b}}: "This Agreement shall"
+    ```
+
+Then to chose one of the two provisions you would would simply change the line to "false" but without the quotes. Example:
+
+    ```yaml
+    {{provision12a}}: false
+    ```
+
+# Structured Headers
+
+When creating many legal documents, but especially laws and contracts, we find ourselves constantly repeating structured headers. This gets utterly maddening when working collaboratively with various word processors because each word processor has its own sytles and limitations for working with ordered lists and each user of even the same word processor has different defaults. This presents a mess for those that have to clean up these lists. We waste an inordinate amount of time with "Format Painter" and other hacks that do not really allow us to focus on the text. 
+
+In order to address this problem, I have built functionality into legal_markdown that gets around this. Here is how structured headers work in the gem. At the beginning of the line you simply type the level in which the provision resides by the number of lowercase "l" followed by a period and then a space. So a top level provision (perhaps a Chapter, or Article depending on your document) will begin with `l. The provision ...` A second level provision (a Section or whatnot) will begin with `ll. Both parties agree ...` A third level provision will begin with `lll. Yaddy Yadda ...` And so on. These will reside in the body of the text. 
+
+Then you can describe the functionality that you require in the YAML front-matter. In the YAML front-matter you will simply add the following fields: `level-1` and then the `: ` followed by what the format you would like it to be in. Currently there are a few possible options at this time (for those using pandoc at least): 
+
+    1. `level-1: 1.` will format that level of the list as 1. 2. 3. etc.; This is the default functionality; 
+    2. `level-1: (1)` will provide for the same numbering only within parenteticals rather than followed by a period; 
+    3. `level-1: A.` will format with capital letters followed by a period (e.g, A., B., C., etc.);
+    4. `level-1: (A)` will format the same as the above only with the capital letters in a parentetical;
+    5. `level-1: a.` will format with lowercase letters followed by a period;
+    6. `level-1: (a)` will format with lowercase letters within a parentethical;
+    7. `level-1: I.` will format with Roman numerals followed by a period;
+    8. `level-1: (I)` will format with Roman numerals within a parententical.
+
+Obviously you will replace `level-1` with `level-2`, etc. Although this functionality was built into the gem, it is generally not the best practice. A better practice is to let the gem make the replacements and reformat the markdown and then use your rendering system and its default reference documents to set the styles you need. 
+
+## Example
+
+If you use a system like Pandoc you can establish a system wherein the styles that you establish in the reference.docx or reference.odt or the latex style references can make up for the lack of granular fuctionality. When you build your reference.odt for example and you want to have a contract look like this:
+
+Article 1. Provision for Article 1.
+
+  Section 1.1. Provision for Section 1.1. 
+
+    1.1.1 Provision for 1.1.1.
+
+    1.1.2 Provision for 1.1.2.
+
+  Section 1.2. Provision for Section 1.2.
+
+    1.2.1 Provision for 1.2.1.
+
+    1.2.2 Provision for 1.2.2.
+
+...
+
+You can easily to that by doing the following steps.
+
+### Step 1: Type the body
+
+    ```
+    l. Provision for Article 1.
+    ll. Provision for Section 1.1.
+    lll. Provision for 1.1.1.
+    lll. Provision for 1.1.2.
+    ll. Provision for Section 1.2.
+    lll. Provision for 1.2.1.
+    lll. Provision for 1.2.2.
+    ```
+
+### Step 2: (Optional) Fill out the YAML Front-Matter
+
+    ```yaml
+    ---
+    title: Wonderful Contract
+    author: Your Name
+    date: today
+    level-1: 1.
+    level-2: A.
+    level-3: a.
+    ---
+    ```
+
+### Step 3: Modify your reference.odt or reference.docx
+
+In Libreoffice you would modify your template reference.odt as you need it. You would go to Format -> Bullets and Numbering -> Options. 
+
+    1. First you would select Level 1 (on the left). In the Before field you would add "Article " (without the quotes, but not the space). In the After field you would add a period. In the Numbering field you would select 1, 2, 3, .... And in the Show sublevels field you would choose 1
+    2. Second you would select Level 2 (on the left). In the Before field you would add "Section " (without the quotes, but with the space). In the After field you would add a period. In the Numbering field you would select 1, 2, 3, .... And in the Show sublevels field you would choose 2.
+    3. Third you would select Level 3 (on the left). In the Before field you would add nothing (to accomplish the above desired output). In the After field you would add a period. in the Show sublevels field you would choose 3.
+    4. Lastly you would make sure that Consecutive Numbering (field at the bottom) was turned off. 
+    5. You can make sure that all the indenting is as desired in the Position Tab. 
+
+Then you would save the reference.odt as a new name perhaps contract-reference.odt in your Pandoc reference folder. 
+
+### Step 4: Run Legal-Markdown and Pandoc
+
+Make sure when you run Pandoc you use the new reference document that you created as the basis. 
+
+I do not use latex to create pdfs nor do I use Word, but the functionality will be similar with Word, and if you're using latex then you can figure out how to mirror this workflow.
+
+## A Few Gotchas
+
+You cannot begin the block of structured headers with a second level header. The gem searches the markdown to find a line that begins with `l.` where there is a blank line above it. This is made to be fairly precise so as to ensure that the gem does not strip out some other functionality that you want to build. 
+
+When you are using structured headers of legal_markdown you should make the lists tight. Do not add blank lines in between the list levels or the gem will think you are creating a new list. If you are trying to create a new list then by all means go ahead as the blank lines will break the parsing. 
+
+Also, if you use the reference.odt or reference.docx to override the default formating of the list then you do not need to add any level-1 or level-2 fields to the YAML front-matter. The best way to do it is to simply use the defaults that pandoc or your renderer will use and then use the reference styles to build the functionality that you would like. 
+
+# TODO
+
+[ ] - Definitions. For now these can be used as mixins but that functionality needs to improve.
+
+[ ] - Parsing. At this point legal_markdown cannot take a markdown document and parse it to build structured headers. Legal_markdown only works with a renderer to *create* documents but not to *import* documents. I want to build this functionality out at a later date. 
+
+# Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+# License
+
+MIT License - (c) 2012 - Watershed Legal Services, PLLC. All copyrights are owned by [Watershed Legal Services, PLLC](http://watershedlegal.com). See License file.
+
+This software is provided as is and specifically disclaims any implied warranties of fitness for any purpose whatsoever. By using this software you agree to hold harmless Watershed Legal Services and its Members for any perceived harm that using this software may have caused you. 
+
+In other words, don't be a jerk. 

data/Rakefile

@@ -0,0 +1,34 @@
+require "bundler/gem_tasks"
+
+# begin
+#   require "mg"
+#   MG.new("legal_markdown.gemspec")
+# rescue LoadError
+#   nil
+# end
+
+# desc "Build standalone script"
+# task :build => [ :standalone ]
+
+# desc "Build standalone script"
+# task :standalone => :load_legal_markdown do
+#   require 'legal_markdown/standalone'
+#   LegalMarkdown::Standalone.save('legalmd')
+# end
+
+# Rake::TaskManager.class_eval do
+#   def remove_task(task_name)
+#     @tasks.delete(task_name.to_s)
+#   end
+# end
+
+# # Remove mg's install task
+# Rake.application.remove_task(:install)
+
+# desc "Install standalone script"
+# task :install => :standalone do
+#   prefix = ENV['PREFIX'] || ENV['prefix'] || '/usr/local'
+
+#   FileUtils.mkdir_p "#{prefix}/bin"
+#   FileUtils.cp "legalmd", "#{prefix}/bin"
+# end

data/bin/legalmd

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+#
+# == USAGE
+#  legalmd file.md
+
+require 'legal_markdown'
+LegalMarkdown.execute(ARGV)

data/legal_markdown.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'legal_markdown/version'
+
+Gem::Specification.new do |s|
+  s.name              = "legal_markdown"
+  s.version           = LegalMarkdown::VERSION
+  s.date              = Time.now.strftime('%Y-%m-%d')
+  s.summary           = "Gem for parsing legal documents written in markdown for processing with legal specific requirements."
+  s.homepage          = "http://github.com/compleatang/legal-markdown"
+  s.email             = "caseykuhlman@watershedlegal"
+  s.authors           = [ "Casey Kuhlman" ]
+  s.has_rdoc          = false
+
+  s.files             = `git ls-files`.split($/)
+  s.executables       = s.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  s.test_files        = s.files.grep(%r{^(test|spec|features)/})
+  s.require_paths     = ["lib"]
+
+  #s.add_dependency ""
+
+  s.description       = <<desc
+  This gem will parse YAML Front Matter of Markdown Documents. Typically, this gem would be called with a md renderer, such as Pandoc, that would turn the md into a document such as a .pdf file or a .docx file. By combining this pre-processing with a markdown renderer, you can ensure that both the structured content and the structured styles necessary for your firm or organization are more strictly enforced. Plus you won't have to deal with Word any longer, and every lawyer should welcome that. Why? Because Word is awful. 
+desc
+end

data/lib/legal_markdown/version.rb

@@ -0,0 +1,3 @@
+module LegalMarkdown
+  VERSION = "0.1.1"
+end

data/lib/legal_markdown.rb

@@ -0,0 +1,135 @@
+#! ruby
+require 'yaml'
+require 'English'
+require "legal_markdown/version"
+
+module LegalMarkdown
+  extend self
+  def execute(*args)
+    # Get the Content & Yaml Data
+    data = load(*args)
+    parsed_content = parse_file(data[0])
+    # Run the Mixins
+    mixed_content = mixing_in(parsed_content[0], parsed_content[1])
+    #REMOVE THESE LATER
+    content = mixed_content[0]
+    yaml_data = mixed_content[1]
+    puts content
+    puts "What's left"
+    yaml_data.each{|k,v| puts "#{k}: #{v}"}
+  end
+
+  private
+  # ----------------------
+  # |      Step 1        |
+  # ----------------------
+  # Parse Options & Load File 
+  def load(*args)
+
+    # OPTIONS
+    # OPTS = {}
+    # op = OptionParser.new do |x|
+    #     x.banner = 'cat <options> <file>'      
+    #     x.separator ''
+
+    #     x.on("-A", "--show-all", "Equivalent to -vET")               
+    #         { OPTS[:showall] = true }      
+
+    #     x.on("-b", "--number-nonblank", "number nonempty output lines") 
+    #         { OPTS[:number_nonblank] = true }      
+
+    #     x.on("-x", "--start-from NUM", Integer, "Start numbering from NUM")        
+    #         { |n| OPTS[:start_num] = n }
+
+    #     x.on("-h", "--help", "Show this message") 
+    #         { puts op;  exit }
+    # end
+    # op.parse!(ARGV)
+
+    # # Example code for dealing with multiple filenames -- but don't think we want to do this.
+    # ARGV.each{ |fn| output_file(OPTS, fn) }
+
+    # Load Source File
+    source_file = File::read(ARGV[-1]) if File::exists?(ARGV[-1])
+    return[source_file, '']
+  end
+
+  # ----------------------
+  # |      Step 2        |
+  # ----------------------
+  # Load YAML Front-matter
+
+  def parse_file(source)
+    begin
+      yaml_pattern = /\A(---\s*\n.*?\n?)^(---\s*$\n?)/m
+      if source =~ yaml_pattern
+        data = YAML.load($1)
+        content = $POSTMATCH
+      else
+        data = {}
+        content = source
+      end
+    rescue => e 
+      puts "Error reading file #{File.join(ARGV[0])}: #{e.message}"
+    end
+    return[data, content]
+  end
+
+  # ----------------------
+  # |      Step 3        |
+  # ----------------------
+  # Mixins
+
+  def mixing_in( mixins, content )
+    mixins.each do | mixin, replacer |
+      replacer = replacer.to_s
+      safe_words = [ "title", "author", "date" ]
+      if replacer != "false"
+        pattern = /{{#{mixin}}}/
+        if content =~ pattern
+          content = content.gsub( pattern, replacer )
+          # delete the mixin so that later parsing of special mixins & headers is easier and faster
+          mixins.delete( mixin ) unless safe_words.any?{ |s| s.casecmp(mixin) == 0 }
+        end
+      end
+    end
+    return[content, mixins]
+  end
+
+  # ----------------------
+  # |      Step 4        |
+  # ----------------------
+  # Headers
+
+
+  #  Step 4a: Find the block starting and finishing lines
+
+
+  #  Step 4b: Set the alignment and the nesting structure
+
+
+  #  Step 4c: Set the requested list styling per the YAML front-matter
+
+
+  #  Step 4d: Pull out the ll. tags & strip the leading whitespace
+  #   but keep the proper nesting alignment.
+
+
+  # ----------------------
+  # |      Step 5        |
+  # ----------------------
+  # Special YAML fields
+
+
+  # Step 6: Strip the YAML front-matter
+
+
+  # Step 7: Write the file 
+
+
+  #   Step 7a: Where an output file was specified
+
+
+  #   Step 7b: Where an output file was not specified
+
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: legal_markdown
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- Casey Kuhlman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-18 00:00:00.000000000 Z
+dependencies: []
+description: ! "  This gem will parse YAML Front Matter of Markdown Documents. Typically,
+  this gem would be called with a md renderer, such as Pandoc, that would turn the
+  md into a document such as a .pdf file or a .docx file. By combining this pre-processing
+  with a markdown renderer, you can ensure that both the structured content and the
+  structured styles necessary for your firm or organization are more strictly enforced.
+  Plus you won't have to deal with Word any longer, and every lawyer should welcome
+  that. Why? Because Word is awful. \n"
+email: caseykuhlman@watershedlegal
+executables:
+- legalmd
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/legalmd
+- legal_markdown.gemspec
+- lib/legal_markdown.rb
+- lib/legal_markdown/version.rb
+homepage: http://github.com/compleatang/legal-markdown
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1250125497917414480
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 1250125497917414480
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Gem for parsing legal documents written in markdown for processing with legal
+  specific requirements.
+test_files: []