开源软件名称（OpenSource Name）：compleatang/legal-markdown开源软件地址(OpenSource Url)：https://github.com/compleatang/legal-markdown开源编程语言(OpenSource Language)：Ruby 100.0%开源软件介绍(OpenSource Introduction)：Legal Markdown
IntroductionThis gem will parse YAML Front Matter of Markdown and other Text Based Documents. It will work with more than only markdown. Typically, this gem would be called as a preprocessor to a primary renderer, such as Pandoc, that would turn the document outputed by Despite its name, Legal Markdown is not actually dependent upon markdown. It is agnostic in this regard. Indeed, it does not depend on markdown, or any of its flavors at all and should work with rst, latex, ascii or other text based documents. If it does not work with these types of documents please let me know via Github Issues and we'll try to work out a solution. MotivationThis gem was built specifically to empower the creation of structured legal documents using simple text based documents along with a primary renderer. This gem acts as a middle layer between document drafting and final document production by providing the user with access to structured headers, internal cross references, mixins, and other features that will greatly empower the use of text based documents to create and maintain structured legal documents. By combining this gem as a pre-processor along with a primary renderer, users are able to ensure that both the structured content and the structured styles necessary for their firm or organization are more strictly enforced. Plus users won't have to deal with Word any longer, and every lawyer should welcome that. Why? Because Word is awful. Note, in the coming versions, the gem will be able to output to specific legal versions of various structured documents which will not require a post-processor. See the milestones in the Github Issues Tracker for more information. How to Install This Gem?It is very simple. But first you must have
Once you have ruby installed then you simply go to your terminal and type: If you are looking to try out the gem, and you use Sublime Text as your text editor, then you can easily install my How to Use This Gem?After the gem has finished its installation on your system then you can go to your command line and type If you prefer to output as a different filename (which will allow you to keep the YAML front-matter), then you simply type If you have been working on a template or document and would like the gem to build the YAML Front-Matter (see below) automatically for you, then simply type If you would like to output to If the gem is not outputting as you think it should then you can debug the output by typing All these commands are available from within ruby as well if you would prefer to call them programmatically. The headers command is called with YAML Front-MatterYAML is easy thing to create. At the top of your file (it MUST be at the top of the file) you simply put in three hyphens like so: ---
party1_address: "Muj Axmed Jimcaale Road, Hargeisa, Republic of Somaliland"
party1_full: "Watershed Legal Services, Ltd."
party1_reg: the Republic of Somaliland
party1_rep: "# Casey Kuhlman"
party1_short: "(\"Watershed\")"
party1_type: private company limited by shares
---Note: YAML can be quite testy, so if you use any symbols or parentheses or square brackets, etc. just put the entire field inside of double quotes ("). Also, if you need double quotes within the value then you "escape" them by putting a backslash before the double quotes as shown above. If you need to use a backslash (for instance if you are using latex), then you would escape the backslash by putting two backslashes. If you use the automatic YAML population feature of the gem, it will handle this escaping for you. MixinsMixins are simple markers that can be used throughout the text to identify certain things (Court) or (Company) or (Client) to identify a few. The example above is the YAML Front Matter for mixins. This allows for the creation and utilization of templates that can be reused by simply updating the YAML front-matter and leaving the main text of the template largely untouched. Mixins are structured in the form of double curly brackets. So, for a court: Regional Court of HargeisaIf you do not want a mixin turned on for a particular document just add the mixin in the YAML Frontmatter and then leave it blank, the gem will take it out of the text along with any extraneous spaces. If you have a mixin within the body of your document, but not within the YAML front matter, then the gem will leave the mixin as is -- which is unlikely the result you want to achieve. Optional Clauses FunctionWhen building templates for contracts, you often build optional clauses or clauses that are mutually exclusive to one another. This functionality is supported by legal_markdown. Here is how to build an optional clause. In the body of your document you put the entire clause in square-brackets (as you likely normally would) and at the beginning of the square bracket you put a mixin title for the optional clause. In the YAML Front-Matter you simply add You are able to nest optional clauses inside of other optional clauses. However, if you do so, make sure that you include all of the sub-provisions of the master provision in the YAML matter, else the gem will think that you closed your square brackets earlier than you would like it to. If you use the automatic YAML population feature either from the command line (see above) or by using the Sublime package, it will simplify this process for you greatly. Another thing to note, if you include nested provisions, you can turn off an inside provision and leave an outside provision on, but if you turn off an outside provision the entire portion will not be produced, even if you turned an inner portion on. Usually, as long as you keep this rule in mind you can draft around it, and it is generally the case that that will be the result that you will want any way. So, this is how the body of the text would look. Then the YAML Front Matter would look like this my_optional_clause: trueor my_optional_clause: falseI don't know why you would ever write such a clause, but that is why the functionality exists! Structured HeadersWhen 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 styles and limitations for working with ordered lists and each user of even the same word processor has different defaults. In order to address this problem, I have built functionality into legal_markdown that gets addresses this problem. Here is how structured headers work in the gem. Wherever you wish to start a block of structured headers just put in At the beginning of the line you simply type the level in which the provision resides by the number of lowercase l's (for level) 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 When the gem parses the document it will automatically add and reset each level in the tree that you set up based on the criteria you establish. In the YAML front-matter you will describe the output functionality you need to see by adding the levels by:
Obviously you will replace In addition to the reference portion of the structured header, you can add in whatever text you wish. For example, if you want the top level to be articles with a number and then a period, the next level down to be sections with a number in parentheses, and the next level down to be a letter in parentheses then this is what the YAML front matter would look like. ---
level-1: Article 1.
level-2: Section (1)
level-3: (a)
---Also, you can start on any number or letter you wish. So if you want the first article to be Note. If you do not start with the default numbering/lettering you should likely turn off the reset function for that level (see below) or else when the gem is parsing the document it will reset the level based on the default numbering/lettering rather than the initial numbering/lettering you established. Also, be careful if you want to start with letters that also match with Roman Numerals (I, V, X, L, C, D, M) whether upper or lower case as the gem parses Roman's before letters. If you want a sequence similar to (a), (b), ... but you put in (c) as the starting point the gem will default to the lowercase version of the Roman Numeral C (100). No Reset FunctionSometimes in legal documents (particularly in laws) you want to build multiple structured header levels, but you do not want to reset the headers when you are going up the tree. For example, in some laws you will have Chapters, Parts, Sections, ... and you will want to track Chapters, Parts and Sections but when you go up to Parts you will not want to reset the Sections. This functionality is built in with a no-reset: l., ll., lll.This will not reset level-1, level-2, or level-3 when it is parsing the document and those levels will be numbered sequentially through the entire block rather than reseting when going to a higher block, levels not in this reset, e.g., llll. and lllll. will be reset when going up a level in the tree. Obviously the level 1 headers will never reset because levels only reset when going a level higher and there is no level 0. No Indent FunctionYou may want to keep some of the header levels tight to the margins. This functionality is built into legal_markdown with a Titles and Text or ProvisionsSometimes you want to have a title on one line and then some text on the next line all referencing the same provision. This is simple to achieve in a ExamplesThe syntax should be straight-forward. If you learn by seeing rather than by reading, take a look at the Watershed Let us say you wanted to output a document that looks like this: 1. Provision for Article 1.
1. Provision for Section 1.1.
1. Provision for 1.1.1.
2. Provision for 1.1.2.
2. Provision for Section 1.2.
1. Provision for 1.2.1.
2. Provision for 1.2.2.You can easily to that by doing the following steps. Step 1: Type the bodyStep 2(a): Fill out the YAML Front-Matter with the Base References you want---
level-1: 1.
level-2: 1.
level-3: 1.
---Step 2(b): (Optional) Add any additional text before the Base ReferenceTo output the document above, we need to be able to add the words Article and Section before the Base Reference. This is trivial. You just add those words into the YAML front matter before the base reference. Note. The gem looks at the last block of characters in the level-X YAML field to understand what type of Base Reference you need for your document. So you cannot add additional text after the Base Reference. If the headers looked like this: ---
level-1: Article 1.
level-2: Section 1.
level-3: 1.
---Then the output would look like this: Article 1. Provision for Article 1.
Section 1. Provision for Section 1.1.
1. Provision for 1.1.1.
2. Provision for 1.1.2.
Section 2. Provision for Section 1.2.
1. Provision for 1.2.1.
2. Provision for 1.2.2.Step 2(c): (Optional) Add Precursors to HeadersTo output the document above, we need to be able to call the reference of the level above (also the level above that in the case of the above example). Legal Markdown allows for this with the precursor function. To reference the level above in your reference, you will modifiy the YAML front matter. In the YAML front matter you add any word or other marker before the precursor trigger. If you want to reference the preceding level (like 1.1.1 in the example above) then simply put in If the headers looked like this: ---
level-1: Article 1.
level-2: Section pre 1.
level-3: pre 1.
---Then the output would 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.Step 2(d): (Optional) Add Another Type of Precursors to HeadersSometimes, particularly in laws, the structure is something akin to Chapter 1 and then Section 101, Section 102, ... Chapter 9, Section 901, Section 902, etc. You can easily adopt this structure to your document by using the ---
level-1: "# Chapter 1."
level-2: "## Section preval 1."
level-3: pre(a)
no-indent: l., ll.
---This would output (using the same text from the body of the document typed in step 1) as: # Chapter 1. Provision for Article 1.
## Section 101. Provision for Section 1.1.
101(a) Provision for 1.1.1.
101(b) Provision for 1.1.2.
## Section 102. Provision for Section 1.2.
102(a) Provision for 1.2.1.
103(b) Provision for 1.2.2.
...
## Section 110. Provision for Section 1.10.
110(a) Provision for 1.10.1.
110(b) Provision for 1.10.2.Step 3: Run Legal-Markdown and Primary ProcessorYou can do this via the command line or via the Sublime Text package. Or, if you are really adventurous make a package for your text editor! Other FeaturesI find, particularly when I'm working with contracts and templates that I needed a few more features than those detailed above. Working with Cross Reference Provisions.Often we need the ability to cross reference between provisions where the text of Section 16 refers back to Section 12. When you're working with templates you may turn on or off provisions after reviewing a draft with a client and so you may not know if the reference point will be Section 12 or 14 in the final document. Also when you're working in a Cross references only work within structured headers blocks. They do not work outside of that block. To use cross references, you simply place a reference key (which you can make up and remember, it can contain letters, numbers, or symbols) within pipes "|" (shift + the key above the enter key on US keyboards). First "stake" the cross reference to the provision which you want to reference to. Stakes should go directly after the ll., and before the text of the provision. Then other provisions within the structured headers block can refer to it (either before or after the reference point within the document). Referencing provisions can utilized the cross references whereever is appropriate for the text. Note, cross references will use the entire replacement field so if you have leading text, pre, or preval utilized these will be brought into the cross reference within the text of the referencing provision. For example, if the YAML front matter looked like this: ---
level-1: "# Article 1."
level-2: "Section 1."
level-3: (a)
no-indent: l., ll.
---and the body of the text looked like this: the output would look like this: Section 7. This provision will need to be referenced later.
Section 8. Provision
(a) As stated in Section 7, whatever you need to say.Working with PartialsWhen work with templates it is nice to be a bit more DRY (don't repeat yourself). In order to help with this, legal_markdown has a built in partials feature. Probably not a lot of people will use this, but here is how you do it. Let's say you put your standard interpretation, notice, severance, boilerplate typically at the end of the contract just before the signature block. Let's also assume that you have multiple contract templates and they all mostly use the same boilerplate final provisions. If you were lawyering like coders think then you would abstract these provisions into their own file within your contracts templates folder. Then you would have all of your templates reference back to that partial. Later, if there is some change in the law you would just go into the partial, make the necessary change in order to adapt your template based on the change, and then all of your templates which refer to that partial will be automatically updated. A bit more simple then updating each and every one of your templates, eh? Partials are simple. They use the Note. If you use relative directories, you will need to cd into the directory where the base file is before calling legal_markdown from the command line. If that is a hassle, then you can use absolute and call from whereever you like. I use partials as an easy way to get at my templates. Generally, I build my templates without the YAML front matter added (they have been added in to the Watershed templates only for demonstration purposes). When I want to use a specific template for a specfic client what I do is open a blank document within that client's folder and type If the document will require changes to the template because it is an unusual transaction or overly complex situation then I'll copy the template into the client folder, build the YAML front matter, make the necessary changes to the document, then output. Mostly, though, I use the Working with Document Meta Data / InformationBy default, when outputting a text based system via If you need to add some metadata to your document (say the title and author of the document which your primary processor will utilize in some way) then you would add the following into the YAML front matter: ---
meta:
title: My Title
author: ME
---Note. The fields within the meta are indented. The remainder of your YAML front matter should not be indented except for the meta fields. Calling ---
meta-yaml-output:
title: My Title
author: ME
meta-json-output:
title: My Title
author: YOU
---Note. The general For example: ---
meta:
title: My Title
meta-yaml-output:
title: Your Title
---will output Another example: ---
meta:
title: My Title
meta-yaml-output:
author: ME
---will output If you are using this feature with pandoc, you will have to turn on the If you are very adventurous and reading the code you will see that a Alternative Header SyntaxIt can be a pain to count whether you are on level 5 or level 6 for a very complex document with multiple levels. To address this situation, legal_markdown has an alternative header syntax besides the l., ll., lll. syntax. The alternative syntax uses l1., l2., l3., l4., ... for level-1, level-2, etc. To use this syntax throughout your document you simply type in l1., l2., etc. into the body of your document, then you will also use that syntax for the no-reset and no-indent functions. Lastly, make a DateWhen you are building documents sometime you simply want to put CitationsAt this point legal_markdown does not have a native citation handling ability. For now, I've outsourced that to the primary processor. If you look at pandoc, it has excellent bibtex and citation support that will bluebook up everything for you. Legal Markdown does not get in the way of how pandoc does citations so it is fully compatible. A Few Gotchas
|
