mint 0.1.1 → 0.1.3

data/README.md

@@ -1,4 +1,4 @@
-*The following is a **rough draft** of the current Mint design, along with my future plans for the library and tool.*
+*The following is a **rough draft** of the current Mint design, along with my future plans for the library and tool. The code is not yet tested, though it will be as soon as I decide on a framework, and the binary does not yet work. This is concept stuff, people.*
 
 If I believed in slogans...
 ---------------------------
@@ -14,7 +14,7 @@ Introduction
 
 Mint is an agile, lightweight solution for your documents.
 
-Mint manages your documents in a decentralized way. It frees you from bloated word processors. Mint brings together standards and common templating languages for a clean, agile approach to documents. It uses HTML outside of the web. Leverages text for tons of different views. Keeps your data and formatting separate. In a word: simplifies. In a couple of words: kicks ass.
+Mint manages your documents in a decentralized but consistent way. It frees you from bloated word processors. Mint brings together standards and common templating languages for a clean, agile approach to documents. It uses HTML outside of the web. Leverages text for loads of different views. Keeps your data and formatting separate. In a word: simplifies. In a couple of words: kicks ass.
 
 In a few more: *Mint processes words so you don't have to.*
 
@@ -25,38 +25,33 @@ I. Use cases
 II. The Mint library  
 III. Designing a template  
 IV. The Mint path  
-V. The `mint` command   
+V. The `mint` command  
 VI. Future directions and tools
 
 I. 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. 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.
+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.
 
-2. Donna has traditionally used a WYSIWYG word processor to create, edit, version, and present ideas in her personal and school life (not work). She wants her documents to exist forever without breaking standards: she wants them to be completely future-compatible. Therefore, she wants to migrate away from her proprietary word processor. She wants a migration tool to make the initial conversion. Interoperability with other people is not required. As long as she can view and print formatted documents, keeping source files as plaintext, she is happy.
+2. Donna has traditionally used a WYSIWYG word processor to create, edit, version, and present ideas in her personal and school life (not work). She wants her documents to exist forever without breaking standards: she wants them to be completely future-proof. Therefore, she wants to migrate away from her proprietary word processor. (Even non-proprietary word processors are really too heavyweight for her text-centered documents.) She wants a migration tool to make the initial conversion. Interoperability with other people is not required. As long as she can view and print formatted documents, keeping source files as plain text, she is happy.
 
-3. Bertrande wants to build a styles gallery that previews certain styles on Textile-formatted documents using a web application... (finish later)
-
-4. 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.
+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.
 
 II. The Mint library
 --------------------
 
-This section discusses the Mint library API. Read on for the mint binary.
- 
+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.
+
 ### A basic Mint document ###
 
-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 name or director--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.
+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.press
-  
-And voilà, you will find the following next to Minimalism.md in the same directory:
+    document = Document.new '~/Documents/Minimalism.md'
+    document.mint
 
-- Minimalism.html
-- styles/default.css
+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]--will show what looks like a word processed document, complete with big bolded headers, italic emphasis, automatically numbered lists, and bullets.
+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.
 
 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.)
 
@@ -70,101 +65,84 @@ To understand how the library works, with and without configuration, it is helpf
 
 You can pass any of the following to a new document:
 
-- `:layout` and `:style` are names of templates or file names.
+- `:layout` and `:style` are names of templates or file names. They can be overridden by `:template`, which sets both to the same name.
 
   Defaults:
-    
-        :layout => 'default'  
-        :style => '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:
+        :template => 'default'
 
