middlemac 2.0.0

data/bin/middlemac

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+
+################################################################################
+# middlemac
+#  This file constitutes the command line interface for middlemac
+################################################################################
+
+require 'thor'
+require 'fileutils'
+require_relative '../lib/middlemac/version'
+
+
+module MiddlemacCli
+
+  class Cli < Thor
+
+    map %w[--version -v] => :__print_version
+
+    ############################################################
+    # help
+    #  Override to add additional description.
+    ############################################################
+    def help(*args)
+      if args.count == 0
+        puts <<-HEREDOC
+
+middlemac version #{Middleman::Middlemac::VERSION}
+
+This gem adds functionality to Middleman and is not executable on its own,
+other than for generating the documentation sample project and/or a blank
+starter project. Instead, you must add this gem to your Middleman project's
+`Gemfile` and then activate it in your `config.rb` file. 
+
+HEREDOC
+      end
+      super
+    end
+
+
+    ############################################################
+    # documentation
+    ############################################################
+    desc 'documentation', 'Install the sample project into your current working directory.'
+    long_desc <<-HEREDOC
+`documentation` will produce a sample project named `middlemac-docs/`
+in your current working directory. This sample uses the features of this gem.
+You can then serve this new project to read the documentation by:
+
+cd middlemac-docs
+bundle install
+bundle exec middleman server
+    
+    HEREDOC
+    def documentation
+      source = File.join('..', '..', 'documentation_project', '.')
+      source = File.expand_path(source, __FILE__)
+      dest = File.expand_path(File.join('.', 'middlemac-docs', '.'))
+      FileUtils.cp_r(source, dest)
+      puts "middlemac installed the project in\n#{dest}" 
+    end
+
+
+    ############################################################
+    # init
+    ############################################################
+    desc 'init', 'Install a (mostly) blank project into your current working directory.'
+    long_desc <<-HEREDOC
+`init` will produce a nearly blank project named `middlemac-init/` in you
+current working directory. It is a minimal, buildable project that you can
+serve and test by:
+
+cd middlemac-init
+bundle install
+bundle exec middleman server
+    
+    HEREDOC
+    def init
+      source = File.join('..', '..', 'fixtures', 'middlemac_app', '.')
+      source = File.expand_path(source, __FILE__)
+      dest = File.expand_path(File.join('.', 'middlemac-init', '.'))
+      FileUtils.cp_r(source, dest)
+      puts "middlemac installed the project in\n#{dest}" 
+    end
+
+
+    ############################################################
+    # __print_version
+    ############################################################
+    desc '--version, -v', 'print the version'
+    def __print_version
+      puts "middlemac-extras version #{Middleman::Middlemac::VERSION}"
+    end
+
+  end # class Cli
+
+end # module MiddlemacCli
+
+
+###########################################################
+# Main
+###########################################################
+
+MiddlemacCli::Cli.start(ARGV)

data/documentation_project/.gitignore

@@ -0,0 +1,37 @@
+# Rubymine noise
+.idea/
+
+# BBedit noise
+*.bbprojectd
+
+# Mac OS X noise
+.DS_Store
+
+# Ignore bundler lock files
+Gemfile.lock
+
+# Ignore pkg folder
+/pkg
+
+# Ignore build folders
+.rbenv-*
+.ruby-gemset
+.ruby-version
+.sass-cache
+.sassc
+.tmp
+build*
+Makefile
+tmp
+
+# XCode user-specific files
+*.pbxuser
+!default.pbxuser
+*.mode1v3
+!default.mode1v3
+*.mode2v3
+!default.mode2v3
+*.perspectivev3
+!default.perspectivev3
+xcuserdata/
+

data/documentation_project/Contents/Info.plist.erb

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleIdentifier</key>
+	<string><%= cfBundleIdentifier %></string>
+	<key>CFBundleName</key>
+	<string><%= cfBundleName %></string>
+	<key>HPDBookAccessPath</key>
+	<string>index.html</string>
+	<key>HPDBookIndexPath</key>
+	<string><%= cfBundleName %>.helpindex</string>
+	<key>HPDBookTitle</key>
+	<string><%= cfBundleName %> Help</string>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>en-us</string>
+	<key>CFBundleShortVersionString</key>
+	<string><%= config[:targets][config[:target]][:CFBundleShortVersionString] || product_version %></string>
+	<key>CFBundleVersion</key>
+	<string><%= config[:targets][config[:target]][:CFBundleVersion] || product_version %></string>
+	<key>HPDBookIconPath</key>
+	<string><%= config[:targets][config[:target]][:HPDBookIconPath] || 'shared/icon_32x32@2x.png' %></string>
+	<key>HPDBookKBProduct</key>
+	<string><%= config[:targets][config[:target]][:HPDBookKBProduct] %></string>
+	<key>HPDBookKBURL</key>
+	<string><%= config[:targets][config[:target]][:HPDBookKBURL] || product_uri %></string>
+	<key>HPDBookRemoteURL</key>
+	<string><%= config[:targets][config[:target]][:HPDBookRemoteURL] %></string>
+	<key>HPDBookTopicListCSSPath</key>
+	<string><%= config[:targets][config[:target]][:HPDBookTopicListCSSPath] %></string>
+	<key>HPDBookTopicListTemplatePath</key>
+	<string><%= config[:targets][config[:target]][:HPDBookTopicListTemplatePath] %></string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundlePackageType</key>
+	<string>BNDL</string>
+	<key>CFBundleSignature</key>
+	<string>hbwr</string>
+	<key>HPDBookType</key>
+	<string>3</string>
+</dict>
+</plist>

