mint 0.2 → 0.2.2

data/README.md

@@ -1,5 +1,7 @@
 *The following is a **rough draft** of the current Mint design, along with my future plans for the library and tool. The templates are not all there yet (that's the next step) and my first plugins aren't quite there. That said, I'm excited about where this library is going to go.*
 
+**Mint requires Ruby 1.9.**
+
 If I believed in slogans...
 ---------------------------
 
@@ -18,16 +20,6 @@ Mint manages your documents in a decentralized but consistent way. It frees you
 
 In a few more: *Mint processes words so you don't have to.*
 
-Table of contents
------------------
-
-I. Use cases  
-II. The Mint library  
-III. Designing a template  
-IV. The Mint path  
-V. The `mint` command  
-VI. Future directions and tools
-
 I. Use cases
 ------------
 
@@ -37,6 +29,8 @@ I. Use cases
 
 3. Marina wants to convert all her proprietary processed documents to Markdown for future compatibility, but wants to share these documents with friends at work. Interoperability is important here. The friends should be able to easily view *and* edit *and* annotate all documents. Marina will be happiest if she has a simple GUI that can export documents to an open-source document format that's interoperable with word processors.
 
+4. Santosh stores his blog entries in Markdown and wants to see how they look using his blog engine's stylesheet. He doesn't want to upload his entry until he's finished with it, but he wants to preview it with that stylesheet along the way.
+
 II. The Mint library
 --------------------
 
@@ -46,12 +40,12 @@ This section discusses the Mint library API. This library encapsulates the idea
 
 Mint is loaded with smart defaults, so if you don't want to configure something--say, the basic HTML skeleton of your document or the output directory--you don't have to. You'll probably be surprised at how easy it is to use out of the box, and how configurable it is.
 
-    document = Document.new '~/Documents/Minimalism.md'
+    document = Document.new 'Minimalism.md'
     document.mint
 
 And voilà, Minimalism.html will show up next to Minimalism.md.
 
-Opening Minimalism.html with your favorite web browser--[Firefox is best for typography][Firefox typography], but Webkit-based browsers (Chrome, Safari) work, too--will show what looks like a word processed document, complete with big bolded headers, italic emphasis, automatically indented and numbered lists, and bullets. If you're in a modern browser, you'll even see ligatures and proper kerning. The page will be on a white canvas that looks like a page, even though you are in a browser.
+Opening Minimalism.html with your favorite web browser--[Firefox is best for typography][Firefox typography], but Webkit-based browsers (Chrome, Safari) work, too--will show what looks like a word-processed document, complete with big bold headers, italic emphasis, automatically indented and numbered lists, and bullets. If you're in a modern browser, you'll even see ligatures and proper kerning. The page will be on a white canvas that looks like a page, even though you are in a browser.
 
 Sending that page to a printer is as easy as clicking "Print" from your browser. What comes out of your printer will have a 12 pt base font, normal margins, and a not-too-cramped baseline. (Ah the wonder of print stylesheets.)
 
@@ -69,14 +63,14 @@ You can pass any of the following to a new document:
 
   Defaults:
 
-        :template => 'default'
+      :template => 'default'
 
   Notes:
 
   1. If you specify a template name here, Mint will search its paths in order (see **The Mint Path** for more details) for a template with that name. A template file looks like the following:
 
-            ${MINT_PATH}/templates/template_name/style.css
-            ${MINT_PATH}/templates/template_name/layout.haml
+          ${MINT_PATH}/templates/template_name/style.css
+          ${MINT_PATH}/templates/template_name/layout.haml
 
   2. If you specify a template name that is also the name of an existing file in your working directory, Mint will use the file and not look for a template. (It is unlikely you'll have an extension-less file named 'normal' or 'default' in your working directory, so don't worry about this edge case.) If you do specify an existing file, the path/file will be resolved from the directory where you're calling Mint (the 'working directory'). To use Mint this way (and I don't see this as more than a temporary solution) you'll probably want to call Mint from within your source's directory. Alternatively, you can use [`Dir.chdir`][Dir::chdir method] for the same effect.
 
@@ -84,14 +78,14 @@ You can pass any of the following to a new document:
 
   Defaults:
 
-        :destination => nil
-        :style_destination => nil
+      :destination => nil
+      :style_destination => nil
 
   Notes:
 
   1. `:destination` *must* refer to a directory (existing or not) and not a file.
 
