middlemac 2.0.0 → 3.0.0

data/documentation_project/Contents/Resources/en.lproj/030_get_started/070_about_ruby.html.md.erb

@@ -0,0 +1,194 @@
+---
+title:  About Ruby and its Ecosystem
+blurb:  As the language that powers <em>Middlemac</em>, it’s worth taking a
+        short look at the Ruby language and its ecosystem.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= 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`.
+
+
+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.2 or higher,
+which itself requires other gems of specific versions. Bundler will ensure
+that when building a _Middlemac_ project, _only_ the correct gems and versions
+are used.
+
+When you see a command such as:
+
+~~~
+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:
+
+~~~
+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 with 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-targets', '~> 1.0.12'
+~~~
+
+This declaration tells Bundler that `middleman-targets` is a gem that is
+required for this project, and that any version greater than 1.0.12
+(inclusive) 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 modify this file yourself. 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.
+
+Whether or not you add `Gemfile.lock` to version control is up to you. Doing
+so mean that anyone that checks out your project will use the exact gem
+versions that you have committed; otherwise, consistent with the rules in the
+`Gemfile`, any checkouts will generate a `Gemfile.lock` and run using
+different versions of the gems. In theory, this should be perfectly fine, but
+API-breaking changes sometimes do happen with point updates.
+{: .tip .callout}
+
+### `bundle install`
+
+When you `cd` into a project directory, you can:
+
+~~~
+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-targets` 1.0.12 or above, and I’ve
+been building with it for weeks, and then update my gem to 1.0.14? In this
+case, as long as 1.0.12 is still installed on your system, Bundler will still
+use this version.
+
+You’ll either have to update the `Gemfile` with 1.0.14 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.
+
+~~~
+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] of this documentation.

data/documentation_project/Contents/Resources/en.lproj/030_get_started/aside_frontmatter.html.md.erb

@@ -0,0 +1,64 @@
+---
+title:  Front Matter
+blurb:  <em>Middleman</em> (and hence <em>Middlemac</em>) source files use
+        front matter to control many features of pages.
+layout: layout-apple-modern-aside
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+Front matter is a document header section in format called YAML 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 it was given a blurb
+(used as the opening paragraph and also the `meta description` `content` value
+for the page) via the `blurb:` key.
+
+If you examine the source for this page, you might notice that there is no
+`meta description` tag in the `head`; rest assured, it _is_ present in the
+HTML file, and used by the Apple Help Indexer.
+{: .note}
+
+Front matter can also control page order within a section, 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:  _Middleman_ (and hence _Middlemac_) source files use front matter to
+        control many features of pages.
+---
+~~~
+
+## 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.
+
+
+## JSON Frontmatter
+
+Recent versions of _Middleman_ support the use of JSON instead of YAML for
+frontmatter. The following example show how this page’s frontmatter may have
+been written instead:
+
+~~~ json
+;;;
+"title":  "Front Matter",
+"blurb":  "_Middleman_ (and hence _Middlemac_) source files use front matter to control many features of pages."
+;;;
+~~~
+
+JSON is indicated with delimiting `;;;` instead of hyphens.
+{: .note}

data/documentation_project/Contents/Resources/en.lproj/030_get_started/index.html.md.erb

@@ -0,0 +1,4 @@
+---
+title:  Get Started
+layout: layout-blank
+---

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/010_setup.html.md.erb

