mint 0.2.2 → 0.2.5

data/README.md

@@ -1,10 +1,12 @@
-*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.*
+*The following is a **rough description** of the current Mint design, along with my future plans for the library and tool. When I have time, I'll extract the juciest parts into a README and move the rest into official documentation. The templates are not finished, and I haven't completed the plugin system. That said, I'm excited about where this library is going to go.*
 
-**Mint requires Ruby 1.9.**
+> **Mint requires Ruby 1.9.**
 
 If I believed in slogans...
 ---------------------------
 
+Mint is a publishing platform for people who want to store their documents as plain text without giving up proper layout or the ability to share with friends.
+
 I don't actually believe in tag lines, but if Mint were to have one, it might be one of these:
 
 - Value your words. Leave the formatting up to us.
@@ -20,7 +22,7 @@ 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.*
 
-I. Use cases
+Use cases
 ------------
 
 1. Jake has text files formatted as Markdown-style text. He has traditionally published these as blog entries, which works well because his webserver takes care of processing the Markdown, generating HTML, and styling it with his static CSS. Jake has no way of visualizing his documents without a webserver running. He likes the convenience of centralized CSS styles that he can update once and cascade everywhere. He does not like depending on a webserver for static pages, i.e., his local documents. Jake wants a document management system where source files are written in Markdown but are "printed" into HTML and styled with centralized sheets he creates himself. In some cases, he merely wants to tweak the typography settings of a solid existing style. Above all, he wants simplicity: he does not want to have to put his documents into a certain structure in order for them to be rendered. And he wants default styles so that he doesn't have to create them on his own.
@@ -31,7 +33,7 @@ I. Use cases
 
 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
+The Mint library
 --------------------
 
 This section discusses the Mint library API. This library encapsulates the idea of a styled document, which is composed of a stylesheet, a layout and content. Mint makes combining those seemless. See **The `mint` command** for more information on an easy-to-use binary.
@@ -41,9 +43,9 @@ 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 'Minimalism.md'
-    document.mint
+    document.publish!
 
-And voilà, Minimalism.html will show up next to Minimalism.md.
+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 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.
 
@@ -57,35 +59,39 @@ If you want to customize your document, though--and that's why I built this libr
 
 To understand how the library works, with and without configuration, it is helpful to look at the options you can pass to the library and what their defaults are.
 
-You can pass any of the following to a new document:
+You can change a document by passing it one of several options.
+
+#### Layout and style ####
+
+`:layout` and `:style` are names of templates or file names. They can be overridden by `:template`, which sets both to the same name.
 
-- `:layout` and `:style` are names of templates or file names. They can be overridden by `:template`, which sets both to the same name.
+Defaults:
 
-  Defaults:
+    :template => 'default'
 
-      :template => 'default'
+Notes:
 
-  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:
 
-  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.
 
-  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.
+#### Destination ####
 
-- `:destination` lets you organize your output. It directs Mint to write the template or document to one of root's subdirectories. There is an option to specify a separate `:style_destination`, which is resolved relative to `:destination`.
+`:destination` lets you organize your output. It directs Mint to write the template or document to one of root's subdirectories. There is an option to specify a separate `:style_destination`, which is resolved relative to `:destination`.
 
-  Defaults:
+Defaults:
 
-      :destination => nil
-      :style_destination => nil
+    :destination => nil
+    :style_destination => nil
 
-  Notes:
+Notes:
 
-  1. `:destination` *must* refer to a directory (existing or not) and not a file.
+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 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.
+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 ###
 
@@ -120,7 +126,7 @@ Block-style indentation passes the block to you *after* initializing the documen
 
 [Dir::chdir method]: http://ruby-doc.org/core/classes/Dir.html#M002314 "You can change the current directory context with Dir::chdir(path)"
 
-III. Designing a template
+Designing a template
 -------------------------
 
 Templates can be written in any format accepted by the Tilt template interface library. (See [the Tilt TEMPLATES file][Tilt templates] for more information.)
