middlemac 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d2b3410abbcf1647fe5bb583455675fc72a44c94
+  data.tar.gz: 92adcc43e61ddf09e65e84c99eb031fb183b3cb1
+SHA512:
+  metadata.gz: b8ec6cd32d7a0f7c23fff233455cb8b9d52ab4031db52c3561516f06879ba07f915142f70c208f0da68c23d88ac696ecd1eb889c6a52a8dbbed059d30624fb0e
+  data.tar.gz: e523e9deb1141f927269495e61aa0fa8afdde9105f8e9fef6545e6cb88c12f156d599e708713b0e94a69968d7060a73cd8964606fbfe2d94c1ff69d3723019d4

data/.gitignore

@@ -0,0 +1,24 @@
+# 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
+build/*
+
+# Yard cruft
+/doc/
+/.yardoc
+
+# Aruba
+/tmp/

data/.yardopts

@@ -0,0 +1,7 @@
+--no-private
+--markup=markdown
+--load yard/yard_extensions.rb
+--exclude middlemac/version.rb
+--one-file
+--readme yard/readme.md
+--title middlemac

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+middlemac change log
+====================
+
+- Version 2.0.0 / 2016-May-15
+
+  - All new Middlemac version 2.0.0!
+      - _Significant_, major upgrade to _Middlemac_.
+      - Now packaged as a real Ruby gem.
+      - Uses the latest Middleman 4.1 series (4.1.7 or newer required).
+      - This version _will_ break old projects.
+      - Read the full documentation to understand the full scope of changes.
+
+- Previous
+  - Updated to newer middleman.
+    - Use font-awesome-sass gem instead of keeping it in the file system.
+  - Fixed 256x256 image file.
+  - Added built output. RC1
+  - Content. Readme. Version.
+  - Ibid.
+  - More content added.
+  - Typo.
+  - More content
+  - More yummy content\!
+  - Partials overview complete.
+  - More content. yay
+  - Added new content.
+  - Header information added.
+  - Header information added.
+  - Content cleanup; new features content.
+  - Reverted to full breadcrumbs; breadcrumb css tweak.
+  - Separate navigate (children do) and navigator (I do)
+  - Content enhancements.
+  - Fixed indentation error.
+  - README, getting started.
+  - Overhaul of helpers and sitemap manipulators complete.
+  - BRETHREN checkpoint
+  - Continued refactoring resources.
+  - Begin refactor helpers to methods.
+  - Topical content.
+  - Bug-proofing.
+  - Added topical content.
+  - Removed conflicting LESS stuff.
+  - More content.

data/Gemfile

@@ -0,0 +1,18 @@
+# If you do not have OpenSSL installed, update
+# the following line to use "http://" instead
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in middleman-pagegroups.gemspec
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'rdoc'
+  gem 'yard'
+end
+
+group :test do
+  gem 'cucumber'
+  gem 'aruba'
+  gem 'rspec'
+end

data/LICENSE.md

@@ -0,0 +1,22 @@
+The MIT License
+===============
+
+Copyright (c) 2016 Jim Derry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+Middlemac, the Middleman Build System for Mac OS X Help Projects
+================================================================
+[![Gem Version](https://badge.fury.io/rb/middlemac.svg)](https://badge.fury.io/rb/middlemac)
+
+
+_Middlemac_
+
+This gem provides a complete solution to generating help documentation for
+Mac OS X applications in the form of Help Books, using Middleman and a
+selection of custom extensions to provide everything a developer needs.
+
+Using this Apple Help Book building system leverages the tools of _Middleman_ to
+make building end-user documentation for your Mac OS X applications a snap.
+Whether you are targeting multiple versions of your application or a single
+version, once properly configured, _Middlemac_ will take all of the pain out of
+building help files.
+
+
+Simple README
+-------------
+Jump to the [verbose README](#verbose-readme) and instructions below, otherwise…
+
+
+Install the Gem
+---------------
+
+Install the gem in your preferred way, typically:
+
+~~~ bash
+gem install middlemac
+~~~
+
+From git source:
+
+~~~ bash
+rake install
+~~~
+
+
+Documentation
+-------------
+
+The complete documentation leverages the features of this gem in order to better
+document them. Having installed the gem, read the full documentation in your
+web browser:
+
+~~~ bash
+middlemac documentation
+cd middlemac-docs/
+bundle install
+bundle exec middleman server
+~~~
+   
+And then open your web browser to the address specified (typically
+`localhost:4567`).
+
+
+License
+-------
+
+MIT. See `LICENSE.md`.
+
+
+Changelog
+---------
+
+See `CHANGELOG.md` for point changes, or simply have a look at the commit
+history for non-version changes (such as readme updates).
+
+
+Verbose README
+==============
+
+About
+-----
+
+_Middlemac_ makes it simple to do this in Terminal…
+
+`bundle exec middleman build_all`
+
+…and end up with versions of your helpbooks with all of the Apple-required files
+in the Apple-required formats in the correct locations of your XCode build
+directory. Simply build your help target, run your application, and find that
+it just works!
+
+At its simplest _Middlemac_ offers:
+
+- Write your help files with plain text using the **Markdown** format (if you
+  are reading this file in a text editor, this is an example of Markdown).
+- Single or multiple build **targets**, e.g., your `pro` target can include
+  content specific to the professional version of your application.
+- **Features** support for each build target, e.g. 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.
+- A low learning curve if you’re a developer.
+- A set of conventions and tools that make automatic tables of contents,
+  automatic sections, and automatic behavior effortless to implement.
+- A basic, Apple-like CSS stylesheet and set of templates that can be used as-is
+  or easily tweaked to suit your needs.
+
+
+**Please note that _Middlemac_ is not associated in any way with the team at
+_Middleman_.**  
+
+
+Documentation
+-------------
+
+_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 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.
+
+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.
+
+
+Installation
+------------
+
+### 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 helpbook.
+Other than for generating your final helpbook, Linux makes a fine development
+environment.
+
+
+### Install _Middlemac_
+
+~~~ bash
+gem install middlemac
+~~~
+
+### Install the documentation project
+
+~~~ bash
+middleman 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 helpbook 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 usually go to
+[http://localhost:4567/Resources/Base.lproj/](http://localhost:4567/Resources/Base.lproj/).
+If you have setup a custom hostname, then `localhost` may not work for you.
+
+See also the [change log](CHANGELOG.md) and the [license](LICENSE.md).

data/Rakefile

@@ -0,0 +1,213 @@
+require 'bundler/gem_tasks'
+require 'cucumber/rake/task'
+require 'yard'
+require 'git'
+require File.expand_path('../lib/middlemac/version.rb', __FILE__)
+
+
+###############################################################################
+# :default
+#   Define the default task.
+###############################################################################
+task :default => :test
+
+
+###############################################################################
+# :test
+#   Perform Cucumber testing.
+###############################################################################
+Cucumber::Rake::Task.new(:test, 'Features that must pass') do |task|
+  task.cucumber_opts = '--require features --color --tags ~@wip --strict --format QuietFormatter'
+end
+
+
+###############################################################################
+# :yard
+#   Generate documentation using YARD. Note that there is a `.yardopts` file
+#   present that will load the `yard/yard_extensions.rb` file in order to
+#   control how output is generated. Output will be to the default `doc`
+#   directory using the template-grouped template, as a single page.
+###############################################################################
+YARD::Rake::YardocTask.new(:yard) do |task|
+  task.stats_options = ['--list-undoc']
+end
+
+
+###############################################################################
+# :partials
+#   Generate documentation partials using YARD. These are used by the
+#   documentation project in order to include the API documentation.
+###############################################################################
+desc 'Make separate documents for documentation_project'
+task :partials do
+
+  # Define the @!group to output file relationships.
+  sections = [
+      { :file => '_yard_middlemac_helpers.erb',          :group => 'Helpers',  },
+      { :file => '_yard_middlemac_helpers_extended.erb', :group => 'Extended Helpers' },
+      { :file => '_yard_middlemac_config.erb',           :group => 'Extension Configuration' },
+  ]
+  
+  # Define the output directory.
+  dest = File.join('documentation_project', 'Contents', 'Resources', 'Base.lproj', 'assets', 'partials')
+
+  # Run YARD multiple times, filtering the group that interests us.
+  sections.each do |s|
+    params = [
+      "--query 'o.group == \"#{s[:group]}\" || has_tag?(:author)'",
+      "-o #{dest}",
+      "-t default",
+      "-p #{File.join(File.dirname(__FILE__), 'yard', 'template-partials')}"     
+     ]
+    command = "yardoc #{params.join(' ')}"
+    puts command
+    system(command)
+    File.rename( File.join(dest, 'index.html'), File.join(dest, s[:file]) )
+  end
+
+end
+
+
+###############################################################################
+# :version
+#   Displays the current version.
+###############################################################################
+desc 'Displays the current version'
+task :version do
+  puts "Current version: #{Middleman::Middlemac::VERSION}"
+end
+
+
+###############################################################################
+# :version_finalize
+#   Remove any wip suffix from the version, as we are ready to release.
+###############################################################################
+desc 'Remove any wip suffix from the version'
+task :version_finalize do
+  version_old = Middleman::Middlemac::VERSION
+  version_new = version_old.sub('.wip', '')
+  update_versions( version_new )
+end
+
+
+###############################################################################
+# :version_next_wip
+#   Increment the patch level and add a wip suffix. We are ready for work.
+###############################################################################
+desc 'Increment the patch level and add a wip suffix'
+task :version_next_wip do
+  version_old = Middleman::Middlemac::VERSION
+  version_new = version_old.sub('.wip', '').split('.')
+  version_new.last.succ!
+  version_new = version_new.join('.') + '.wip'
+  update_versions( version_new )
+end
+
+
+###############################################################################
+# :version_set
+#   Sets an arbitrary version.
+###############################################################################
+desc 'Sets all of the files to the version specified. Use rake version_set[value].'
+task :version_set, :new_version do |t, args|
+  update_versions( args[:new_version] )
+end
+
+
+###############################################################################
+# :log
+#   Generate the CHANGELOG.md file.
+###############################################################################
+desc 'Generate the CHANGELOG.md file'
+task :log do
+  report = ''
+  report << "middlemac change log\n"
+  report << "====================\n"
+
+  Git.open( File.expand_path('..', __FILE__) ).log.each_with_index do |l, i|
+
+    version = nil
+    if i == 0 && !l.name.start_with?('tags/')
+      version = "Version #{Middleman::Middlemac::VERSION}"
+    elsif l.name.end_with?('^0')
+      version = "Version #{l.name.match(/tags\/v(.*)\^0/)[1]}"
+    end
+    
+    if version
+      report << "\n- #{version} / #{l.date.strftime('%Y-%B-%d')}\n"
+      report << "\n"
+    end
+    
+    l.message.each_line.with_index do |line, lineno| 
+      if lineno == 0
+        report << "  - #{line}"
+      else
+        report << "    #{line}" unless line.strip == ''
+      end
+    end
+    report << "\n"
+  end # Git.open
+
+  file = File.expand_path('../CHANGELOG.md', __FILE__)
+  File.write(file, report)
+  puts "The changelog has been written."
+end
+
+
+###############################################################################
+# :pre_release
+#   Prepares the project for release.
+###############################################################################
+desc "Prepares the project for release"
+task :pre_release do
+
+  if `git status -s`.length > 0
+    puts "Cannot continue because you have uncommitted changes."
+    exit 1
+  end
+
+  Rake::Task[:version_finalize].execute
+  Rake::Task[:partials].execute
+  Rake::Task[:log].execute
+  sh "git add -A"
+  sh "git commit --amend --no-edit"
+end
+
+private
+
+
+###############################################################################
+# update_versions
+#   Update the version in various files that depend on the correct version.
+###############################################################################
+def update_versions( version_new )
+  [ {
+      :file  => File.expand_path('../lib/middlemac/version.rb', __FILE__),
+      :regex => /(?<=VERSION = ')(.*)(?=')/
+    },
+    {
+      :file  => File.expand_path('../documentation_project/Gemfile', __FILE__),
+      :regex => /(?<=gem 'middlemac', '~> ).*(?=')/
+    },
+    {
+      :file  => File.expand_path('../documentation_project/config.rb', __FILE__),
+      :regex => /(?<=:ProductVersion   => ')(.*)(?=')/
+    },
+    {
+      :file  => File.expand_path('../fixtures/middlemac_app/Gemfile', __FILE__),
+      :regex => /(?<=gem 'middlemac', '~> ).*(?=')/
+    },
+    {
+      :file  => File.expand_path('../fixtures/middlemac_app/config.rb', __FILE__),
+      :regex => /(?<=:ProductVersion   => ')(.*)(?=')/
+    },
+  ].each do | item |
+    
+    content = File.read( item[:file] )
+    content.gsub!( item[:regex], version_new )
+    File.write( item[:file], content )
+    puts "#{File.basename( item[:file] )} changed to '#{version_new}'."
+  end
+
+  Middleman::Middlemac::VERSION.replace version_new
+end