@@ -0,0 +1,204 @@
+---
+title:  Set Up your Help Project
+blurb:  Setting up your help project is the first step in <em>Middlemac</em>’s
+        workflow. Understand how configure your project and Xcode in this
+        article.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= 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 Help Book 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 a few different components, its key
+configuration is performed in a couple of 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 macOS knows which help bundle belongs
+    to which application. If they are not unique, macOS _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 `SharedGlobalAssets/convention/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`
+`:ProductURI`
+`:ProductCopyright`
+  : 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.
+{: .width25}
+
+
+
+CFBundleName and Targets
+------------------------
+
+The first thing we need to do is come up with a `CFBundleName` for our help
+projects, and decide what the targets are going to be. This will help us setup
+Xcode shortly.
+
+Xcode doesn’t know or care what the help bundle’s `CFBundleName` is, but
+_Middlemac_ uses it and the target to name the final, built help bundle, and
+Xcode _does_ have to know the name of those.
+
+All of your targets will share the same `CFBundleName`, so it should be
+descriptive of all of your targets and related to your product name. If the
+examples on this page, we’ll use `Middlemac`. This project also has the
+targets `pro` and `free`. What this means is _Middlemac_ will build help
+bundles named `Middlemac_(pro).help` and `Middlemac_(free).help`.
+
+If your `CFBundleName` contains any space characters, they will be replaced
+during build with underscores. This ensures that if you use `make` (e.g., such
+as from within Xcode) to build your Help Books, `make`’s broken handling of
+spaces won’t prevent a build.
+{: .note .callout}
+
+
+CFBundleID and Targets
+----------------------
+
+You will also have to have unique bundle identifiers for each of your Help
+Book targets, and you will have to have these available when you set up your
+`Info.plist` files in Xcode.
+
+As is standard with BundleID’s, reverse DNS notation is preferred. This
+documentation project uses `com.balthisar.middlemac.free.help` and
+`com.balthisar.middlemac.pro.help` for its two targets.
+
+Let’s use this information and start to set up Xcode.
+
+
+Xcode Configuration
+-------------------
+
+### Add Files 
+
+Let’s first tell your Xcode application targets that the help bundle files are
+available. In your Xcode project, create folders named `Middlemac_(pro).help`
+and `Middlemac_(free).help`. They typically go into your project’s
+`Resources/` folder. Mac OS will automatically display them as bundles. For
+now, these are just proxies for the bundles we’ll build later.
+
+Help Books are bundles with their own localizations inside of them. Don’t put
+Help Books in your application’s localized folders such as `Base.lproj/` or
+`en.lproj/`. Putting them into `Resources/` is the right thing to do.
+{: .tip .callout}
+
+Next you can add these files to Xcode the usual way (“Add files…”). **Make
+sure you add these by creating folder references. This is critical.** If you
+are able to browse the folder contents in Xcode, then they were not properly
+added and will not properly copy into the final application bundle.
+
+Assuming you have a Pro and Free target in Xcode, you can use the file
+inspector to make sure the Pro `.help` and the Free `.help` have the
+appropriate, obvious target memberships.
+
+### Configure your applications’ `Info.plist` files
+
+If you have multiple Xcode targets, you may be using a different `Info.plist`
+file for each target. If not, then you’ll have to start because they contain
+information unique to each Help Book.
+
+Alternatively you can setup an `Info.plist` pre-processor (this is my
+preferred approach) that generates an `Info.plist` for each target when you
+build. _That’s_ beyond the scope of this document, though. You can begin by
+looking at your Xcode targets’ **Build Settings -> Packaging**. 
+{: .tip .callout}
+
+In each of your `Info.plist` files, find or create the following keys:
+
+`Help Book directory name` (`CFBundleHelpBookFolder`)
+
+ : Ensure you use the appropriate `Middlemac_(pro).help` or
+   `Middlemac_(free).help`, depending on which target’s `.plist` this is.
+
+`Help Book identifier` (`CFBundleHelpBookName`)
+
+ : This must match the unique `CFBundleID` that you set for each of your
+   help targets in the help project’s `config.rb` file. If you’ve not setup
+   the `config.rb` yet, now is a good time to decide on the keys that you will
+   use. 
+   
+   This sample project uses `com.balthisar.middlemac.free.help` and
+   `com.balthisar.middlemac.pro.help`.
+{: .nontabular}
+
+
+Setup `config.rb` and especially `options.help_output_location`
+-------------------------------------------------------------------
+
+Next make sure you setup `config.rb` with matching values from above.
+
+We setup empty proxy `.help` bundles for Xcode above. Make sure that you set
+your `config.rb`’s `options.help_output_location` to the directory that you
+created the proxy files. Then, any time you build your help projects with
+_Middlemac_, they will be ready to go in Xcode automatically, the next time
+you build your Xcode project.
+
+
+_Middlemac_ takes care of everything else
+-----------------------------------------
+
+Once your `config.rb` is setup, _Middlemac_ takes care of setting all of the
+required keys and data in all of the help bundle `.plist`, `.strings`, and
+main `index.html` file, managing them for each target.
+
+

data/documentation_project/Contents/Resources/{Base.lproj/030_skills_refresher/60_filetypes_skill.html.md.erb → en.lproj/040_compose_project/020_filetypes.html.md.erb}

@@ -3,17 +3,13 @@ title:  File Types
 blurb:  <em>Middleman</em> uses several filetypes to get its job done. An
         understanding of their differences is important to your successful use
         of <em>Middlemac</em>.
-layout: template-logo-medium
 ---
 <%= md_links %>
 <%= md_images %>
 
-<%= current_page.data.title %>
-==============================
-
 <%= current_page.data.blurb %>
 
-Although you can use static `.html` files to build your help book, you would be
+Although you can use static `.html` files to build your Help Book, you would be
 sacrificing a lot of _Middleman_’s utility to do so, because static html is
 simply copied to your build directory as-is, with no opportunity to take
 advantages of the infrastructure that _Middleman_ and _Middlemac_ offer you.
@@ -43,11 +39,11 @@ extensions and will process them accordingly.
  
 `.haml`
 
-  : The “HTML abstraction markup language” excels at enforcing structure in your
-    HTML-target documents, and is clutter-free and easy to read. It supports
-    many built-in filters for including content in Ruby, Markdown, raw source
-    code, and more. _Middlemac_’s templates, layouts, and partials are written
-    in HAML.
+  : The “HTML abstraction markup language” excels at enforcing structure in 
+    your HTML-target documents, and is clutter-free and easy to read. It 
+    supports many built-in filters for including content in Ruby, Markdown, 
+    raw source code, and more. _Middlemac_’s layouts are written in HAML, but
+    you probably won’t use it for your own HTML documents.
     
     You can learn more about HAML on [its website](http://haml.info/).
 
@@ -68,7 +64,7 @@ extensions and will process them accordingly.
     and SCSS is the file format.
     
     You can learn more about SASS on [its website](http://sass-lang.com/).
-
+{: .width25}
 
 Files with a leading underscore
 -------------------------------