-  2. `:style_destination` is resolved relative to `:destination` so that packaging styles inside document directories is easy. (This supports the common case where you will want a subdirectory called 'styles' to hold your style files.) When `:style_destination` is nil (default), the stylesheet will not be copied anywhere. Instead, your document will link to the rendered stylesheet in place. If `:style_destination` is 'inline', your style will be included inline with your published document.
+  2. `:style_destination` is resolved relative to `:destination` so that packaging styles inside document directories is easy. (This supports the common case where you will want a subdirectory called 'styles' to hold your style files.) When `:style_destination` is nil (default), the stylesheet will not be copied anywhere. Instead, your document will link to the rendered stylesheet in place. If it needs to be rendered, it will be rendered into a subdirectory called 'css' so that the rendered document isn't picked up the next time you specify the same style.
 
 ### Examples ###
 
@@ -100,21 +94,21 @@ At this point, a couple of examples may be useful.
 The following are possible:
 
     include Mint
-    content = '~/Documents/Minimalism.md'
+    content = 'Minimalism.md'
     
     Document.new content
-    Document.new content, :destination => 'directory', :style => 'serif-pro'
+    Document.new content, :destination => 'output', 
+      :style => 'serif-pro'
     Document.new content, :style => Style.new(:normal)
     
     Style.new 'normal'
     Style.new :normal
-    Style.new '~/Sites/Common Styles/normal.css', :destination => 'styles'
+    Style.new '~/Sites/Common Styles/normal.css', 
+      :destination => 'styles'
     Style.new '~/Sites/Common Styles/normal.css', 
       :style_destination => 'inline'
     Style.new 'Common Styles/normal.css'
 
-> Note: A style's destination is specified as `:destination` when passed directly to the file or as `:style_destination` when passed to a document or project
-
 If block-style initiation is your thing:
 
     Document.new content do |d|
@@ -122,27 +116,7 @@ If block-style initiation is your thing:
       d.template = 'resume'
     end
 
