middlemac 2.0.0 → 3.1.2

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

@@ -1,126 +0,0 @@
----
-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/030_skills_refresher/20_frontmatter_skill.html.md.erb

@@ -1,54 +0,0 @@
----
-title:  Front Matter
-blurb:  <em>Middleman</em> (and hence <em>Middlemac</em>) source files use
-        front matter to control many features of pages.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-Front matter is a document header section that contains key-value data that
-applies to a page. This data can be referred to later for output or control.
-For example, the title of this page was specified with a `title:` key in the
-source document’s front matter, and its layout was specified with a `layout:`
-key.
-
-Front matter can also control page order (a feature of _Middleman_’s
-`middleman-pagegroups` gem), inclusion of pages for targets/features (provided
-by the `middleman-targets` gem), and more.
-
-Here’s this document’s front matter:
-
-~~~ yaml
----
-title:  Front Matter
-blurb:  <em>Middleman</em> (and hence <em>Middlemac</em>) source files use
-        front matter to control a lot of features of pages.
-layout: template-logo-medium
----
-~~~
-
-## Declaring Front Matter
-
-Front matter is defined as being delimited at the beginning and end with a line
-consisting of a series of three hyphens (`-`), and this block must appear at the
-top of a document.
-
-Although specific front matter keys are discussed elsewhere in this
-documentation it’s worth pointing out that the `title:` and `:blurb` are used
-extensively in _Middlemac_. For example all of the automatic navigation
-features are built using this data, meaning that this data need only appear
-once, here, in this very document.
-
-## Markdown in Front Matter
-
-You may have noticed that the front matter contains HTML. Because the front
-matter consists of data rather than content specifically targeted for display,
-it is not processed by the Markdown engine. Front matter is one of the very
-few places in a _Middlemac_ project where you have to revert to using HTML.
-

data/documentation_project/Contents/Resources/Base.lproj/030_skills_refresher/40_ruby_skill.html.md.erb