-        PATH/templates/TEMPLATE_NAME/style.sass
-        PATH/templates/TEMPLATE_NAME/layout.haml
-
-  2. If you specify a template name, it MUST be a simple name without extensions or directories included. Also, it must not be the name of a file in the working directory. (It is unlikely you'll have an extension-less file named 'normal' or 'default' in your working directory.)
+  Notes:
 
-  3. You can include path information if you're specifying a source file instead of a template name. If you do specify a file, the path/file will be resolved from the directory where you're calling Mint (the 'working directory'). If you're going 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 the context of your source directory. Alternatively, you can use [`Dir.chdir`][Dir::chdir method] for the same effect.
+  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:
 
-  4. You can specify nil if you don't want a style to be rendered. This is useful if you're pointing a lot of documents to one stylesheet and only want to Mint the stylesheet one time.
+        ${MINT_PATH}/templates/template_name/style.css
+        ${MINT_PATH}/templates/template_name/layout.haml
 
-- `:root` is the root context of the final document. That is, the output. All relative *output* paths are resolved from the root path. `:root` itself must be an absolute path or nil. In most cases where you want a relative `:root`, try using `:destination`, instead. `:root` is most useful when compiling several source documents from different folders into a single, centralized directory.
-  
-  Default:
-  
-        :root => nil
-  
-  Notes:
-  
-  1. If nil, `:root` defaults to your content's parent directory.
-  2. `:root` MUST be a directory.
+  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` lets you specify a subdirectory for your output. There is an option to specify a separate `:style_destination`. The former is resolved relative to `:root`. The latter 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:
 
-        :destination => nil  
+        :destination => ''
         :style_destination => nil
 
   Notes:
 
-  1. `:destination` MUST refer to a directory and *not* a file. If you want to specify the output file name, use the `:name` parameter.
+  1. `:destination` *must* refer to a directory (existing or not) and not a file.
 
-  2. Mint resolves `:destination` relative to `:root` and serves as a way of organizing output files. `: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.)
+  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.
 
-  3. If either value is nil, it is simply ignored.
-  
-- `:name` is the name of the output file, which will end up in `/:root/:destination/`. `:style_name` is the name of the stylesheet output file and will show up in `/:root/:destination/:style_destination/`.
-  
-  Defaults:
-  
-        :name => nil
-        :style_name => nil
+### Examples ###
 
-  Notes:
+At this point, a couple of example may be useful.
 
-  1. If nil, the name of a Document or stylesheet comes from it's source file. (Minimalism.md will turn into Minimalism.html without configuration.)
+The following are possible:
 
-In summary: if `:root` is unspecified, it will be the directory where your content file. The rendered content and style files will be placed directly into this directory unless given a specific `:destination`. The output names will come from their source files unless you specify `:name`.
+    include Mint
+    content = '~/Documents/Minimalism.md'
+    
+    Document.new content
+    Document.new content, :destination => 'directory', :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', 
+      :style_destination => 'inline'
+    Style.new 'Common Styles/normal.css'
 
-Without configuration, `destination = root = content.dirname.expand_path`
+> 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
 
-### Examples ###
+If block-style initiation is your thing:
 
-At this point, a couple of example may be useful.
+    Document.new content do |d|
+      d.destination = 'final'
+      d.template = 'resume'
+    end
 
-The following are possible:
+> 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.
 
-  content = '~/Documents/Minimalism.md'
-
-  Document.new content
-  
-  Document.new content, :root => '~/Documents/Final', :destination => 'directory', :name => 'final.html'
-  Document.new content, :root => 'directory'
-  Document.new content, :root => 'directory', :destination => 'subdirectory'
-  
-  Style.new 'normal'
-  Style.new '~/Sites/Commons/style/normal.sass', :destination => 'style', :name => 'normal.css' # :destination is converted to :style_destination in the context of a document
-  Style.new '~/Sites/Commons/style/normal.css'
-  Style.new 'Commons/style/normal.css'
-  
-If block-style initiation is your thing:
+One warning: when you initialize a document via a block, do not try
+the following:
 
     Document.new content do |d|
-      d.root = 'my-book'
-      d.name = 'my-book-final-draft.html'
-    
-      d.style 'normal' do |s|
-        s.destination = 'styles'
-        s.name = 'stylesheet.css'
-      end
+      # The wrong way to block-initialize a style destination:
+      d.style_destination = 'styles'
     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.