-> Note: Block-style indentation passes the block to you *after* initializing
-> the document with default values. So you do not need to worry about
-> specifying each argument. Anything you specify will override what
-> is already there.
-
-One warning: when you initialize a document via a block, do not try
-the following:
-
-    Document.new content do |d|
-      # The wrong way to block-initialize a style destination:
-      d.style_destination = 'styles'
-    end
-
-Because `:style_destination` translates internally to `:destination` (so that it can be passed to the style initializer), setting `:style_destination` is meaningless in a document block. Instead, you should do the following:
-
-    Document.new content do |d|
-      # The right way to block-initialize a style destination:
-      d.style.destination = 'styles'
-    end
-
-*(Should this change? Maybe I'll fix that.)*
+Block-style indentation passes the block to you *after* initializing the document with default values. So you do not need to worry about specifying each argument. Anything you specify will override what is already there.
 
 [Dir::chdir method]: http://ruby-doc.org/core/classes/Dir.html#M002314 "You can change the current directory context with Dir::chdir(path)"
 
@@ -291,7 +265,7 @@ Other options have nothing to do with document configuration but are there for c
 
 Not all commandline arguments will be read as files. `mint` has a certain vocabulary that you can use, for example, to manipulate configuration options or edit layout files.
 
-Currently, the `mint` vocabulary consists of `set`, `edit`, and `config`. 
+Currently, the `mint` vocabulary consists of `set`, `edit`, and `config`. (Coming soon: `install` and `package`.)
 
 ### `mint` configuration ###
 
@@ -350,8 +324,8 @@ Inside of a directory, you can edit any stylesheet or document template that wou
 
 Mint will open the appropriate file in the editor specified by EDITOR. The same short forms listed earlier apply here:
 
-    mint edit -L normal
-    mint edit -S normal
+    mint edit -l normal
+    mint edit -s normal
 
 VI. The future of Mint
 ----------------------
@@ -366,4 +340,5 @@ Not everyone wants to code an entire stylesheet every time he wants a new look.
 
 Sometimes, it may be useful to "finalize" the design of a document, for example, with publications. The best way I can think of to do this is to package the document's output file with its style inline. To do so, simply add the package option:
 
+    # Note: I haven't implemented this yet 
     mint package document.md

data/features/mint_document.feature

@@ -38,10 +38,10 @@ Feature: Mint document with varying options at the command line
     And the file "content.html" should contain "<style file>"
 
     Examples:
-      | template | layout | style  | style file                        |
-      |          |        |        | ../../templates/default/style.css |
-      | -t pro   |        |        | ../../templates/pro/style.css     |
-      |          | -l pro | -s pro | ../../templates/pro/style.css     |
+      | template | layout | style  | style file                            |
+      |          |        |        | ../../templates/default/css/style.css |
+      | -t pro   |        |        | ../../templates/pro/css/style.css     |
+      |          | -l pro | -s pro | ../../templates/pro/css/style.css     |
 
   Scenario: Mint document with non-existent template
     When I run "mint -t nonexistent content.md"

data/lib/mint.rb

@@ -1,5 +1,10 @@
 require 'mint/helpers'
 require 'mint/mint'
+require 'mint/resource'
+require 'mint/layout'
+require 'mint/style'
+require 'mint/document'
 require 'mint/version'
 require 'mint/css'
 require 'mint/commandline'
+require 'mint/exceptions'

data/lib/mint/commandline.rb

@@ -41,7 +41,6 @@ module Mint
     #   FileUtils.copy file, directory
     # end
 
-
     # If we get the edit command, will retrieve appropriate file
     # (probably a Mint template) and shell out that file to
     # the user's favorite editor.
@@ -58,7 +57,6 @@ module Mint
       Helpers.ensure_directory config_directory
       Helpers.update_yaml opts, config_file
     end
- 
 
     # Try to set a config option (at the specified scope) per 
     # the user's command.

data/lib/mint/css.rb

@@ -4,8 +4,8 @@ module Mint
       'container'
     end
 
-    # Mappings from "DSL" to actual CSS. The plan is to translate
-    # this into something like:
+    # Mappings from "DSL" to actual CSS. This is not yet implemented, but 
+    # the plan is to translate this into something like:
     #
     # #container {
     #   font: (value specified and cleaned up)

data/lib/mint/document.rb

@@ -0,0 +1,136 @@
+require 'mint/resource'
+require 'mint/layout'
+require 'mint/style'
+
+module Mint
+  class Document < Resource
+    # The following provide reader/accessor methods for the objects's
+    # important attributes. Each implicit reader is paired with an
+    # explicit assignment method that processes a variety of input to a 
+    # standardized state.
+    
+    # When you set content, you are giving the document a renderer based
+    # on the content file and are processing the templated content into
+    # Html, which you can then access using via the content reader.
+    attr_reader :content
+    def content=(content)
+      @renderer = Mint.renderer content
+      @content = @renderer.render
+    end
+
+    # The explicit assignment method allows you to pass the document an existing
+    # layout or the name of a layout template in the Mint path or an
+    # existing layout file.
+    attr_reader :layout
+    def layout=(layout)      
+      @layout = 
+        if layout.respond_to? :render
+          layout
+        else
+          layout_file = Mint.lookup_template layout, :layout
+          Layout.new layout_file
+        end
+    rescue TemplateNotFoundException
+      abort "Template '#{layout}' does not exist."
+    end
+    
+    # The explicit assignment method allows you to pass the document an existing
+    # style or the name of a style template in the Mint path or an
+    # existing style file.
+    attr_reader :style
+    def style=(style)
+      @style = 
+        if style.respond_to? :render
+          style
+        else
+          style_file = Mint.lookup_template style, :style
+          Style.new style_file
+        end
+    rescue TemplateNotFoundException
+      abort "Template '#{style}' does not exist."
+    end
+
+    # I'm going to maintain a document's official style_destination
+    # outside of its style object. If a document has no
+    # style_destination defined when it needs one, the document will
+    # use the style's source directory. This eliminates edge cases
+    # nicely and lets us maintain document-specific information
+    # separately. (Without this separation, funky things happen when
+    # you assign a new style template to an existing document -- if
+    # you had specified a custom style_destination before changing
+    # the template, that custom destination would be overridden.
+
+    attr_reader :style_destination
+    def style_destination=(style_destination)
+      @style_destination = style_destination
+    end
+
+    def template=(template)
+      if template
+        self.layout = template
+        self.style = template
+      end
+    end
+    
+    def initialize(source, opts={})
+      options = Mint.default_options.merge opts
+      super(source, :document, options)
+
+      # Each of these should invoke explicitly defined method
+      self.content  = source
+      self.layout   = options[:layout]
+      self.style    = options[:style]
+      self.style_destination = options[:style_destination]
+
+      # The template option will override layout and style choices
+      self.template = options[:template]
+
+      yield self if block_given?
+    end
+
+    def render(args={})
+      layout.render self, args
+    end
+
+    def mint(root=Dir.getwd, render_style=true)      
+      root = Pathname.new root
+      
+      # Only render style if a) it's specified by the options path and
+      # b) it actually needs rendering (i.e., it's in template form and
+      # not raw, browser-parseable CSS).
+      render_style &&= style.need_rendering?
+
+      document_file = root + (self.destination || '') + self.name
+      FileUtils.mkdir_p document_file.dirname
+      document_file.open 'w+' do |f|
+        f << self.render
+      end
+
+      if render_style
+        style_dest = 
+          if style_destination 
+            root + self.destination + style_destination
+          else
+            self.style.destination
+          end
+        style_file = style_dest + self.style.name
+        FileUtils.mkdir_p style_file.dirname
+        
+        style_file.open 'w+' do |f|
+          f << self.style.render
+        end
+      end
+    end
+
+    # Convenience methods for views
+
+    # Returns a relative path from the document to its stylesheet. Can
+    # be called directly from inside a layout template.
+    def stylesheet
+      style_dest = self.style_destination || self.style.destination
+      destination = self.destination || ''
+      Helpers.normalize_path(style_dest, destination) + 
+        style.name.to_s
+    end
+  end
+end

data/lib/mint/layout.rb

@@ -0,0 +1,12 @@
+require 'mint/resource'
+
+module Mint
+  # Layout describes a resource whose type is `:layout`. Beyond its type,
+  # it is a simple resource. However, its type helps decide which template
+  # file to use when a template name is specified.
+  class Layout < Resource
+    def initialize(source, opts=Mint.default_options)
+      super(source, :layout, opts)
+    end
+  end
+end

data/lib/mint/mint.rb

@@ -3,8 +3,9 @@ require 'fileutils'
 require 'yaml'
 require 'tilt'
 
-module Mint
+require 'mint/exceptions'
 
+module Mint
   # Assume that someone using an Html template has formatted it
   # in Erb and that a Css stylesheet will pass untouched through
   # a Less parser.
@@ -89,7 +90,7 @@ module Mint
     File.exist?(name) ? Pathname.new(name) : find_template(name, type)
   end
 
-  # Finds a template named `name` in the Mint path. If `type` # is :layout,
+  # Finds a template named `name` in the Mint path. If `type` is :layout,
   # will look for `${MINT_PATH}/templates/layout.*`. If it is :style, will
   # look for `${MINT_PATH}/templates/template_name/style.*`. Mint assumes
   # that a named template will hold only one layout and one style template.
@@ -104,10 +105,11 @@ module Mint
     find_files = lambda {|x| Pathname.glob "#{x.to_s}.*" }
     acceptable = lambda {|x| x.to_s =~ /#{Mint.formats.join '|'}/ }
 
-    Mint.path.
-      map(&file_name).map(&find_files).flatten.
-      select(&acceptable).select(&:exist?).
-      first
+    template = Mint.path.map(&file_name).map(&find_files).flatten.
+      select(&acceptable).select(&:exist?).first
+    raise TemplateNotFoundException unless template
+
+    template
   end
 
   # Guesses an appropriate name for the resource output file based on
@@ -123,195 +125,6 @@ module Mint
   # Transforms a path into a template that will render the file specified
   # at that path
   def self.renderer(path)
-    Tilt.new path.to_s, :smart => true
-  end
-
-  class Resource
-    attr_accessor :type
-
-    attr_reader :source
-    def source=(source)
-      @source = Pathname.new(source) if source
-    end
-    
-    # I haven't tested this - moved empty string from
-    # default options into this method, so that default options
-    # can be uniform - i.e., style_destination and destination
-    # can each be nil to indicate that any rendering will be
-    # done in the same folder the file is already in. I need
-    # to make sure that adding the empty string here actually
-    # keeps us in the current working directory
-    attr_reader :destination
-    def destination=(destination)
-      @destination = Pathname.new(destination || '')
-    end
-    
-    attr_reader :name
-    def name=(name)
-      @name = name
-    end
-
-    def renderer=(renderer)
-      @renderer = renderer
-    end
-
-    def initialize(source, type=:resource, options={})
-      return nil unless source
-
-      self.source = source
-      self.type = type
-      self.destination = options[:destination]
-      self.name = Mint.guess_name_from source
-      self.renderer = Mint.renderer source
-    end
-
-    def equal?(other)
-      destination + name == other.destination + other.name
-    end
-    alias_method :==, :equal?
-
-    def render(context=Object.new, args={})
-      # see Tilt TEMPLATES.md for more info
-      @renderer.render context, args 
-    end
-  end
-
-  # Layout describes a resource whose type is `:layout`. Beyond its type,
-  # it is a simple resource. However, its type helps decide which template
-  # file to use when a template name is specified.
-  class Layout < Resource
-    def initialize(source, opts=Mint.default_options)
-      super(source, :layout, opts)
-    end
-  end
-
-  # Style describes a resource whose type is `:style`. Beyond its type,
-  # it is a simple resource. However, its type helps decide which template
-  # file to use when a template name is specified.
-  class Style < Resource
-    def initialize(source, opts=Mint.default_options)
-      super(source, :style, opts)
-    end
-
-    def needs_rendering?
-      source.extname !~ /\.css$/
-    end
-  end
-
-  class Document < Resource
-    # The following provide reader/accessor methods for the objects's
-    # important attributes. Each implicit reader is paired with an
-    # explicit assignment method that processes a variety of input to a 
-    # standardized state.
-    
-    # When you set content, you are giving the document a renderer based
-    # on the content file and are processing the templated content into
-    # Html, which you can then access using via the content reader.
-    attr_reader :content
-    def content=(content)
-      @renderer = Mint.renderer content
-      @content = @renderer.render
-    end
-
-    # The explicit assignment method allows you to pass the document an existing
-    # layout or the name of a layout template in the Mint path or an
-    # existing layout file.
-    attr_reader :layout
-    def layout=(layout)      
-      @layout = 
-        if layout.respond_to? :render
-          layout
-        else
-          layout_file = Mint.lookup_template layout, :layout
-          Layout.new layout_file
-        end
-    end
-    
-    # The explicit assignment method allows you to pass the document an existing
-    # style or the name of a style template in the Mint path or an
-    # existing style file.
-    attr_reader :style
-    def style=(style)
-      # Before setting this document's style to a new one, save
-      # the current style destination, if it exists
-      destination = @style ? @style.destination : ''
-
-      @style = 
-        if style.respond_to? :render
-          style
-        else
-          style_file = Mint.lookup_template style, :style
-          Style.new style_file, :destination => destination
-        end
-    end
-
-    def template=(template)
-      if template
-        self.layout = template
-        self.style = template
-      end
-    end
-    
-    # Convenience methods for reaching into a document's style
-    # via a unified interface
-    def style_destination=(style_destination)
-      self.style.destination = style_destination if self.style
-    end
-
-    def style_destination
-      self.style.destination
-    end
-
-    def initialize(source, opts={})
-      options = Mint.default_options.merge opts
-      super(source, :document, options)
-
-      # Each of these should invoke explicitly defined method
-      self.content  = source
-      self.layout   = options[:layout]
-      self.style    = options[:style]
-
-      # The template option will override layout and style choices
-      self.template = options[:template]
-
-      self.style_destination = 
-        options[:style_destination] || self.style.source.dirname.expand_path
-
-      yield self if block_given?
-    end
-
-    def render(args={})
-      layout.render self, args
-    end
-
-    def mint(root=Dir.getwd, render_style=true)      
-      root = Pathname.new root
-      
-      # Only render style if a) it's specified by the options path and
-      # b) it actually needs rendering (i.e., it's in template form and
-      # not raw, browser-parseable CSS).
-      render_style &&= style.needs_rendering?
-
-      resources = [self]
-      resources << style if render_style
-
-      resources.compact.each do |r|
-        dest = root + r.destination + r.name
-        FileUtils.mkdir_p dest.dirname
-        
-        dest.open 'w+' do |f|
-          f << r.render
-        end
-      end
-    end
-
-    # Convenience methods for views
-
-    # Returns a relative path from the document to its stylesheet. Can
-    # be called directly from inside a layout template.
-    def stylesheet
-      Helpers.normalize_path(style.destination, destination) + 
-        style.name.to_s
-    end
+    Tilt.new path.to_s, :smart => true, :ugly => true
   end
 end