@@ -176,20 +182,19 @@ destination.
 Mint comes preloaded with several styles and layouts.
 
 1. Default
-2. Serif Pro
-3. Sans Pro
+2. Pro
+3. Resume\*
 4. Protocol
-5. Protocol Flow - requires Javascript and jQuery
-6. Resume
+5. Protocol Flow\* - requires Javascript and jQuery
 
-> Note: These aren't all designed yet. Also, if you have a killer
+> Note: Starred entries are not yet implemente. If you have a killer
 > template you think should be included, send it my way. I'll check
 > it out and see if it should be part of the standard template library.
 > (Of course, you'll get all the credit.)
 
-I'm going to build a template extension system soon so that you can easily base your template off of another one using its template name, and without knowing its location on disk.
+I've included a base stylesheet that is useful for setting sensible typographic defaults.
 
-IV. The Mint path
+The Mint path
 -----------------
 
 Mint's path tells the library where to search for named templates. It can be useful for other things, too, especially for extensions and tools that use the library (for example, for storing config files for the `mint` command). The Mint path is flexible and something that you can modify, even from the command line. (Just export `MINT_PATH`=`your:colon-separated-paths:here`. Just make sure to specify higher-priority paths before lower-priority ones.)
@@ -212,7 +217,7 @@ Templates should be in a directory named templates. Inside this directory, there
 
 Normally a style will go best with its layout complement. However, layouts and styles can be mixed and matched at your discretion. This is especially true where you are primarily customizing DOM elements with your stylesheet instead of targeting specific IDs or classes you're expecting to find. (In other words, this works best when your stylesheet focuses on modifying typography and not page layout.)
 
-V. The `mint` command
+The `mint` command
 ---------------------
 
 *The `mint` command is almost functional. Testing is in development.*
@@ -327,7 +332,7 @@ Mint will open the appropriate file in the editor specified by EDITOR. The same
     mint edit -l normal
     mint edit -s normal
 
-VI. The future of Mint
+The future of Mint
 ----------------------
 
 This section documents features that do not yet exist, but that I would like to have in future versions of Mint.

data/bin/mint

@@ -1,72 +1,35 @@
 #!/usr/bin/env ruby
-
 # A script for harnessing Mint at the commandline
 # Usage: mint [options] files
 
-require 'optparse'
 require 'mint'
 
 # Parse options from the commandline
 commandline_options = {}
-optparse = OptionParser.new do |opts|
-  opts.banner = 'Usage: mint [command] files [options]'
-
-  Mint::CommandLine.options.each do |k,v|
-    has_param = v['parameter']
+process_opts = lambda {|k,v| commandline_options[k] = v }
+parser = Mint::CommandLine.parser(&process_opts)
+parser.parse!
 
-    v['short'] = "-#{v['short']}"
-    v['long'] = "--#{v['long']}"
+# Minimalist implementation that I want to move to, but
+# will have to refactor commandline.rb code and tests
+#
+# first = ARGV.first.downcase.to_sym
+# commands = [ :install, :edit, :set, :config ]
+# command = commands.include?(first) ? command : :mint
 
-    if has_param
-      v['long'] << " PARAM"
-      opts.on v['short'], v['long'], v['description'] do |p|
-        commandline_options[k.to_sym] = p
-      end
-    else
-      opts.on v['short'], v['long'], v['description'] do
-        commandline_options[k] = true
-      end
-    end
-  end
-end
-optparse.parse!
+# Mint::CommandLine.send(command, commandline_options)
 
 case ARGV.first.downcase.to_sym
 when :help
-  Mint::CommandLine.help(optparse.help)
-
+  Mint::CommandLine.help(parser.help)
 when :install
-  commandline_options[:local] = true
-  scope = [:global, :user, :local].
-    select {|e| commandline_options[e] }.
-    first
-
-  Mint::CommandLine.install ARGV.shift, scope
-
+  Mint::CommandLine.install(ARGV.shift, commandline_options)
 when :edit
-  layout = commandline_options[:layout]
-  style = commandline_options[:style]
-
-  if layout and not style
-    Mint::CommandLine.edit layout, :layout
-  elsif style
-    Mint::CommandLine.edit style, :style
-  else
-    puts optparse.help
-  end
-
+  Mint::CommandLine.edit(ARGV.shift, commandline_options)
 when :set
-  # Determine scope, using local as the default
-  commandline_options[:local] = true
-  scope = [:global, :user, :local].
-    select {|e| commandline_options[e] }.
-    first
-
-  Mint::CommandLine.set ARGV.shift, ARGV.shift, scope
-
+  Mint::CommandLine.set(ARGV.shift, ARGV.shift, commandline_options)
 when :config
   Mint::CommandLine.config
-
 else
   # If no commands were found, search the PATH for commands prefixed
   # with mint-. If no matching executables are found, we know we've
@@ -82,6 +45,6 @@ else
     commandline_options.delete :verbose
     commandline_options.delete :simulation
 
-    Mint::CommandLine.mint ARGV, commandline_options
+    Mint::CommandLine.mint(ARGV, commandline_options)
   # end
 end

data/config/{options.yaml → syntax.yaml}

@@ -2,7 +2,7 @@ template:
   short: t
   long: template
   parameter: true
-  description: 'Specify the template (layout + style).'
+  description: 'Specify the template (layout + style)'
 
 layout:
   short: l
@@ -14,19 +14,19 @@ style:
   short: s
   long: style
   parameter: true
-  description: 'Specify only the style.'
+  description: 'Specify only the style'
 
 root:
   short: w
   long: r
   parameter: true
-  description: 'Specify a root outside the current directory.'
+  description: 'Specify a root outside the current directory'
 
 destination:
   short: d
   long: destination
   parameter: true 
-  description: 'Specify a destination directory, relative to the root.'
+  description: 'Specify a destination directory, relative to the root'
 
 style_destination:
   short: n
@@ -38,35 +38,34 @@ global:
   short: G
   long: global
   parameter: false
-  description: 'Specify config changes on a global level.'
+  description: 'Specify config changes on a global level'
 
 user:
   short: U
   long: user
   parameter: false
-  description: 'Specify config changes on a user-wide level.'
-
+  description: 'Specify config changes on a user-wide level'
 
 local:
   short: L
   long: local
   parameter: false
-  description: 'Specify config changes on a project-specific level.'
+  description: 'Specify config changes on a project-specific level'
 
 force:
   short: f
   long: force
   parameter: false
-  description: 'Force file overwrite without prompt.'
+  description: 'Force file overwrite without prompt'
 
 verbose:
   short: v
   long: verbose
   parameter: false
-  description: 'Verbose output.'
+  description: 'Verbose output'
 
 simulation:
   short: S
   long: simulation
   parameter: false
-  description: 'Simulate transformation without actually creating files.'
+  description: 'Simulate transformation without actually creating files'

data/lib/mint/commandline.rb

@@ -1,6 +1,6 @@
 require 'pathname'
 require 'yaml'
-require 'mint'
+require 'optparse'
 
 module Mint
   module CommandLine
@@ -9,21 +9,48 @@ module Mint
     # the commandline. (All other arguments are taken to be
     # filenames.)
     def self.options
-      options_file = '../../../config/options.yaml'
+      options_file = "../../../#{Mint.files[:syntax]}"
       YAML.load_file File.expand_path(options_file, __FILE__)
     end
 
-    def self.configuration
-      config_file = Pathname.new(Mint.files[:config])      
+    def self.parser(options_metadata=Mint::CommandLine.options)
+      optparse = OptionParser.new do |opts|
+        opts.banner = 'Usage: mint [command] files [options]'
+
+        Helpers.symbolize_keys(options_metadata).each do |k,v|
+          has_param = v[:parameter]
+
+          v[:short] = "-#{v[:short]}"
+          v[:long] = "--#{v[:long]}"
+
+          if has_param
+            v[:long] << " PARAM"
+            opts.on v[:short], v[:long], v[:description] do |p|
+              yield k.to_sym, p
+            end
+          else
+            opts.on v[:short], v[:long], v[:description] do
+              yield k, true
+            end
+          end
+        end
+      end
+    end
+
+    def self.configuration(file=Mint.files[:config])
+      return nil unless file
+      config_file = Pathname.new file
 
       # Merge config options from all config files on the Mint path,
       # where more local options take precedence over more global
       # options
-      Mint.path.map {|p| p + config_file }.
+      configuration = Mint.path(true).map {|p| p + config_file }.
         select(&:exist?).
         map {|p| YAML.load_file p }.
         reverse.
         reduce(Mint.default_options) {|r,p| r.merge p }
+
+      Helpers.symbolize_keys configuration
     end
 
     def self.configuration_with(opts)
@@ -36,23 +63,39 @@ module Mint
 
     # Install the listed file to the scope listed, using 
     # local as the default scope.
-    # def self.install(file, scope=:local)
-    #   directory = path_for_scope(scope)
-    #   FileUtils.copy file, directory
-    # end
+    def self.install(file, commandline_options)
+      commandline_options[:local] = true
+      scope = [:global, :user, :local].
+        select {|e| commandline_options[e] }.
+        first
+
+      directory = path_for_scope(scope)
+      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.
-    def self.edit(name, layout_or_style=:layout)
+    def self.edit(name, commandline_options)
+      layout = commandline_options[:layout]
+      style = commandline_options[:style]
+
+      if layout and not style
+        layout_or_style = :layout
+      elsif style
+        layout_or_style = :style
+      else
+        puts optparse.help
+      end
+
       file = Mint.lookup_template name, layout_or_style
       
-      editor = ENV['EDITOR'] || 'vim'
+      editor = ENV['EDITOR'] || 'vi'
       system "#{editor} #{file}"
     end
 
     def self.configure(opts, scope=:local)
-      config_directory = Mint.path_for_scope scope
+      config_directory = Mint.path_for_scope(scope, true)
       config_file = config_directory + Mint.files[:config]
       Helpers.ensure_directory config_directory
       Helpers.update_yaml opts, config_file
@@ -60,7 +103,12 @@ module Mint
 
     # Try to set a config option (at the specified scope) per 
     # the user's command.
-    def self.set(key, value, scope=:local)
+    def self.set(key, value, commandline_options)
+      commandline_options[:local] = true
+      scope = [:global, :user, :local].
+        select {|e| commandline_options[e] }.
+        first
+
       configure({ key => value }, scope)
     end
 
@@ -80,13 +128,13 @@ module Mint
       documents = []
       options = configuration_with commandline_options
       
-      root = options[:root] || Dir.getwd
+      options[:root] ||= Dir.getwd
 
       # Eventually render_style should be replaced with file 
       # change detection
       render_style = true
       files.each do |file|
-        Document.new(file, options).mint(root, render_style)
+        Document.new(file, options).mint(render_style)
         render_style = false
       end
     end

data/lib/mint/document.rb

@@ -53,8 +53,10 @@ module Mint
     # 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
+    # use the style's source directory. This happens lazily via
+    # virtual attributes like #style_destination_file, etc.
+    # This eliminates edge cases (like styles we don't want to move
+    # anywhere) 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
@@ -65,6 +67,29 @@ module Mint
       @style_destination = style_destination
     end
 
+    def style_destination_file_path
+      if style_destination
+        path = Pathname.new style_destination
+        dir = path.absolute? ? 
+          path : destination_directory_path + path
+        dir + style.name
+      else
+        style.destination_file_path
+      end
+    end
+
+    def style_destination_file
+      style_destination_file_path.to_s
+    end
+
+    def style_destination_directory_path
+      style_destination_file_path.dirname
+    end
+
+    def style_destination_directory
+      style_destination_directory_path.to_s
+    end
+
     def template=(template)
       if template
         self.layout = template
@@ -74,7 +99,11 @@ module Mint
     
     def initialize(source, opts={})
       options = Mint.default_options.merge opts
-      super(source, :document, options)
+
+      # Loads source and destination, which will be used for
+      # all source_* and destination_* virtual attributes.
+      super(source, options)
+      self.type     = :document
 
       # Each of these should invoke explicitly defined method
       self.content  = source
@@ -85,38 +114,32 @@ module Mint
       # The template option will override layout and style choices
       self.template = options[:template]
 
+      # Yield self to block after all other parameters are loaded,
+      # so we only have to tweak. (We don't have to give up our
+      # defaults or re-test blocks beyond them being tweaked.)
       yield self if block_given?
     end
 
+    # Render content in the context of layout
     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|
+    # Write all rendered content where a) possible, b) required,
+    # and c) specified
+    def publish!(render_style=true)      
+      FileUtils.mkdir_p self.destination_directory
+      File.open(self.destination_file, 'w+') do |f|
         f << self.render
       end
 
+      # 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) or it if it doesn't need
+      # rendering but there is an explicit style_destination.
       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|
+        FileUtils.mkdir_p style_destination_directory
+        File.open(self.style_destination_file, 'w+') do |f|
           f << self.style.render
         end
       end
@@ -127,10 +150,7 @@ module Mint
     # 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
+      self.destination_file_path.relative_path_from(self.style_destination_file_path).to_s 
     end
   end
 end

data/lib/mint/exceptions.rb

@@ -0,0 +1,3 @@
+module Mint
+  class TemplateNotFoundException < Exception; end
+end

data/lib/mint/helpers.rb

@@ -1,5 +1,4 @@
 require 'pathname'
-require 'fileutils'
 require 'yaml'
 
 module Mint
@@ -7,9 +6,9 @@ module Mint
     def self.slugize(obj)
       obj.to_s.downcase.
         gsub(/&/, 'and').
-        gsub(/\s+/, '-').
-        gsub(/-+/, '-').
-        gsub(/[^a-z0-9-]/, '')
+        gsub(/[\s-]+/, '-').
+        gsub(/[^a-z0-9-]/, '').
+        gsub(/[-]+/, '-')
     end
 
     def self.symbolize(obj)
@@ -25,14 +24,26 @@ module Mint
       end.expand_path
     end
 
-    # Returns the relative path to dir1 from dir2.
-    def self.normalize_path(dir1, dir2)
-      path1, path2 = [dir1, dir2].map {|d| pathize d }
-      path1.relative_path_from path2
+    def self.symbolize_keys(map)
+      map.reduce(Hash.new) do |syms,(k,v)| 
+        syms[k.to_sym] = 
+          case v
+          when Hash
+            self.symbolize_keys(v)
+          else
+            v
+          end
+        syms
+      end
     end
 
-    def self.ensure_directory(dir)
-      FileUtils.mkdir_p dir
+    # Returns the relative path to dir1 from dir2. If dir1 and dir2 
+    # have no directories in common besides /, will return the 
+    # absolute directory of dir1. Right now, assumes no symlinks
+    def self.normalize_path(dir1, dir2)
+      path1, path2 = [dir1, dir2].map {|d| pathize d }
+      root1, root2 = [path1, path2].map {|p| p.each_filename.first }
+      root1 == root2 ? path1.relative_path_from(path2) : path1
     end
 
     def self.update_yaml(new_opts, file)

data/lib/mint/layout.rb

@@ -6,7 +6,8 @@ module Mint
   # file to use when a template name is specified.
   class Layout < Resource
     def initialize(source, opts=Mint.default_options)
-      super(source, :layout, opts)
+      super(source, opts)
+      self.type = :layout
     end
   end
 end