mandown 0.0.7 → 0.0.8

data/bin/mandown-sample

@@ -0,0 +1,124 @@
+# Please note that the copyright of the manuscript is owned by The PLoS
+# Medicine Editors and their work is licensed according to the Creative
+# Commons Attribution License.
+
+def sample
+<<END
+Lethal Injection Is Not Humane
+==============================
+
+The PLoS Medicine Editors
+
+Citation: The PLoS Medicine Editors (2007) Lethal Injection Is Not Humane. PLoS Med 4(4): e171 doi:10.1371/journal.pmed.0040171
+
+Published: April 24, 2007
+
+Copyright: © 2007 The PLoS Medicine Editors. This is an open-access article distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited.
+
+E-mail: medicine_editors@plos.org
+
+This month's issue of PLoS Medicine contains a research article on three protocols used in lethal injection, the current method of execution for most US states. Despite the British Royal Commission on Capital Punishment advising against lethal injection half a century ago cite:Emanuel, the United Nations General Assembly affirming the desirability of abolishing the death penalty in 1971, and the European Union explicitly banning the death penalty in all circumstances cite:EU, execution—predominantly by lethal injection—is still practiced in many countries. During 2005 at least 2,148 people were executed in 22 countries in cases recorded by Amnesty International; the actual numbers were certainly higher. The majority of these executions took place in China, where fleets of mobile execution vans have been deployed to facilitate prompt, low-profile executions by lethal injection. Iran, Saudi Arabia, and the US together with China accounted for 94% of executions in 2005 cite:AmInt.
+
+Following its introduction to the US in 1982, lethal injection became the primary method of execution there, largely replacing execution by hanging, firing squad, gas chamber, and electrocution. Each of these older methods has come to be seen as inhumane or excessively violent by most states, but each remains an option in a handful of others. Of the 53 executions in the US in 2006, all but one (an electrocution) were carried out using lethal injection cite:DPIC.
+
+In recent months, concerns over botched lethal injections have put the method on hold in a dozen or so of the 36 US states that have the death penalty. Following a particularly agonizing execution in December 2006, the US District Court ruled that California's lethal injection protocol was unconstitutional. The governors of Florida and Tennessee suspended executions pending review of their states' lethal injection protocols. A court ruling in December 2006 suspended Maryland's executions, and New Jersey is considering an outright ban on its death penalty following a 2004 court order requiring the state to justify its lethal injection process. Executions are on hold in several other states pending legal proceedings cite:DPIC.
+
+In this context, the editors of PLoS Medicine believe it is timely to publish a research article reporting shortcomings of lethal injection protocols. Strictly speaking, this article has little to do with medicine. Execution by lethal injection, even if it uses tools of intensive care such as intravenous tubing and beeping heart monitors, has the same relationship to medicine that an executioner's axe has to surgery. Nonetheless, there is a need for greater openness in public discussion and consideration of the death penalty, including its unpalatable details.
+
+Challenges to the constitutionality of lethal injection have thus far been based largely on accounts of suffering resulting from unskilled administration. The American Medical Association, the American Nurses Association, the Society of Correctional Physicians, and a number of state medical boards have banned as unethical any causative role for medical professionals in executions cite:Gawande. Accordingly, in lethal injection procedures intravenous access has often been attempted (with frequent failures) by untrained staff, the execution mixture has precipitated and blocked IV tubes, and lethal doses have been unreliably calculated cite:Koniaris. Anesthesia has failed, chemical burns have occurred, and suffering has proceeded for 30 minutes or longer. Although this suffering might be seen as a consequence of professional refusal to participate in executions, this refusal also appears to be one of the primary forces motivating reexamination of lethal injection by the courts.
+
+The current article by Koniaris and colleagues gives further cause for concern by questioning whether, even if “perfectly” administered, the protocols would achieve their stated aim of causing death without inflicting inhumane punishment. The authors analyzed several cases from three states: California, North Carolina, and Virginia. (Texas, the state with the largest number of lethal injections, does not release data from executions.) These lethal injection protocols use the barbiturate thiopental (intended to sedate and to suppress breathing), the neuromuscular blocker pancuronium (which paralyzes, causing respiratory arrest but also preventing agonal movements that might indicate suffering), and the electrolyte potassium (intended to cause cardiac arrest). Such protocols are intended to provide redundancy, such that each drug is given at a dose that would by itself cause death. However, in analyzing data from actual executions, Koniaris and colleagues report that thiopental and potassium do not consistently result in death. In fact, individuals undergoing execution have continued to breathe after the injection of thiopental, and their hearts have continued to beat following injection of potassium; in these cases, the authors conclude, it is quite likely that those being executed have experienced asphyxiation while conscious and unable to move, and possibly an intense burning pain throughout the body from the potassium injection.
+
+Each of the editors of PLoS Medicine opposes the death penalty. It is not our intention to encourage further research to “improve” lethal injection protocols. As editors of a medical journal, we must ensure that research is ethical, and there is no ethical way to establish the humaneness of procedures for killing people who do not wish to die. Human research to further the ends of governments at the expense of individual lives is an obvious violation of the Declaration of Helsinki, which was conceived largely in response to the atrocities of Nazi “medicine” in order to articulate an international standard for ethical human experimentation cite:WMA. Whatever local law might say in a given place and time, no ethical researcher would propose a study to establish such procedures, no ethical reviewers would approve it, and no ethical journal would publish it. The acceptability of lethal injection under the US Constitution's Eighth Amendment ban on inhumane punishment has never been established; the data presented by Koniaris and colleagues adds to the evidence that lethal injection is simply the latest in a long line of execution methods that have been found to be inhumane. It is time for the US to join the majority of countries worldwide in recognizing that there is no humane way of forcibly killing someone.
+
+Apart from the issue of whether humane execution can exist, we must also consider the accuracy of convictions resulting in death sentences. Execution of wrongfully sentenced individuals is obviously unacceptable, yet between 1973 and 2004 in the US, 118 prisoners who had been sentenced to death were later released on grounds of innocence cite:AmInt2. Of 197 convictions in the US that were subsequently exonerated by DNA evidence, 14 were at one time sentenced to death or served time on death row cite:InProj. Racial bias in sentencing likely accounts for much of this error; more than half of the exonerees were African Americans, and the rate of death sentences in the US among those convicted of killing a white victim is considerably higher than for murderers of blacks. Given this potential for fatal error, how can any objective person support the death penalty, which allows for no correction?
+
+We support the recent decision of Craig Watkins, the new district attorney of Dallas, Texas, to examine hundreds of cases over the past 30 years to see whether DNA tests might reveal wrongful convictions cite:McGonigle. Such errors are inevitable when an implicit goal of sentencing, and particularly of imposing the death penalty, is not rational but emotional: the desire for revenge. As one law professor stated in a recent New York Times Magazine article on lethal injection, “Retribution, the conscious affliction of pain and suffering because and only because some people deserve it, is the essence of punishment” cite:Weil. But if the personal satisfaction of seeing criminals “get what they deserve” really reflects the intentions of Americans, why has the US seen a transition away from firing squads, hanging, or even drawing and quartering? Why was capital punishment illegal for a decade until it was reinstated by a Supreme Court ruling in 1976? Why have some US states rejected the death penalty completely, and others suspended its use? Why has the US followed the course associated with totalitarian states and rejected by other democracies in this matter?
+
+Clearly, the death penalty is a matter of profound ambivalence in American society. Courts and state governments are saying that if capital punishment exists, it must not be cruel or visibly violent. Physicians and nurses are saying that their involvement in executions is below any acceptable conception of professional ethics. How to reconcile the needs of a society given to vengeance but outwardly abhorrent of cruelty or violence, trusting of medical science's trappings but indifferent to their use in killing, expecting the highest ethics of its physicians but willing to medicalize the execution chamber? The new data in PLoS Medicine will further strengthen the constitutional case for the abandonment of execution in the US. As a moral society, the US should take a leading role in the abandonment of executions worldwide.
+
+# Bibliography
+
+Emanuel:
+  authors:  Emanuel, L L & Bienen, L B
+  title:    Physician participation in executions (editorial)
+  journal:  Ann Intern Med
+  volume:   135
+  pages:    922--924
+  year:     2001
+
+EU:
+  organization:  European Union
+  title:    The EU's human rights & democratisation policy
+  url:      http://ec.europa.eu/comm/external_relations/human_rights/adp/index.htm
+  accessed: 19 March 2007
+
+AmInt:
+  organization:  Amnesty International
+  title:    Facts and statistics on the death penalty
+  url:      http://web.amnesty.org/pages/deathpenalty-statistics-eng
+  accessed: 19 March 2007
+  year:     2007
+
+DPIC:
+  organization:  Death Penalty Information Center
+  title:    Seaerchable database of executions
+  url:      http://www.deathpenaltyinfo.org/executions.php
+  accessed: 19 March 2007
+  year:     2007
+
+Gawande:
+  authors:  Gawande, A
+  title:    When law and ethics collide---Why physicians participate in executions  
+  journal:  New Engl J Med
+  volume:   354
+  pages:    1221--1229
+  year:     2006
+
+Koniaris:
+  authors:  Koniaris, L G & Zimmers, T A & Lubarsky, D A & Sheldon, J P
+  title:    Inadequate anaesthesia in lethal injection for execution
+  journal:  Lancet
+  volume:   365
+  pages:    1412--1414
+  year:     2005
+
+WMA:
+  organization:  World Medical Association
+  title:    Policy Statement
+  url:      http://www.wma.net/e/policy/b3.htm
+  accessed: 19 March 2007
+  year:     2007
+
+AmInt2:
+  organization:  Amnesty International
+  title:    'The death penalty worldwide: Developments in 2004'
+  url:      http://web.amnesty.org/library/Index/ENGACT500012005
+  accessed: 19 March 2007
+  year:     2005
+
+InProj:
+  organization:  The Innocence Project
+  title:    Facts on post-conviction DNA exonerations
+  url:      http://www.innocenceproject.org/Content/351.php
+  accessed: 19 March 2007
+
+McGonigle:
+  authors:  McGonigle, S
+  title:    Innocence Project to review Dallas County convictions
+  journal:  The Dallas Morning News
+  url:      http://www.dallasnews.com/sharedcontent/dws/dn/latestnews/stories/021607dnmetinnocence.179e9f3.html
+  accessed: 19 March 2007
+  year:     2007
+
+Weil:
+  authors:  Weil, E
+  title:    The needle and the damage done
+  journal:  New York Times (Magazine)
+  url:      http://www.nytimes.com/2007/02/11/magazine/11injection.t.html?ex=1328850000&en=98538f95b199b74e&ei=5088&partner=rssnyt&emc=rss
+  accessed: 19 March 2007
+  year:     2007
+END
+end
+
+STDOUT.puts(sample)

