middlemac 2.0.0 → 3.0.0

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.
-
-
-

data/documentation_project/Contents/Resources/Base.lproj/050_structure/010_directories_and_images.html.md.erb

@@ -1,176 +0,0 @@
----
-title:  Directories, filenames, images, and paths
-blurb:  Learn about proper structure for your directory hierarchy, filenames,
-        and image locations, and discover some best practices related to paths.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-Directory conventions
----------------------
-
-You will have noticed by now that your content root appears to be two levels
-below the actual project root. This is a result of the Apple Help directory
-structure. Remember, _Middleman_ depends on building an output project that
-mirrors the input project. In order for links, images, and other content to
-be accessed properly, _Middlemac_ uses Apple’s convention.
-
-Fortunately once inside the `Base.lproj` directory, we -- as help book 
-developers -- are free to organize files as we see fit, despite the examples
-you may have seen in Apple’s documentation. _Middlemac_, though, has setup a
-hierarchy that “just works,” and the explanation follows. Starting at the top,
-let’s look at a _Middleman_ project layout. Also don’t forget to have a look
-later at [Apple Help setup][apple_help_setup].
-
-Note the many of the file names below are written with destination, _built_
-file extensions, and not the complete extension as it might appear in the source
-directory. For example, the top level source file for `index.html` could have
-the name `index.html.md.erb` or `index.html.haml`, as you see fit.
-{:.note}
-
-`Contents/`
-
- : Contains everything in your help project that will be compiled into or
-   contribute to the final `.help` project.
-   
-`Contents/Info.plist`
-
- : The `Info.plist` file is the file that _Middlemac_ will process into the
-   final `Info.plist` that your Mac OS X application needs in order to work with
-   your help book. For a basic project you shouldn’t have to modify anything in
-   this file, but if you want or need to have other key-value pairs in the final
-   `Info.plist`, then add them here. 
-   
-`Contents/Resources/shared`
-
- : This directory contains assets that are common between all of your different
-   help language projects. Although _Middlemac_ is not a multilingual solution
-   _per se_, this is maintained because you can simply have a different
-   _Middlemac_ project per language, and then merge in the other language
-   `.lproj` directories into your final help book, sharing assets in this
-   directory.
-   
-`Contents/Resources/Base.lproj`
-
- : This directory serves as your base [group][groups] and contains all of your
-   help book’s content as well as pieces that will contribute to your content
-   (such as templates).
-   
-   Any other files that result in `.html` in this directory level, except for
-   `index.html` constitute part of the `Base.lproj` group. At this level you
-   should start adding directories to contain your other groups.
-   
-`Contents/Resources/Base.lproj/index.html`
-
- : This is the top level file in your entire project, and is also the Apple
-   Help System main landing page.
- 
-`Contents/Resources/Base.lproj/InfoPlist.strings`
-
- : The `InfoPlist.strings` file is the file that _Middlemac_ will process into
-   the final `InfoPlist.strings`, which contains the localized version of your
-   applications’ human-readable `Info.plist` data (specifically, `CFBundleName`
-   and `HPDBookTitle`).
-   
-   _Middlemac_ is a multi-target solution for a single language, and not a
-   multi-language solution _per se_, and so the `CFBundleName` in your
-   `config.rb` will be used, whether it’s English or German or Chinese. This is
-   one of the strengths of `Base.lproj`: it’s agnostic.
-
-`Contents/Resources/Base.lproj/assets/`
-
- : This directory contains all of the non-content assets used in your help book
-   such as stylesheets, images, etc., as well as data source files, templates,
-   layouts and partials.
-   
-   You will notice that some of these classes of items are in unconventional
-   locations compared to a default _Middleman_ project. This was done on your
-   behalf for the sake of portability and for having a non-distracting directory
-   environment.
-   
-   `_data/`
-    : This directory contains data files that you can use to supply data for
-      [using local data][using_local_data]. This directory will not be
-      output in the final build.
-    
-   `_layouts/`
-    : All layouts and templates should go here. This directory will not be
-      output in the final build.
-      
-   `images/`
-    : All images should go here. _Middleman_ will find them automatically if
-      you use the helpers.
- 
-   `javascripts/`
-    : Javascripts, if any, should go here. You should prefix each script with
-      an underscore so that they will _not_ be included. The already-present
-      file `all.js` will bundle them into a single file -- `all.js` -- and
-      _that’s_ the file loaded by the _Middlemac_ layouts.
-
-   `partials/`
-    : Partials can go here, and should be prefaced with an underscore so that
-      they will not generate build output. Partial files can also be included
-      in any other directory, too. This is for organizational convenience of
-      common partials that may be used anywhere.
-
-   `stylesheets/`
-    : Your `.css` and `.scss` files should go here. Read more about _Middlemac_
-      CSS organization [here][css].
-
- 
-Images
-------
-
-Most images, of course, should go into the `images` directory of the `assets`
-directory.
-
-However _Middlemac_ also depends on some magic images being placed in
-`Contents/Resources/shared/`:
-
-`icon_32x32.png` and `icon_32x32@2x.png`
-
- : These files are your help file icon at 32 × 32 pixels and @2x, and will be
-   used by the included templates automatically. More importantly, however, your
-   main landing page is linked to this icon so that Apple Help Viewer knows what
-   the help icon is.
-
-`icon_256x256.png` and `icon_256x256@2x.png`
-
- : The same as above, but at 256 × 256 pixels and @2x.
- 
-You will also notice that there are target-specific versions of these images
-located here, too. This documentation project takes advantage of them, and you
-can do the same. Note that the non-target specific versions are still required
-so that the Help Viewer knows to find them!
-
-
-Images Organization
--------------------
-
-When your content images are located in the `assets/images/` directory,
-_Middleman_’s [helpers][middleman_helpers] can find them automatically
-without any worry about relative or absolute file paths.
-
-
-“Absolute” Paths
-----------------
-
-When using _Middleman_’s [helpers][middleman_helpers], absolute paths will be
-converted to relative paths during the build. Absolute paths are relative to the
-`Contents` directory and _not_ the filesystem root.
-
-In general it’s _not_ recommended to use absolute paths unless you need assets
-outside of _Middlemac_’s configuration. _Middleman_ will automatically build the
-correct path using only the asset name when you use its helpers, if the assets
-are in the correct directories (e.g., images in `images/`).
-
-However you will use absolute paths to refer to items in the `shared/` directory
-since this it outside of _Middlemac_’s normal search scope. The view templates
-use this approach, for example.