+
+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.)*
 
 [Dir::chdir method]: http://ruby-doc.org/core/classes/Dir.html#M002314 "You can change the current directory context with Dir::chdir(path)"
 
@@ -173,15 +151,17 @@ III. 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.)
 
-Mint gives you convenience methods that you can use in your templates.
+Templates are rendered in the context of the document they are "about", so Mint documents give you convenience methods you can easily use in your templates.
 
 ### Place your content, point to your styles ###
 
-If you're designing a layout, you need to indicate where Mint should place your content. Therefore, raw HTML files cannot be layouts. Instead, if you want to use HTML templates, you should change the extension to .erb. These files are essentially HTML with the possibility for Ruby calls.
+In Mint layouts, Ruby calls are sparse but necessary.
+
+If you're designing a layout, you need to indicate where Mint should place your content. For that simple reason, raw Html files cannot be layouts. Instead, if you want to use Html templates, you should use the Erb format. These files are essentially Html with the possibility for Ruby calls. You can even use the .html extension for your files. Just code the dynamic portion using Erb syntax.
 
-Inside your template, use the keyword (well, actually the method) `content` to place your source's content.
+Inside your template, use the `content` method to place your source's content.
 
-You will want to point to your document's stylesheet (via a relative URL) from within your layout, usually in the `<head/>` element. Use the keyword `stylesheet`.
+You will want to point to your document's stylesheet (via a relative URL) from within your layout, usually in the `<head/>` element. Use the `stylesheet` method.
 
 So if you're writing your layout using Erb, the template might look like this:
 
@@ -190,7 +170,7 @@ So if you're writing your layout using Erb, the template might look like this:
       <head>
         <link rel='stylesheet' href='<%= stylesheet %>' />
       </head>
-  
+
       <body>
         <div id='container'>
           <%= content %>
@@ -203,83 +183,103 @@ The same layout in Haml would be:
     !!!
     %html
       %head
-        %link{ :rel => 'stylesheet', :href => stylesheet }
-    
+        %link(rel='stylesheet' href=stylesheet)
+
       %body
         #container= content
-    
+
 ### Style your content ###
 
-You can build stylesheets using [CSS][], [Sass/Scss][] or [Less][].
+You can build stylesheets using [Css][], [Sass/Scss][] or [Less][]. They will
+always be compiled. They will only be copied, though, if you specify a style
+destination.
 
 [Tilt templates]: http://github.com/rtomayko/tilt/blob/master/TEMPLATES.md "A listing of all templates supported by Tilt."
-[CSS]: http://en.wikipedia.org/wiki/Cascading_Style_Sheets
+[Css]: http://en.wikipedia.org/wiki/Cascading_Style_Sheets
 [Sass/Scss]: http://sass-lang.com/
 [Less]: http://lesscss.org/
 
-Mint comes preloaded with several styles and layouts:
+Mint comes preloaded with several styles and layouts.
 
 1. Default
 2. Serif Pro
 3. Sans Pro
 4. Protocol
-5. Protocol Flow - requires Javascript
+5. Protocol Flow - requires Javascript and jQuery
 6. Resume
 
+> Note: These aren't all designed yet. Also, 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.
+
 IV. The Mint path
 -----------------
 
-Mint's path can be useful for a lot of things, especially for extensions and tools that use the library. The most important use for the path in the library is to find named templates.
+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.)
 
-When given a style or layout name (instead of a file name), Mint will search its paths in order until it finds the appropriate template. If no template is found, it will fall back to the default template.
+So here's the rundown.
+
+When you name a layout or style with a string or symbol, Mint will first search the current directory for that file or file path. If that file does not exist, Mint will search its path in order until it finds the appropriate template. If no template is found, it will fall back to the default template.
 
 The default Mint path (in order) is:
 
 - the current working directory