data/lib/bibdown_lib.rb

@@ -0,0 +1,537 @@
+#################### License ###################################################
+# 
+# Copyright (c) 2008 Chris Rose
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+# 
+################################################################################
+
+require 'yaml'
+
+# Define the text that is displayed when the user asks for documentation
+def documentation
+<<END
+
+
+  bibdown --- part of the Mandown set of tools.
+  
+  bibdown processes standard input, builds a bibliography from a YAML-format set 
+  of references and inserts citation keys.
+  
+  Copyright © 2008 Chris Rose. 
+  Distributed according to the GNU General Public License.
+  
+  Usage:
+  ------
+  cat infile.txt | bibdown > outfile.txt
+  
+  Syntax:
+  -------
+  
+  Place references at the end of your Markdown file in a level 1 section 
+  called 'Bibliography' using the exact string '# Bibliography' (as given in the 
+  example below). Cite references in your text using 'cite:MyKey', where 'MyKey' 
+  is a key to one of your references. Keys may contain any characters, but end 
+  with a space character (i.e. 'cite:SomeKey' refers to the key 'SomeKey', while 
+  'cite:Some Key' refers to the key 'Some').
+  
+  ------------------------------- Example -------------------------------------
+  ...
+  This is some text that needs to cite the very important work of Jones and 
+  Smith cite:Jones.
+  ...
+  
+  # Bibliogrqaphy
+  
+  Jones:
+    authors:  Jones, Bob & Smith, Fred J.
+    title:    Spaghetti-Wall Interactions
+    journal:  Am. J. Pasta Phys.
+    volume:   3
+    number:   2
+    month:    January
+    year:     2008
+    pages:    111--112
+    note:     In press.
+  ------------------------------- End of example ------------------------------
+  
+  Suppoted fields:
+  ----------------
+  
+  The following fields are supported by bibdown and all are optional; you may 
+  use other arbitrarily-named fields, but they will be ignored (by this version 
+  of bibdown, at least).
+  
+  authors -- Use 'surname, first names' format; separate authors with '&'.
+      e.g. "Einstein, Albert & Bohr, Neils"
+  organization -- Use if the publication is authored by an organization.
+      e.g. "Amnesty International"
+  title -- The title of the reference.
+      e.g. "Some Clever Stuff on Quantum Physics"
+  journal -- The name of the journal; this field causes the reference to be 
+             treated as an article in a journal.
+      e.g. "Int. J. Quan. Phys."
+  conference -- The name of the conference; this field causes the reference to 
+                be treated as a paper in a conference proceedings.
+      e.g. "Medical Image Understanding and Analysis"
+  booktitle -- The title of a book; this field causes the reference to be 
+               treated as a book.
+      e.g. "Moby Dick"
+  chapter -- The chapter in a book being cited; only valid for references 
+             that use the booktitle field.
+      e.g. "4"
+  edition -- The edition of a book being cited; only valid for references 
+             that use the booktitle field.
+      e.g. "5"
+  editors -- The editors of a book being cited; only valid for references 
+             that use the booktitle field.
+      e.g. "Harris, Thomas & Hopper, Dennis"
+  isbn -- The ISBN number of a book being cited; only valid for references 
+          that use the booktitle field. 
+      e.g. "9783540356257"
+  month -- The month of publication.
+      e.g. "January"
+  volume -- The volume of the publication being cited.
+      e.g. "2"
+  number -- The number/issue of the journal article being cited; only valid for 
+            references that use the journal field.
+      e.g. "2"
+  pages -- The pages in the publication being referred to.
+      e.g. "201--211"
+  series -- The series the book being cited belongs to; only valid for 
+            references that use the booktitle field.
+      e.g. "Mathematical Statistics"
+  url -- A URL for the publication being cited.
+      e.g. "http://www.something.com/somedocument"
+  accessed -- The date the URL was accessed (note: do not use this field without 
+              also including a URL).
+      e.g. "28 January 2008"
+  year -- The year the publication being cited was published.
+      e.g. 2008
+  note -- Any notable comment about the publication being cited.
+      e.g. "In press."
+  
+  
+  Notes:
+  ------
+  
+  You must use soft tabs (emulated using spaces) in the bibliography. If you 
+  need to include a colon in the reference (e.g. in the title field), you 
+  will need to surround the field entry in quotes (e.g. "title:  'Gnocci: nasty 
+  or nice?'").
+  
+  If you are going to process the resulting file (outfile.txt, in the usage 
+  example given above), you may wish to use a double-dash for page ranges 
+  (and be sure to use the 'smart typography' mode of Pandoc)---see the example 
+  above.
+  
+  See also:
+  ---------
+  
+  Markdown -- http://daringfireball.net/projects/markdown/
+  Pandoc   -- http://johnmacfarlane.net/pandoc/
+  
+END
+end
+
+
+# Given a symbol identifying a part of a citation (e.g. :journal), return the
+# separator string that should follow it (e.g. a '. ' follows the name of the
+# journal). (Note: include any following space!)
+def get_sep(part)
+  sep = case part
+    when :authors, :organization, :title, :booktitle, :isbn, :series, :accessed, :year
+      '. '
+    when :journal, :conference, :chapter, :edition, :pages, :url
+      ', '
+    when :editors
+      ', editors. '
+    when :month, :note
+      ' '
+    when :number, :volume
+      ''
+  end
+  
+  sep
+end
+
+# Define a function that takes a string and returns that string marked as being of :normal (upright) or :italic using Markdown notation.
+def markdown_format(string, style)
+  case style
+    when :normal: string
+    when :italic: '*' + string + '*'
+  end
+end
+
+# Define a function to render a string as normal using Markdown notation.
+def r_norm(string)
+  markdown_format(string, :normal)
+end
+
+# Define a function to render a string as italic using Markdown notation.
+def r_ital(string)
+  markdown_format(string, :italic)
+end
+
+
+# Given a bib entry (a hash that maps the parts of a reference to the content
+# for that reference), construct a string that can be used in a paper as the
+# bibliographic entry for that entry. Also return information that can be used
+# to sort the bibliography (first author surname, publication year). Also
+# return the key that was used in the text to refer to this citation. Return a
+# hash with fields :reference (containing the reference), :sort_info and :key.
+# :sort_info is a hash with fields :surname and :year.
+#
+# See the documentation string above for details on what fields are supported
+# and how they should behave.
+def make_bib_entry_string(bib_entry, key)
+  # We'll encode the order in which the parts of the reference appear for the
+  # three types of reference in three arrays; we'll associate these arrays
+  # with symbols that specify the reference type.
+  order = {
+    :journal =>
+      [:authors, :organization, :title, :journal, :volume, :number, :pages,
+        :month, :year, :url, :accessed, :note],
+    :conference =>
+      [:authors, :organization, :title, :conference, :editors, :volume, :pages,
+        :month, :year, :isbn, :url, :accessed, :note],
+    :book =>
+      [:authors, :organization, :editors, :booktitle, :series, :edition,
+        :volume, :chapter,  :pages, :month, :year, :isbn, :url, :accessed,
+        :note]}
+  
+  # Cope with the misc type.
+  order[:misc] = order[:journal]
+
+  # Use an associative array to specify how each part of a citation should be
+  # styled. We map from the parts to functions which perform the required
+  # styling.
+  styles = {:authors => proc {|x| r_norm(x)},
+   :organization => proc {|x| r_norm(x)}, :title => proc {|x| r_norm(x)},
+   :journal => proc {|x| r_ital(x)}, :conference => proc {|x| r_ital(x)},
+   :booktitle => proc {|x| r_ital(x)}, :chapter => proc {|x| r_norm(x)},
+   :edition => proc {|x| r_norm(x)}, :editors => proc {|x| r_norm(x)},
+   :isbn => proc {|x| r_norm(x)}, :month => proc {|x| r_norm(x)},
+   :note => proc {|x| r_norm(x)}, :number => proc {|x| r_norm(x)},
+   :pages => proc {|x| r_norm(x)}, :series => proc {|x| r_norm(x)},
+   :url => proc {|x| r_norm(x)}, :accessed => proc {|x| r_norm(x)},
+   :volume => proc {|x| r_norm(x)}, :year => proc {|x| r_norm(x)}}
+   
+  # Make a copy for later, as we alter the original bib_entry object.
+  org_bib_entry = bib_entry.clone
+      
+  # Make the author string and replace the entry in the bib_entry with the
+  # formatted version. Do similarly with the editors.
+  bib_entry['authors'] = 
+    make_author_string(bib_entry['authors']) if !bib_entry['authors'].nil?
+  bib_entry['editors'] = 
+    make_author_string(bib_entry['editors']) if !bib_entry['editors'].nil?
+  
+  # See if we're making a journal article, conference paper or book reference.
+  ref_type = :journal unless bib_entry['journal'].nil?
+  ref_type = :conference unless bib_entry['conference'].nil?
+  ref_type = :book unless bib_entry['booktitle'].nil?
+  if !(defined? ref_type) || ref_type.nil?
+    ref_type = :misc
+    STDERR.puts('Note: Reference type not found for reference ' + key)
+  end
+  
+  # Get the order for the type of entry we're dealing with.
+  order = order[ref_type]
+  
+  # Iterate over the parts of the citation for this type of reference and
+  # build the bibliography entry.
+  bib_entry_string = ''
+  order.each do |part_name|
+    # Construct the part of the entry for the given part_name, taking into
+    # account the fact that some parts need to be formatted in certain ways.
+    if bib_entry[part_name.to_s] # If there is an entry for this part name...
+      part = bib_entry[part_name.to_s].to_s
+    else
+      part = ''
+    end
+    
+    # Format the part of the reference using the appropriate style.
+    part = styles[part_name].call(part)
+    
+    part = case part_name
+      when :authors, :organization, :booktitle, :isbn, :series, :year
+        part + '. '
+      when :title
+        # Only add an '.' if doesn't already end with a punctuation character.
+        if /[[:punct:]]$/.match(part): part + ' '
+        else part + '. '
+        end
+      when :conference
+        'In proc. ' + part + ', '
+      when :journal, :conference, :chapter, :edition
+        part + ', '
+      when :editors
+        part + ', editors. '
+      when :month
+        part + ' '
+      when :volume
+        part
+      when :number, :note
+        '(' + part + ')'
+      when :pages
+        if ref_type == :journal
+           ':' + part + ', '
+        elsif ref_type == :conference || ref_type == :book
+           'pp' + part + ', '
+        end
+      when :url
+        'Available at: ' + part
+      when :accessed
+        ', accessed ' + part + '. '
+      else
+        part
+    end
+    
+    bib_entry_string += part if bib_entry[part_name.to_s]
+  end
+  
+  # Make sure the bib_entry_string ends with a punctuation character,
+  # appending a full stop if it doesn't.
+  bib_entry_string.strip!
+  bib_entry_string += '.' unless /[[:punct:]]$/.match(bib_entry_string)
+  
+  # Get the surname for sorting purposes. Use the author as first preference
+  # if it is available, otherwise use the organisation, otherwise use a sort
+  # surname that will place it last.
+  sort_surname = 'ZZZ' # The default if we can't find something better.
+  sort_surname = 
+    org_bib_entry[:organization] if !bib_entry['organization'].nil?
+  sort_surname = 
+    get_first_author_surname(org_bib_entry) if !bib_entry['author'].nil?
+  
+  
+  # Make the hash to return.
+  { :reference => bib_entry_string,
+    :key => key,
+    :sort_info => {:surname => sort_surname, :year => bib_entry['year']}}
+end
+
+# Return the surname of the first author in lowercase.
+def get_first_author_surname(bib_entry)
+  make_author_string(
+    bib_entry['authors'], true, true).split[0][0..-2].downcase
+end
+
+
+# Given a string of the form 'Chris James' turn it into a string of the form 'C. J.'
+def make_initials(firstnames)
+  firstnames = firstnames.split(' ')
+  firstnames.each_index do |i|
+    firstnames[i] = firstnames[i][0].chr + '.'
+  end
+end
+
+# Given a string of the form 'Rose, Chris & Jones, Bob', make an authors
+# string that can be placed in the bibliography.
+#
+# use_initials specifies whether the full firstnames are used, or whether
+# initials are used instead.
+#
+# surname_first specifies whether the author surnames should appear before
+# their first names or initials.
+def make_author_string(authors, use_initials=true, surname_first=false)
+  # Strip out the individual authors and remove leading and trailing
+  # whitespace, and split each into surname and firstnames.
+  authors = authors.split('&')
+  authors.each_index do |i|
+    authors[i].strip!
+    authors[i] = authors[i].split(',')
+    authors[i][0].strip!
+    authors[i][1].strip!
+  end
+  
+  # If we have to use first initials for the first names, then make them.
+  if use_initials
+    authors.each_index do |i|
+      authors[i][1] = make_initials(authors[i][1])
+    end
+  end
+
+  # Now make the authors string.
+  authors_string = ''
+  authors.each_index do |i|
+    # Get a string for the forename(s) for the i-th author.
+    this_forenames = ''
+    authors[i][1].each do |name_or_initial|
+      this_forenames += name_or_initial + ' '
+    end
+
+    # Concatenate the forename(s) and surname in the appropriate order.
+    if surname_first
+      authors_string += authors[i][0] + ', '
+      authors_string += this_forenames.rstrip
+    else
+      authors_string += this_forenames
+      authors_string += authors[i][0] 
+    end
+    authors_string += ', ' unless i == authors.length-1 or i == authors.length-2
+    authors_string += ' and ' if i == authors.length-2
+  end
+  
+  authors_string.strip! # Remove leading and trailing whitespace.
+  authors_string # Return the authors string.
+end
+
+
+# Given an array of bib_entries, each made using the make_bib_entry_string
+# function, sort this array according to first author surname, or year of
+# publication, or by the order in which the papers were cited in the text.
+#
+# keys_in_order must be an array containing the keys used in the text, in the
+# order the keys appear in the text, without repetition. by must be one of
+# :surname, :year or :order_in_text
+def sort_bib_entries(bib_entries, keys_in_order, by = :surname)
+  case by
+  when :surname, :year
+    bib_entries.sort {|x,y| x[:sort_info][by] <=> y[:sort_info][by]}
+  when :order_in_text
+    to_return = []
+    keys_in_order.each do |key|
+      bib_entries.each do |entry|
+        to_return.push(entry) if entry[:key] == key
+      end
+    end
+    to_return
+  end
+end
+
+
+# Given a string containing the YAML for the bibliography, and an array
+# containing the keys in the order they appear in the text (without
+# repetitions), make an array of strings where each string is a bibliographic
+# entry (i.e. can be placed directly in the bibliography). The entries
+# returned will be sorted in an appropriate order.
+def make_bib_entries(bibliography_yaml, keys_in_order)
+  # Convert the YAML text to a Ruby data type.
+  objs = YAML.load(bibliography_yaml)
+
+  # Make each bibliography entry string (the references).
+  bib_entries = Array.new
+  objs.each_key do |key|
+    bib_entries.push(make_bib_entry_string(objs[key], key))
+  end
+  
+  # Sort the references & return.
+  sort_bib_entries(bib_entries, keys_in_order, :order_in_text)
+end
+
+# Define a function that returns true if bib_entries contains an entry for a
+# given citation key.
+def has_key?(key, bib_entries)
+  ret_val = false
+  bib_entries.each do |entry|
+    ret_val = true if entry[:key] == key
+  end
+  ret_val
+end
+
+# Get an array that contains the reference keys in the order they are cited,
+# without repetitions.
+def get_keys_in_order(plaintext)
+  all_keys = plaintext.scan(/cite:\w*/)
+  all_keys.uniq! # Remove duplicates.
+  uniq_keys = []
+  all_keys.each {|x| uniq_keys.push(x.split('cite:')[1])} # Remove the 'cite:'  
+  uniq_keys
+end
+
+# Convert bib_entries into a string that can be placed at the end of the
+# plaintext as the bibliography. The parenthesis style using the 
+# citation_parens argument.
+def render_bibliography(bib_entries, citation_parens)
+  ret_val = "\n"
+  bib_entries.each_index do |i|
+    ret_val += # The reference number.
+      citation_parens[0].chr + (i+1).to_s + citation_parens[1].chr
+    ret_val += ' ' + bib_entries[i][:reference] # The reference.
+    ret_val += "  \n" # __\n is Markdown for a linebreak.
+  end
+  
+  ret_val
+end
+
+# Given the plaintext containing the key-based citations, and the bib_entries,
+# make the final manuscript by replacing the key-based citations (in the text)
+# with human-readable citations and place the bibliography at the end. Specify
+# the parenthesis style using the optional citation_parens argument.
+def make_manuscript(plaintext, bib_entries, citation_parens='[]')
+  bib_entries.each_index do |i|
+    plaintext.gsub!("cite:#{bib_entries[i][:key]}",
+      citation_parens[0].chr + "#{i+1}" + citation_parens[1].chr)
+  end
+  
+  plaintext + render_bibliography(bib_entries, citation_parens)
+end
+
+# Check the final manuscript for instances of cite:SomeKey (for example), and
+# return an array of messages identifying the keys that were not defined in
+# the bibliography.
+def check_missing_citations(manuscript)
+  ret_val = []
+  # Get the remaining keys.
+  remaining_keys = get_keys_in_order(manuscript)
+  remaining_keys.each do |key|
+    ret_val.push('The following reference key was undefined: ' + key)
+  end
+  
+  ret_val
+end
+
+# Read the text containing the citations from standard input, process the
+# references and send the result to standard output, reporting errors to
+# standard error. This program is written to allow it to be chained with other
+# manuscript-processing tools in a UNIX pipeline. To read/write from/to files,
+# do:
+#
+# cat my-paper.txt | ruby make_paper.rb > my-paper-with-bib.txt
+def bibdown_main
+  # Handle request for documentation.
+  if ARGV.length > 0 && ARGV[0] == '--help'
+    puts documentation
+    exit
+  end
+  
+  # Read the .txt file from standard input and get the plain text and the
+  # bibliography
+  parts = STDIN.readlines('# Bibliography')
+  plaintext = parts[0]
+  bibliography_yaml = parts[1]
+  
+  # Get an array that contains the reference keys in the order they are cited,
+  # without repetitions.
+  keys_in_order = get_keys_in_order(plaintext)
+  
+  # Make a list of bibliography enties, sorted in the correct order.
+  bib_entries = make_bib_entries(bibliography_yaml, keys_in_order)
+  
+  # Now make the final manuscript by replacing the key-based citations (in the
+  # text) with human-readable citations and place the bibliography at the end.
+  manuscript = make_manuscript(plaintext, bib_entries)
+  
+  # Send the manuscript to standard output.
+  STDOUT.puts(manuscript)
+  
+  # Now perform some checks for possible user errors and report then on
+  # standard error.
+  user_errors = []
+  user_errors.concat(check_missing_citations(manuscript))
+  user_errors.each {|x| STDERR.puts(x)} # Report the user errors.
+  
+end

data/lib/mandown/version.rb

@@ -2,7 +2,7 @@ module Mandown #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
     MINOR = 0
-    TINY  = 7
+    TINY  = 8
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end