middlemac 2.0.0 → 3.1.2

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

@@ -0,0 +1,97 @@
+---
+title:  Serve Your Help Book
+blurb:  Learn how to interact with your Help Book in a live environment using
+        <em>Middleman</em>’s development server.
+---
+<%= md_links %>
+<%= md_images %>
+
+When developing the majority of your Help Book content, it’s likely that you
+will want to view the results in a web browser from time to time, which is
+much faster than building the Help Book, clearing Apple Help Builder’s cache,
+building your application, then running it.
+
+While it’s possible to build your Help Book, and open the individual pages in
+your browser, this isn’t practical for a modern Help Book, which depends on
+AJAX and rewriting paths and other things that a file system doesn’t support,
+despite being static pages.
+
+Instead, you can use _Middleman_’s built-in preview server to host your Help
+Books. It’s a zero-configuration that, quite simply, just works.
+
+Let’s have a look at **Your First Help Book** that you worked on in the
+previous topic. From within that project directory in **Terminal**, simply:
+
+~~~ bash
+bundle exec middleman serve --target pro
+~~~
+
+In just a few seconds, you will see a message indicating that the server is
+running, as well as the address for your site, which is generally something
+like:
+
+~~~ bash
+== View your site at "http://localhost:4567", "http://127.0.0.1:4567"
+== Inspect your site configuration at "http://localhost:4567/__middleman", "http://127.0.0.1:4567/__middleman"
+~~~
+
+If you follow this advice, though, you’re like to see this message in your
+browser:
+
+> ###File Not Found
+
+Remember, this is a macOS bundle, so the content we want is really located at
+`http://localhost:4567/Resources/`. Go ahead and type that into your browser,
+and browse the working Help Book, paying particular attention to whatever
+changes you made in the previous lesson.
+
+When ready, try navigating to this file by copying and inserting into the
+browser address bar.
+
+`/Resources/en.lproj/hello_world_file.html`
+
+You should notice the the browser automatically redirected you to:
+
+`http://localhost:4567/Resources/index.html?localePath=en.lproj#/topic-en.lproj-hello_world_file`
+
+
+## What’s going on here?
+
+Modern Apple Help Books function completely from the `/Resources/index.html`
+file. Every other page in the Help Book is loaded via AJAX by this file, and
+then applied to the current browser window after rewriting paths so that they
+are relative to this `index.html`. Apple’s JavaScript and styles are then
+applied, and then you have a modern Apple Help Book.
+
+Because the help indexer tool, `hiutil`, indexes individual pages, a
+search result would lead to that indexed page, and that indexed page has none
+of Apple’s JavaScripts or styling. So, each page of your Help Book, when
+built, also includes a redirect to the main `index.html`, ensuring that search
+works flawlessly.
+
+During development, troubleshooting sometimes indicates the necessity
+of viewing the HTML file in the browser without this redirect. If you’d like
+to prevent this redirect from happening so quickly during development, have a
+look at the `options.show_debug` option in your `config.rb`.
+
+
+## Specifying Targets
+
+As you may have guessed from earlier, by starting the server with:
+
+~~~ bash
+bundle exec middleman serve --target pro
+~~~
+
+…you’ve started the `pro` target. Because **Your First Help Book** was also 
+configured with a `free` target, you can start it, instead, with:
+
+~~~ bash
+bundle exec middleman serve --target pro
+~~~
+
+You can also start the server with a simple `bundle exec middleman`. The
+action `serve` is _Middleman_’s default, and omitting the `--target` option
+will have _Middlemac_ use the `config[:target]` setting (the default target)
+from your `config.rb`.
+{: .tip .callout}

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

@@ -0,0 +1,56 @@
+---
+title:  Build Your Help Book
+blurb:  This article shows you how simple it is to build your Help Book, so
+        that it may be included with your Xcode project.
+---
+<%= md_links %>
+<%= md_images %>
+
+When you’re finally ready to build your Help Book, either for including in 
+your application or for hosting on a website, you can do so easily with
+_Middleman_. Let’s build **Your First Help Book** now. In **Terminal** from
+within the project directory:
+
+~~~ bash
+bundle exec middleman build_all
+~~~
+
+Within just a few seconds (depending on the speed of your computer), you
+should find that _Middleman_/_Middlemac_ will have built two, new help 
+bundles: `New_Project_(free).help` and `New_Project_(pro).help`.
+
+_Middlemac_ ensures that no spaces are in help bundle filenames, just in case
+you want to use `make` to build them. The default macOS `make` is
+**GNU Make**, and it simply doesn’t work with paths containing spaces.
+{: .note .callout}
+
+You can `cd` into these bundles in **Terminal**, or use **Show Package 
+Contents** in **Finder** to browse the folders and contents there.
+
+What you should find is a complete, modern Apple Help Book consisting of
+HTML files that you built, as well as all of the supporting `.plist`, `.json`,
+and other files needed to operate the Help Book.
+
+
+## Targets
+
+As with the server, you can specify that _Middlemac_ build a single target,
+rather than all of them. This is accomplished by using the `build` action
+and specifying the `--target` option when invoking _Middleman_:
+
+~~~ bash
+bundle exec middleman build --target pro
+bundle exec middleman build --target free
+bundle exec middleman build
+~~~
+
+That last example builds the default target as defined in your `config.rb`
+file.
+{: .tip .callout}
+
+
+## Add Your First Help Book to your application
+
+If you’re ready to add **Your First Help Book** to your application, then
+skip ahead to [Set Up your Help Project][setup] for information on getting
+your application to recognize your Help Book.