@@ -1,67 +0,0 @@
----
-title:  Ruby
-blurb:  As the language that powers <em>Middlemac</em>, it’s worth taking a
-        short look at the Ruby language.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-[Ruby](https://www.ruby-lang.org/en/) is the language that _Middlemac_,
-_Middleman_, and many of the others tools are written with. You do not have to
-learn Ruby to take advantage of _Middlemac_, although some ability to work with
-it will be invaluable to you.
-
-Ruby may surprise you
----------------------
-
-If you’re a software developer, then it’s highly likely that you will be able to
-read most Ruby code immediately. Coming from an Objective-C or Swift background,
-these are a few things that may surprise you.
-
-### Symbols
-Ruby has a type of identifier called a `symbol`. They are used quite extensively
-and look like `:this_symbol`. As identifiers and not variables, you can’t assign
-values to them. Their value is themselves, though they have useful string
-representations (`:this_symbol.to_s`). You can even get the symbol
-representation of `'this_string'.to_sym`. Because they're unique, they make
-excellent array/hash keys and excellent, guaranteed unique values.
-
-### Everything is an object
-Everything is an object, including what are fundamental datatypes in other
-languages. Need to convert the integer `i` to a float? It’s as easy as
-`i.to_f`.
-              
-### Everything has a return value
-In Ruby you don’t require `return value`, or `result := value`, or
-`function_name = value`. Just `value`, alone, will return its value. Even `if`
-statements return values:
-
-~~~ ruby
-result = if answer == 'yes'
-            "The answer as affirmative."
-         else
-            "The answer was something else."
-         end
-~~~
-
-This example assigns the appropriate string to the variable `result`.
-
-
-Just enough Ruby
-----------------
-To work effectively with _Middlemac_ you’ll only have to learn enough Ruby to
-do a few simple things:
-
-- Set variables in the `config.rb` file.
-- Use a few helper functions from within files, e.g., `partial 'my_file'`.
-- Use conditionals, if you want them. You know: simply `if/else/end`, or even
-  `unless/else/end`.
-
-Examples of these last two points can be seen when we take a look at
-[File Types][filetypes_skill].

data/documentation_project/Contents/Resources/Base.lproj/030_skills_refresher/50_ruby_ecosystem.html.md.erb

@@ -1,136 +0,0 @@
----
-title:  Ruby’s Ecosystem
-blurb:  Ruby has a huge ecosystem the can be confusing to new users. This
-        article makes a very brief introduction that should shorten the learning
-        curve.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-Gems
-----
-
-“Gems” are packages of Ruby or compiled code in a standard format that serve as
-extensions or library additions to Ruby. _Middlemac_ is a system consisting of
-the `middlemac` gem, among others.
-
-By default Ruby is configured to fetch gems from
-[rubygems.org](https://rubygems.org/), which is convenient as long as you are
-connected to the internet.
-
-Gems, as software, have versions and can have dependencies on other gems. This
-can lead to dependency hell when multiple versions of multiple gems are
-installed having a clash due to mixed dependencies. Luckily this has been mostly
-solved via the use of Bundler.
-
-Bundler
--------
-
-Bundler is a gem version management system that ensures that the correct gem
-version is used on a per-project basis, as specified in the `Gemfile` and locked
-in `Gemfile.lock` (more on these below).
-
-Using bundler will ensure that gem versions of known compatibility will be used.
-For example, _Middlemac_ requires _Middleman_ version 4.1.7 or higher, which
-itself requires other gems of specific versions. Bundler will ensure that when
-building a _Middlemac_ project, _only_ the correct gems are used.
-
-When you see a command such as:
-
-~~~ bash
-bundle exec middleman build
-~~~
-
-…it means that Bundler will execute the `middleman` gem, and will take
-responsibility for ensuring the correct gem versions are used. If we want to
-leave it up to chance, we might try this:
-
-~~~ bash
-middleman build
-~~~
-
-…and this might work, or it might not. Without using Bundler, the default
-versions of gems installed on your system will be used, and they might not be
-compatible the default version of `middleman`.
-
-Ruby projects, including _Middlemac_ help book projects, specify gem versions
-using a file in the project directory called `Gemfile`.
-
-
-`Gemfile` and `Gemfile.lock`
-----------------------------
-
-Your _Middlemac_ project contains this file to specify to Bundler which versions
-of Ruby gems should be used. In general you don't have to bother with this file
-at all. However if you become more advanced and want to use other gems, you’ll
-have to dive into this file eventually.
-
-This file contains gems and the versions that are allowed. For example,
-this documentation project’s `Gemfile` contains something similar to this:
-
-~~~ ruby
-gem 'middleman-pagegroups', '~> 1.0.3'
-~~~
-
-This declaration tells Bundler that `middleman-pagegroups` is a gem that is
-required for this project, and that any version greater than 1.0.3 is allowed,
-but only in the `1.0.x` series. The `~>` is called a “pessimistic operator” and
-is used if we don’t trust the `1.1.x` will break nothing.
-
-Other operators are available, too, of course, and are a simple web search away.
-
-The file `Gemfile.lock` is generated automatically by Bundler, and you should
-never, ever modify this file yourself (you should also exclude it from version
-control). This file is the file that indicates to Bundler the _exact_ versions
-of Gems that will be used. It ensures that the set of gems always stays
-consistent (even if you update gems) unless you deliberately want it to do
-otherwise.
-
-### `bundle install`
-
-When you `cd` into a project directory, you can:
-
-~~~ bash
-bundle install
-~~~
-
-This tells Bundler to check the `Gemfile` and install any gems that are required
-but are missing, typically from [rubygems.org](https://rubygems.org/). After
-installing the gems Bundler will also update the `Gemfile.lock`, thereby
-freezing the versions to be used in your project.
-
-What happens if I install a newer version of a Ruby gem? For example, if the
-`Gemfile` is configured to use `middleman-pagegroups` 1.0.3 or above, and I’ve
-been building with it for weeks, and then update my gem to 1.0.4? In this case,
-as long as 1.0.3 is still installed on your system, Bundler will still use this
-version.
-
-You’ll either have to update the `Gemfile` with 1.0.4 and then `bundle install`
-again, or…
-
-### `bundle update`
-
-This tells Bundler to install newer versions of all of your Gems, if available,
-and within the pessimistic version checks in the `Gemfile`, and also updates
-`Gemfile.lock` so that newer versions of the gems will be used.
-
-~~~ bash
-bundle update
-~~~
-
-
-`config.rb`
------------
-
-Nearly every Ruby project, including your _Middlemac_ help book project, follows
-the convention of configuration via a `config.rb` file in the root level of your
-project directory. 
-
-Information specific to _Middlemac_’s `config.rb` is available in the
-[appropriate section][setup-index] of this documentation.

data/documentation_project/Contents/Resources/Base.lproj/030_skills_refresher/index.html.md.erb

@@ -1,35 +0,0 @@
----
-title:  Skills Refresher
-blurb:  If you don’t know a thing about Ruby or <em>Middleman</em>, don’t
-        worry; there’s enough information in this section to get you started.
-layout: template-logo-large
-navigate: true
----
-<%= md_links %>
-<%= md_images %>
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-_Middlemac_ uses tools you may already know. Or not.
-
-- [Markdown](http://kramdown.gettalong.org/) is the text-based, human-readable,
-  easy to use format that will make writing your documentation a real pleasure.
-  This file is written using Markdown.
-- [_Middleman_](http://middlemanapp.com) is a static HTML site generator, and is
-  the heart of _Middlemac_’s abilities, as well as an inspiration for the name.
-- [Ruby](https://www.ruby-lang.org/en/) is the language that _Middlemac_,
-  _Middleman_, and many of the others tools are written with. You do not have
-  to learn Ruby to take advantage of _Middlemac_, although some ability to work
-  with it will be invaluable to you.
-- HTML is the markup language that Apple requires for help books. But
-  _Middlemac_ promises to make things easy for you, and so…
-
-
-* * *
-
-<%= nav_legitimate_children %>
-
-* * *

data/documentation_project/Contents/Resources/Base.lproj/040_setup/index.html.md.erb

@@ -1,88 +0,0 @@
----
-title:  "Workflow: Set up your Help Project"
-blurb:  Setting up your help project is the first step in <em>Middlemac</em>’s
-        workflow. Understand how to do this setup in this article.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-The file `config.rb` has settings which both affect how _Middleman_ operates as
-well as how _Middlemac_ builds your help books. **If you follow the _Middlemac_
-conventions, there should be no reason to change the _Middleman_ settings.**
-
-When you open `config.rb` in your text editor, at the top you will readily
-identify the start of the _Middlemac_ configuration section, which is delimited
-by this block at the beginning:
-
-~~~ ruby
-################################################################################
-#  config.rb
-#    Configure Middleman to generate Apple HelpBook containers for multiple
-#    targets.
-################################################################################
-~~~
-
-And terminated by this block at the end:
-
-~~~ ruby
-################################################################
-# STOP! There's nothing below here that you should have to
-# change. Just follow the conventions and framework provided.
-################################################################
-~~~
-
-## Sections
-
-Because _Middlemac_ is made from several components, its key configuration
-is performed in several different blocks. The file is also very well commented,
-and the [API Reference][config_ref] contains specific documentation for each
-setting.
-
-However the `targets` hash bears explaining.
-    
-## The `targets` hash explained
-  
-At first the `targets` option looks complicated in that it consists of nested
-hashes, but the format is quite simple to get used to. Each root level item
-in `targets` consists of the following items, which are unique for each target.
-      
-`:CFBundleID`
-  : Each help target must have a unique `CFBundleID` that matches a unique
-    `CFBundleHelpBookName` in your applications’ `Info.plist` files. This
-    pairing is the mechanism by which Mac OS X knows which help bundle belongs
-    to which application. If they are not unique, Mac OS X _will_ become
-    confused, and your end-users, if they have multiple versions of your product
-    installed, will not be very satisfied.
-    
-`:HPDBookIconPath`
-  : If specified a target-specific icon will be used as the help book icon by
-    Apple’s help viewer. This path must be relative to the location of the
-    `Info.plist` file per Apple’s specification. If `nil` (or not present) then
-    the default `shared/icon_32x32@2x.png` will be used.
-
-`:CFBundleName`
-  : This value will be used for correct `.plists` and `.strings` setup, and will
-    determine final `.help` directory name. All targets should use the same
-    `:CFBundleName`. Built targets will be named `CFBundleName (target).help`.
-    This is *not* intended to be a product name, which is defined below.
-    
-`:ProductName`, `ProductVersion`, and `ProductURI`
-  : The default templates use these in a prominent way, and they’re also
-    available to you using _Middlemac_’s helpers.
- 
-`:Features`
-  : Aside from **targets** the use of **features** can give you fine-grained
-    control over what content appears in each target. It’s considered a 
-    best-practice to include all of the same features in the hash for each
-    target, and specify a boolean (true/false) value for each key, as
-    appropriate for your target. _Middlemac_ documentation has four features
-    defined.
-
-
-