-- HOME_DIRECTORY/.mint
-- /usr/share/mint (or whatever your system uses for system-wide configuration)
-- the gem's source directory (as a final effort)
+- ${HOME}/.mint
+- /usr/share/mint (or whatever your system uses for system-wide configuration - Mint will make a smart guess)
+- the Mint gem directory (which holds the Mint-approved templates)
 
 Templates should be in a directory named templates. Inside this directory, there should be a subdirectory for each template:
 
-- PATH/templates/normal/style.sass
-- PATH/templates/normal/layout.haml
-  
-Normally a style will go best with its complement layout. However, layouts and styles can be mixed and matched at your discretion. This is especially true where you are not using stylesheets to format specific IDs or classes you're expecting to find in your layout. (In other words, this works best when you're focused on typography and not page layout.)
+- ${MINT\_PATH}/templates/normal/style.css
+- ${MINT\_PATH}/templates/normal/layout.haml
+
+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 is not yet functional.*
+*The `mint` command is almost functional. Testing is in development.*
 
 ### The basic `mint` command ###
 
-The easiest Mint command doesn't require configuration. It will transform all of your Documents into HTML and link all of them to the default stylesheet, which will be output in the same directory as the source documents.
+The easiest Mint command doesn't require configuration. It will transform the specified document into HTML and link it to the default stylesheet, which will be output in the same directory as the source documents. (If you have a ./templates/default/ subdirectory, the templates found in that directory will be used.)
+
+    mint Minimalism.md                    # creates Minimalism.html
+
+You can throw as many files as you'd like in. Any commandline argument *not* preceded by an option (e.g., `--template`) or in the `mint` command vocabulary (more on that in a minute) will be interpreted as a file name:
+
+    mint Minimalism.md Proposal.md Protocol.md
 
-  mint
-  
-If you have a ./templates/default/ subdirectory, the templates found in that directory will be used.
-  
 This command can be tweaked with options and arguments to be more flexible:
 
-    mint Minimalism.md                  # renders a specific file
-    mint Minimalism.md Final.html       # specifies an output file
-    mint Minimalism.md --style=resume   # specifies a style template
-    mint Minimalism.md --root=~/Documents/Minimalism --style=default --style-destination=styles
+    mint Minimalism.md --template resume  # specifies a style template
+    mint Minimalism.md --destination final --style-destination=styles
 
-### Mint options &amp; shortcuts ###
+### Mint options & shortcuts ###
 
-You can pass several options to `mint`. Each option has a short form.
+You can pass several options to `mint`. Following the Unix tradition, common options have a short and long form.
 
 The following correspond to the parameters you can pass to `Mint::Document.new`, as described in [The Mint library][]:
 
-- `--layout, -L`
-- `--style, -S`
-- `--root, -R`
-- `--destination, -D`
-- `--name, -N`
-- `--style-destination`
-- `--style-name`
+- `--template, -t`
+- `--layout, -l`
+- `--style, -s`
+- `--destination, -d`
+- `--style-destination, -n`
+- `--copy-style`
+
+There are also scoping options, both for the `set` and `edit` commands:
+
+- `--global, -G`
+- `--user, -U`
+- `--local, -L`
+
+*If you've used `MINT_PATH` to set up Mint, then you should be aware that
+`--local` refers to the first element, `--user` refers to the second, and
+`--global` refers to the third.*
 
 Other options have nothing to do with document configuration but are there for convenience:
 
@@ -288,92 +288,82 @@ Other options have nothing to do with document configuration but are there for c
 
 [The Mint library]: #ii_the_mint_library
 
-### Mint projects ###
+### `mint` command vocabulary ###
 
-A more powerful and reconfigurable version of Mint uses Mint projects. To initialize a project in the current directory:
+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.
 
-    mint init 
+Currently, the `mint` vocabulary consists of `set`, `edit`, and `config`. 
 