data/documentation_project/Contents/Resources/Base.lproj/010_what_is_middlemac/index.html.md.erb

@@ -0,0 +1,126 @@
+---
+title:  What is <em>Middlemac</em>?
+blurb:  Discover what <em>Middlemac</em> can do for you, why it exists, and 
+        what it’s made out of.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+## What does _Middlemac_ do?
+
+_Middlemac_ makes it simple to do this in Terminal…
+
+`bundle exec middleman build_all`
+
+…and end up with versions of your help books specific to each version of your
+Mac OS X application, with all of the Apple-required files in the Apple-required
+formats in the correct locations of your Xcode source directory. Simply build
+your help target, run your application, and find that it just works.
+
+## Yeah, but what does it _do_?
+
+_Middlemac_, using _Middleman_, takes a directory of source files, processes all
+of the contents, and produces a finished Apple Help Book. The source files can
+be standard HTML or Markdown, and _Middlemac_ takes care of nearly all of the
+nitty gritty details for you.
+
+- Write your help files with plain text using the
+  [Markdown](http://kramdown.gettalong.org/) format.
+  
+~~~ markdown
+# Read this headline!
+Markdown makes it easy to write text that’s legible in its text form and that
+renders very easily to HTML.
+~~~
+
+- It decouples your content from your visual design and from HTML document
+  formats via the use of [templates][templates]. The templates can be used
+  as-is or easily tweaked to suit your needs, and they include a basic,
+  Apple-like CSS stylesheet offering a reasonably attractive out-of-the-box
+  appearance.
+
+- Single or multiple build [targets][targets], e.g., your `pro` target can
+  include content specific to the professional version of your application.
+  **For example, the current target of this documentation is `<%= target_name
+  %>`**.
+  
+- [Features][features] support for each build target. For example each of your
+  build targets can specify whether or not they support specific features, and
+  this content will be included or excluded as your needs require. This offers
+  highly granular control versus trying to manage complex targets on their own.
+  
+- A low [learning curve][skills_refresher-index], especially if you’re already a
+  developer.
+
+- A set of conventions and tools that make automatic tables of contents,
+  automatic sections, breadcrumbs, and other automatic navigation behavior 
+  simple to implement.
+  
+- [Partials][partials], [helpers][helpers], and [resource methods][resources]
+  that make your static help documents appear more dynamic while
+  [keeping yourself DRY](http://en.wikipedia.org/wiki/Don't_repeat_yourself).
+    
+- Automatic management of `Info.plist` and `InfoPlist.strings` files make it
+  simple to work with Xcode.
+
+- Automatic use of Apple’s help indexer tool ensures that the Help Viewer
+  is always aware of your content.
+
+
+## Why _Middlemac_ exists
+
+_Middlemac_ exists to solve these two problems:
+
+- **How do I build help files for my Mac OS X applications?** Although 
+  ostensibly a simple set of HTML files, a Mac OS X help book requires careful
+  application of data in order for the help book to interface properly with
+  your application. And for historical reasons, some of the pages have to use
+  different HTML versions.
+
+- **How do I manage help files for multiple versions of my Mac OS X
+  applications, each of which has a different feature set?** Although
+  _Middlemac_ is great for applications that have a single version, it really
+  excels when managing applications that have multiple versions (such as Free
+  or Pro). _Middlemac_ makes it simple to produce help documents specific to
+  these versions, all using the same source.
+
+
+## What is _Middlemac_ made of?
+
+_Middlemac_ is a system of Gems that act as an extension to _Middleman_, a
+static site building tool that offers a lot of dynamism to static web sites.
+Without _Middleman_, nothing else in _Middlemac_ would work.
+
+_Middlemac_ consists of the gems:
+
+`middlemac`
+
+  : This gem requires all of the other gems in the system and adds several
+    helpers to make working with target and feature much more convenient. It’s
+    also responsible for providing the basic help book template and managing the
+    Apple help indexer.
+
+`middlemac-extras`
+
+  : This gem adds features to _Middleman_ to make working with images and
+    Markdown reference style links easier. It’s released as a separate gem
+    because it can still be useful for standard _Middleman_ projects.
+
+`middleman-pagegroups`
+
+  : This gem offers all of the automatic navigation features used by
+    _Middlemac_. It’s released as a separate gem because it can still be useful
+    for standard _Middleman_ projects.
+
+`middleman-targets`
+
+  : This gem gives _Middleman_ the ability to build and serve multiple targets.
+    It’s released as a separate gem because it can still be useful for
+    standard _Middleman_ projects.

data/documentation_project/Contents/Resources/Base.lproj/020_setup_tutorial/index.html.md.erb

@@ -0,0 +1,168 @@
+---
+title:  Setting up <em>Middlemac</em>
+blurb:  Read this article to learn how install <em>Middlemac</em> and see
+        that it’s running on your system.
+layout: template-logo-small
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+Getting Started
+---------------
+
+_Middlemac_’s documentation is included in the starter project (and more than
+likely at [http://www.balthisar.com/manuals](http://www.balthisar.com/manuals)).
+There are multiple ways you could be reading this content now, but for now we
+will assume that you have not yet installed _Middlemac_ and its dependencies.
+
+To get started and read the full documentation, make sure that your system has
+[Ruby](https://www.ruby-lang.org/) installed (it comes pre-installed on Mac OS X
+and some Linuxes), and follow these steps below. 
+
+We now recommend the use of the Ruby Version Manager [(RVM)](https://rvm.io/).
+While installation and setup of RVM is entirely outside the scope of this
+tutorial, it avoids the use of `sudo` and the occasional hassles involved with
+using the built in version of Ruby.
+{:.note}
+
+Note that depending on your system’s setup you might have to prefix some of the
+commands below with `sudo`. For example if the instruction is given as
+`gem install bundler` and a permissions error is reported, you may probably
+have to use `sudo gem install bundler` instead.
+{:.note}
+
+If you’re behind a proxy and haven’t already setup an `http-proxy` environment
+variable, then that previous clause is a good hint and Google is your friend.
+{:.note}
+
+
+Quick version, if you don’t want to read details
+------------------------------------------------
+
+In your Terminal, do each of the following:
+
+~~~ bash
+xcode-select --install
+gem install middlemac
+middlemac documentation
+cd middlemac-docs
+gem install bundler
+bundle install
+bundle exec middleman --target free
+open middlemac.webloc
+~~~
+
+Because the penultimate command started the server which keeps control of the
+terminal, you’ll have to open the `.webloc` file in another terminal session,
+or simply double-click it.
+
+If you’re on Linux and `open middlemac.webloc` command doesn’t work for you,
+then use your preferred web browser and go to
+[http://localhost:4567/Resources/Base.lproj/](http://localhost:4567/Resources/Base.lproj/).
+
+If you’ve setup your own custom domain, you’ll have to specify that instead of
+`localhost`.
+
+
+Similar to above, with a bit of handholding
+----------------------------------------
+
+### Install Xcode
+
+If you’re on a Mac you’ll have to install Xcode first, or at least the Xcode
+command line tools. You can _try_ just installing the tools first:
+
+~~~ bash
+xcode-select --install
+~~~
+
+If that fails or the rest of the installation fails, then install all of Xcode.
+It’s available in the App Store. It’s free of charge. And you’re using this
+project to develop help for Mac OS X applications that you’re developing using
+Xcode anyway. Install it, already!
+
+Dependencies on Linux are left up to you. Most modern Linuxes will prompt you to
+install packages that are missing.
+ 
+_Middlemac_ works quite well on Linux, but keep in mind that Linux doesn’t have
+the help indexing tool that’s required in order to build a proper help book.
+Other than for generating your final help book, Linux makes a fine development
+environment.
+{:.note} 
+
+
+### Install the `middlemac` gem
+
+~~~ bash
+gem install middlemac
+~~~
+
+This will fetch the gem from `rubygems.org` and install it for you.
+
+
+### Install the documentation
+
+~~~ bash
+middlemac documentation
+~~~
+
+This will install Middlemac’s documentation project into a new directory
+`middlemac-docs`.
+
+
+### Go into the documentation directory
+
+~~~ bash
+cd middlemac-docs
+~~~
+
+
+### Install bundler (if not already installed)
+
+~~~ bash
+gem install bundler
+~~~
+
+Bundler is the most common Ruby package management system, and it will be used
+to ensure that all of Middlemac’s dependencies are present.
+
+
+### Make sure all of the project dependencies are met
+
+~~~ bash
+bundle install
+~~~
+
+This tells bundler to install the remaining gems that _Middlemac_ requires to
+function.
+
+
+### Start the _Middleman_ server
+
+_Middleman_ comes with its own HTTP server and requires no configuration. It
+simply works, serving your help book as a website.
+
+~~~ bash
+bundle exec middleman --target free
+~~~
+
+This will start the server using our `:free` target.
+
+
+### Open the site in your browser
+
+Simply open the `middlemac.webloc` file from Finder to view the project results
+in your default browser.
+
+Or can open the bookmark file from Terminal with `open middleman.webloc`.
+
+Or you prefer to open the help site manually, or if the .webloc file doesn’t
+work on your Linux distro, you can go to
+[http://localhost:4567/Resources/Base.lproj/](http://localhost:4567/Resources/Base.lproj/).
+
+If you’ve setup your own custom domain, you’ll have to specify that instead of
+`localhost`.