data/documentation_project/Contents/Resources/{Base.lproj/030_skills_refresher/10_markdown_skill.html.md.erb → en.lproj/030_get_started/050_about_markdown.html.md.erb}

@@ -1,27 +1,24 @@
 ---
-title:  Markdown
-blurb:  Although you can hand-write all of your documents in HTML, why not take
-        advantage of the clarity and ease of use offered by Markdown?
-layout: template-logo-medium
+title:  About Markdown
+blurb:  Although you can hand-write all of your documents in HTML, why not
+        take advantage of the clarity and ease of use offered by Markdown?
 ---
 <%= md_links %>
 <%= md_images %>
 
-<%= current_page.data.title %>
-==============================
-
 <%= current_page.data.blurb %>
 
-_Middlemac_ takes care of a lot of the details for generating Apple Help Books,
-and that may be reason enough to use _Middlemac_. However if you decide _not_ to
-use Markdown, then you’re throwing away the single, largest contributor to your
-help file building productivity that there is.
+_Middlemac_ takes care of a lot of the details for generating Apple Help
+Books, and that may be reason enough to use _Middlemac_. However if you decide
+_not_ to use Markdown, then you’re throwing away the single, largest
+contributor to your help file building productivity that there is.
 
 
 What is Markdown?
 -----------------
 
-In the words of the estimable John Gruber (the author of the original Markdown):
+In the words of the estimable John Gruber (the author of the original
+Markdown):
 
 > Markdown is a text-to-HTML conversion tool for web writers. Markdown allows
 > you to write using an easy-to-read, easy-to-write plain text format, then 
@@ -35,7 +32,8 @@ the page was written so:
 What is Markdown?
 -----------------
 
-In the words of the estimable John Gruber (the author of the original Markdown):
+In the words of the estimable John Gruber (the author of the original
+Markdown):
 
 > Markdown is a text-to-HTML conversion tool for web writers. Markdown allows
 > you to write using an easy-to-read, easy-to-write plain text format, then 
@@ -59,5 +57,5 @@ are all fairly well compatible.
 
 _Middlemac_ uses [_Kramdown_](http://kramdown.gettalong.org/) as its Markdown
 engine because that’s what _Middleman_ uses by default. You can read about all
-its features an syntax on its 
+its features and syntax on its 
 [documentation page](http://kramdown.gettalong.org/documentation.html).

data/documentation_project/Contents/Resources/{Base.lproj/030_skills_refresher/30_middleman_skill.html.md.erb → en.lproj/030_get_started/060_about_middleman.html.md.erb}

@@ -1,15 +1,11 @@
 ---
-title:  Middleman
-blurb:  <em>Middleman</em> is the engine that makes <em>Middlemac</em> possible.
-        It’s critical to know a little bit about this tool.
-layout: template-logo-medium
+title:  About Middleman
+blurb:  <em>Middleman</em> is the engine that makes <em>Middlemac</em>
+        possible. It’s critical to know a little bit about this tool.
 ---
 <%= md_links %>
 <%= md_images %>
 
-<%= current_page.data.title %>
-==============================
-
 <%= current_page.data.blurb %>
 
 _Middleman_ is a [static site generator using all the shortcuts and tools in
@@ -26,7 +22,7 @@ development toolchain.
 Builder _and_ server
 --------------------
 _Middleman_ doesn’t merely build final output; it includes a non-configuration
-server that makes it much easier to develop your website or help book. Features
+server that makes it much easier to develop your website or Help Book. Features
 such as live reload mean that when you change your source file, the site in
 your web browser will update automatically.
 
@@ -40,13 +36,13 @@ Basic concepts
 _Middleman_’s basic concepts are these:
 
 - Organize your site in a source directory that mirrors the desired structure
-  on the server (or in our case, in our help book).
+  on the server (or in our case, in our Help Book).
 - Add file extensions to the source files to indicate the type of pre-processing
   that you want to perform on each of them.
 - Provide the ability to include partials and use helpers to improve your
   content development productivity, while keeping yourself DRY.
 - Provide the ability to use templates and layouts to bring uniformity to your
-  website (in our case, to your help book).
+  website (in our case, to your Help Book).
 - Act as a server in developer mode, building content dynamically as you develop
   it.
 - Build final output, ready to use wherever you need it.
@@ -60,25 +56,25 @@ will actually execute `middleman` to serve or to build your projects.
 
 To start the built-in server in order to preview your work, simply do:
 
-~~~ bash
+~~~
 bundle exec middleman serve --target free
 ~~~
 
 Instructions for accessing the server (the address and port) will be reported to
 you.
 
-Note, too, that `--target` specifies an option; the example about would serve
+Note, too, that `--target` specifies an option; the example above would serve
 the `free` target.
 
 To build the `pro` target, you would do this:
 
-~~~ bash
+~~~
 bundle exec middleman build --target pro
 ~~~
 
 And if you wanted to build every target at once, simply this:
 
-~~~ bash
+~~~
 bundle exec middleman build_all
 ~~~
 

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.