-The following does the same thing, but all documents rendered in this project will use the normal template (both layout and style) by default.
-  
-    mint init --template normal
+### `mint` configuration ###
 
-The following does the same thing, but all documents rendered in this project will use the protocol.haml layout and serif-professional style by default.
-  
-    mint init --layout protocol.haml --style serif-professional
-  
-You will want to make sure that your layouts and styles are compatible. Most text-heavy layouts should be compatible with any style (and Mint is made for text-heavy documents). If you're using Mint with specialized style files, though, and expect certain IDs and classes in your layout document, you will want to check for layout/style compatibility.
+`mint` is capable of using config files to harness the power of convention without sacrificing the flexibility of configuration. You can configure `mint` on a global, user-wide, or local (directory-specific) scale to avoid passing commandline options every time you call `mint`.
 
-A project stores references to all of its documents. You can list documents with:
+To set a local (directory-specific) configuration option, call `mint set`:
 
-    mint list
+    mint set [local] --template serif-professional --destination final
 
-You can find out which documents have been minted (and where), along with any universal templates using:
+This will create (or update) a config file: ./.mint/config.yml
 
-    mint status
-  
-### Project configuration ###
+It will contain:
 
-Mint projects can be associated with [Yaml configuration files][Yaml]. These files are created if you pass any options to `mint init` when you create a project. Alternatively, you can set global configuration options after creating a project:
+    template: serif-professional
+    destination: final
 
-    mint set --template serif-pro
+From now on, calling `mint` in this directory will automatically draw on these two options. (Commandline options will override these file options.)
 
-Projects use configuration files *and not command-line options* to determine how they should behave. You can modify the config file through the command line, but do not use the command line to pass options while minting an entire project.
+You can also set user-wide options:
 
-In other words, this is okay for minting a single file:
+    mint set --user template=professional
 
-    mint --template normal
-    
-It is *not* okay if you are inside a project. In this case, you SHOULD alter the configuration file (via command line or an editor) and then type:
+Doing so will create the same style config file, but in your system's user-wide configuration location:
+
+- In Linux and other FHS-compliant systems, and on Mac OS X this 
+  will be in ~/.mint/config.yaml
+- In Windows, this will be *(somewhere dumb...)*
+
+Finally, you can set global options for all users:
+
+    mint set --global template=normal
 
-    mint
-  
-The config.yaml file can include the following options:
- 
-    layout: normal
-    destination: output
-    style: normal
-    style_destination: styles
-    template: resume # overrides layout and style options
+This configuration affects all users and will be put somewhere appropriate:
 
-[...]
+- In Linux and on other FHS-compliant systems, this will be in /usr/share/mint
+- On Mac OS X, this is going to land somewhere unknown, possibly inside 
+  of /Library/Application Support/Mint or /usr/share/mint -- I haven't decided
+- On Windows, this will end up *(somewhere dumber than before)*
 
-These files give you the power to unify a project with a certain layout and style.
-  
-If configuration options get complicated, it may be useful to list all active defaults:
+These options give you the power to unify a directory or user or all users under a certain default layout and style. These options are all overridden via commandline options and only provide defaults so that you can save typing common commands. `mint` selects the most specific option possible, starting with the commandline, then checking local the config file, and finally moving to the user-wide and global config files.
+
+If configuration options get complicated, it may be useful to list all active defaults, with more specific options replacing more general ones per above:
 
     mint config
-  
+
 [Yaml]: http://yaml.org/
-  
+
 ### Editing files in a project ###
 
-Inside of a project directory, you can edit any stylesheet or document template that would normally be used by the project without delving into the Mint templates directories.
+Inside of a directory, you can edit any stylesheet or document template that would normally be used in your current context without delving into the Mint templates directories, except of course the default templates provided with Mint.
+
+    # Selects the first template in your path with the appropriate name:
+    mint edit --layout my-fun-layout
+    mint edit --style snazzy-styles
 
-    mint edit --layout default    # selects the first template in your path
-    mint edit --style normal      # with the appropriate name
+    # Selects the template from a specified context
+    mint edit user --layout my-fun-layout
 
-Mint will open the appropriate file in the editor specified by EDITOR. There is a short form for each option:
+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
 
-To remove all mint-generated files in a directory (or for a package):
-
-    mint restore .
-
 VI. 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.
 
-### Possible next steps ###
-
-I might introduce the concept of a project registry. This would allow for interlinking between Mint projects scattered around a system, or perhaps even remotely. (How useful would a remote link be without the Web, though?)
-
-`mint init` would register a project, whose name would be based on its parent directory. The project directory would be a user-wide listing that could allow hyperlinking between separate Mint projects, along with use of common stylesheets. There would also be a manual option:
+### Composed styles ###
 
-    mint add --project ~/Projects/NamedProject --name=NamedProject
+Not everyone wants to code an entire stylesheet every time he wants a new look. In fact, the most common use case for stylesheets is probably tweaking typography. For this reason (and to make this tool as accessible as possible), I want to implement a feature where you can select one stylesheet as a base and implement tweaks on top of that file. Of course Css makes this easy enough, but I want to implement this feature in such a way that it is easy and intuitive for everyone.
 
 ### Packages ###
 
@@ -383,57 +373,14 @@ Sometimes, it may be useful to "finalize" the design of a document, for example,
 
 To package a document with its stylesheet, as a sort of a printing:
 
-    mint package document.md --name Document # will get the extension .pkg?
-  
-Eventually, I want this to include multiple output formats, like HTML4, HTML5, PDF and ePub. The format opened by the `mint open` command could be determined by the application you choose to open it with.
+    mint package document.md --name Document
 
-When that does happen, you'll also be able to set the default version of the document that will open using:
-
-    mint set --package-default html5
-
-### My dreams about Mint, and where it could go ###
-
-I have more ideas for Mint, but they are probably far-off pipe dreams.
+Eventually, this could include multiple output formats, like Html4, Html5, Pdf and ePub. The format opened by the `mint open` command could be determined by the application you choose to open it with. (This would take some serious OS hacking, I think.)
 
-What if Mint were social and a good citizen with respect to data portability? This could look like:
-
-    mint share --user http://davejacobs.myopenid.com/
-    mint share --user =david --service freeXRI
-    mint share --user @dave_jacobs --service twitter
-    mint share --service twitter
-
-For this last command, Mint would upload an HTML to a preconfigured FTP server or web application and then post a link to that document in the recipient's Twitter stream. I'm not sure exactly how this would go.
+When that does happen, you'll also be able to set the default version of the document that will open using:
 
-The configuration file could look something like:
-  
-    services:
-      - twitter:
-          authorization: OAuth
-          key: etc.
+    mint set [local] --package-default html5
     
-      - openid:
-          url: http://davejacobs.myopenid.com/
-          authorization: OAuth
-          key: etc.
- 
-Or you could publish multiple output formats, and to multiple locations: 
-        
-    mint publish --ftp default
-    mint publish --blog personal
-
-The configuration:
-  
-    publishers:
-      - ftp:
-        - default:
-            server: ftp.provider.com
-            security: sftp
-            directory: /home/USERNAME/example.com/documents
-      - blog:
-        - personal:
-
-Or you could connect to a service to protect your intellectual property rights:   
-
-    mint copyright
-
-I don't know if this is even possible, but wouldn't it be cool to generate a unique number based on the date, time, and contents of any article published and assign it to the article as a hash of all its metadata. The number would be so complex that you could not generate it without all the appropriate data. And using all the appropriate metadata (including date) would give the same number every time. But somehow, the algorithm would have to never run after the current date, so that potential plagiarists could not figure out what the hash should be for a date previous to the date you published it. That idea needs work, but I feel like maybe it could work out, probably as a separate service. Wouldn't it be cool?
+### More ###
+
+More ideas are coming soon...