middlemac 2.0.0 → 3.0.0

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

@@ -0,0 +1,114 @@
+---
+title:  What is Middlemac?
+blurb:  Discover what <em>Middlemac</em> can do for you, why it exists, and 
+        what it’s made out of.
+keywords:
+ - use case
+ - about
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+## Why _Middlemac_ exists
+
+_Middlemac_ exists to solve these three problems:
+
+- **How do I build help files for my macOS applications?** Although 
+  ostensibly a simple set of HTML files, a macOS Help Book requires careful
+  application of data in order for the Help Book to interface properly with
+  your application.
+
+- **How do I manage help files for multiple versions of my macOS
+  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.
+  
+- **How do I make my help files look and work like Apple’s help files?** Since
+  macOS 10.10 (“Yosemite”), Apple has begun using a new look and feel in its
+  macOS and application help files, with tables of contents and enhanced
+  features not previously used. _Middlemac_ doesn’t just simulate those
+  features; it _uses_ those features already present and available on macOS.
+
+
+## What does _Middlemac_ do?
+
+_Middlemac_ builds modern Apple Help Books for your application, and manages all
+of the esoteric details for you. _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
+macOS application, for every language that you support, 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.
+
+_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, for example:
+  
+  ~~~ 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.
+  ~~~
+
+- Single or multiple build [targets][targets_and_features], 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][targets_and_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, especially if you’re already a developer.
+
+- A set of conventions and tools that generate authentic Apple Help Books in
+  exactly the same manner that Apple does, including styles, look-and-feel,
+  and navigation.
+  
+- [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.
+  
+- Support for building Help Books in multiple languages, in the same project.
+
+## 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.
+
+`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.
+{: .nontabular }

data/documentation_project/Contents/Resources/en.lproj/020_apple_help_features/index.html.md.erb

@@ -0,0 +1,241 @@
+---
+title:  Apple Help Book Features
+blurb:  View examples of the features provided by modern Apple Help Books.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+Universal Deployment
+--------------------
+
+Modern Apple Help Books are designed to look and work great in Apple Help
+Viewer, but also look great when served to a browser on the desktop or mobile,
+such as Apple does with their documentation.
+
+![Universal Deployment Screenshot][apple_help_features_universal]
+
+The Help Book, when used in Apple Help Viewer or served to a browser has all
+of the same features that you’d expect in the Help Viewer:
+
+- The Help Book title is displayed as the window title in Help Viewer, and
+  as a top banner in a browser.
+- The Apple Help Viewer window title bar is ready to execute a search, and
+  when in a browser, search function is available with the button in the
+  page banner.
+  
+  A key difference _does_ exist when searching in Apple Help Viewer versus
+  the web browser. Help Viewer uses a binary search index file generated by
+  the `hiutil` command, and the JavaScript that runs the browser version uses
+  a file in JSON format representing a prefix tree (or trie). _Middlemac_
+  covers you in both of these cases, however!
+  {: .note .callout}
+- The Table of Contents button is enabled in Apple Help Viewer, and a Table
+  of Contents button is added to the page banner in the browser. In both
+  cases, a navigation menu is revealed with support for flat or nested Help
+  Book structures.
+  
+All in all, serving a modern Help Book to a web browser delivers all of the
+experience of a Help Book in Apple Help Viewer.
+
+
+Asides
+------
+
+“Asides” are loaded via AJAX from another file into a popup element on the 
+current page, and provide a description, example, or some other contextual
+information without having to load a new page.
+
+![Example Aside Screenshot][apple_help_features_aside_example]
+
+Would you like to access an example of
+<%= link_to "an aside", "aside_description.html", :aside => true %>?
+Activate the specially decorated link to see one in action.
+
+
+Copyright Information
+---------------------
+
+You can provide a copyright message via your [`config.rb`][config_ref] file,
+which Apple’s help system will use to display in certain circumstances:
+
+- When viewed served to your browser, each page of your project will include
+  your copyright statement.
+  ![Copyright Footer Example][apple_help_features_copyright_footer]
+- When printed from Apple Help Viewer, this statement will be used as a footer
+  for each printed page.
+- This message will be displayed on your Help Book’s [landing page][en.lproj]
+  when served to a browser, and, if you also have a topic page with a
+  [frontmatter][frontmatter] `categories` entry containing `copyright`, then
+  this copyright message on the landing page will be displayed as a link to
+  this specified page.
+  ![Landing Page Links][apple_help_features_landing_links]
+
+
+Navigation
+----------
+
+Apple provides an automatic table of contents based on the sections and topic
+pages that you define, which normally appears on the left (for Left to Right
+locales) or right (for Right to Left locales) side of the page content.
+![Navigation Sidebar Example][apple_help_features_navigator]
+
+In the Help Viewer, this table of contents can be revealed or hidden using the
+Help Viewer’s TOC button in the window title bar, or with the
+**Show Topics** (or **Hide Topics**) link that will be be added to the Help
+Book’s [landing page][en.lproj].
+
+When viewing the Help Book served to a web browser, the **Show Topics** (or
+**Hide Topics**) link will not appear. However, the TOC can be revealed or
+hidden via a TOC button that will appear in the banner of the page.
+
+
+Style Sheets
+------------
+
+With a few exceptions described elsewhere in this documentation, all of the
+styling is provided by Apple via the `apple.css` stylesheet. Because Apple
+Help Books generally do not show source code, the `github.css.scss` style
+sheet supplements Apple’s styles, and the `middlemac.css.scss` style sheet
+corrects a couple of issues with Apple’s styles, as well as provides a simple
+alternative for creating Apple’s [tips paragraphs][implement_features].
+
+
+Tasks
+-----
+
+Apple currently uses “tasks” in many of its modern Help Books, and these are
+relatively simply to implement with the [`helpbook_task`][implement_features]
+helper.
+
+Single tasks are always displayed in the expanded state, but when multiple tasks
+are on the same page, like here, they have working disclosure triangles to 
+reveal them.
+
+Make sure you provide unique id’s to the tasks, because Apple’s help system
+keeps track of which ones are revealed or hidden in between page visits.
+
+
+<% helpbook_task "task1", "Expand this task to see what content it contains", :markdown => true do %>
+<%= lorem.paragraphs 2 %>
+<% end %>
+
+
+<% helpbook_task "task2", "This task indicates the answer to the question of life" do %>
+
+The generally accepted answer to this query is **forty-two**.
+
+<%= lorem.paragraphs 2 %>
+<% end %>
+
+
+<% helpbook_task "task3", "Perform this third task" do %>
+Apple’s practice is to nest `<img>` elements within `<figure>` elements, and
+for Apple’s CSS to work properly, this practice should be adhered to.
+_Middlemac_ makes this easy for you by doing this automatically when the 
+[`image_tag`][helpers] helper is used, and when markdown reference format
+images are used, such as here.
+![Icon loaded with the Markdown reference format][icon_256x256]
+<% end %>
+
+
+Tips
+----
+
+Modern Apple Help Books often show tips with a colorful icon to draw your
+attention.
+
+Generally tips are something related to the main content of your article,
+but not necessarily part of the narrative. They might be used to point out
+information that’s not so obvious to your user.
+{: .tip}
+
+Although Apple doesn’t use the following tip styles, _Middlemac_ offers them
+as an extension because they come in useful, like tips, but convey different
+semantics to your users.
+
+Although I couldn’t find any **warning** examples in Apple’s help, it’s
+something that’s sure to be needed by other developers, and so imitating
+Apple’s **Tip** style gives _Middlemac_ access to simple warnings, too.
+{: .warning}
+
+Notes have a use case similar to tips, but with the intention of providing
+additional information that is more educational, rather than pointing out a
+way to do something.
+{: .note}
+
+
+Standard See Also
+-----------------
+
+Apple’s Help Books have a standard format for **See Also** sections of its
+content pages. _Middlemac_’s layouts will automatically provide the proper
+HTML structure when you provide a `:seeAlso` block in any of your help pages.
+![See Also example][apple_help_features_see_also]
+
+Apple’s JavaScript even recognizes when links are internal or external, and
+opens new tabs or windows as appropriate.
+
+A sample **See Also** section appears at the bottom of this page.
+
+<% content_for :seeAlso do %>
+<%= link_to 'See Also article on Wikipedia', 'https://en.wikipedia.org/wiki/See_also' %>
+<%= link_to 'Implement Apple’s Help Features', 'compose_project/implement_features.html' %>
+<%= link_to 'Help Book Landing Page', 'index.html' %>
+<% end %>
+
+
+Other Features not Available on this Page
+-----------------------------------------
+
+### Chapter Headings
+
+You can’t see any chapter headings on this page, because it’s a root level
+page. However if you look at page within a section, such as the
+[Set Up Middlemac][setup] page in the **Get Started** section, you will
+see that the chapter/section name is automatically added to the top of your
+page, before the title.
+
+The example below, from iTunes’ help, shows a page with a chapter heading from
+its “Get Music, Video, and More” section:
+
+![Sample Chapter Heading][apple_help_features_chapter_heading]
+
+### Languages
+
+In addition to the **Copyright** and **Navigation** features described above,
+the [Help Book Landing Page][en.lproj] also provides an interface to switching
+languages when your Help Book is served to a web browser. Feel free to head
+back to the [landing page][en.lproj] to switch the language to Spanish for a
+demonstration of this feature.
+![Language Chooser Example][apple_help_features_language_chooser]
+
+Within Apple Help Viewer, this feature does not exist, as Help Viewer chooses
+the locale for you automatically based on your operating system settings.
+
+### Next and Previous Page Links
+
+Although disabled by default, you can change the `show_previous_next` setting
+in [setup][setup] to `true` so that your Help Books will automatically
+include Apple-style “next page” and “previous page” navigation buttons at the
+bottom of each of your content pages. Because Apple itself does not use this
+feature, it has not been enabled by _Middlemac_.
+
+<div style="display: flex; justify-content: space-around;">
+<%= image_tag 'Resources/SharedGlobalAssets/css/apple/css/img/L0200_LeftArrow_2x.png' %>
+<%= image_tag 'Resources/SharedGlobalAssets/css/apple/css/img/L0201_RightArrow_2x.png' %>
+</div>
+
+### Title Icons
+
+When viewed in Apple Help Viewer, the help icon is automatically inserted
+before the page title headline. For some reason, Apple doesn’t do this when
+your content is viewed served to a browser.
+![Title Icons Example][apple_help_features_title_icons]
+
+Although this is consistent with Apple’s own practices, examining the source
+reveals that the icon is served as part of the page, but merely hidden via
+Apple’s CSS. Given that this is what Apple wants to do, choosing to override
+this behavior via CSS is an exercise left to the user.
+

data/documentation_project/Contents/Resources/{Base.lproj/020_setup_tutorial/index.html.md.erb → en.lproj/030_get_started/010_set_up_middlemac.html.md.erb}

@@ -1,16 +1,11 @@
 ---
-title:  Setting up <em>Middlemac</em>
+title:  Set Up Middlemac
 blurb:  Read this article to learn how install <em>Middlemac</em> and see
         that it’s running on your system.
-layout: template-logo-small
 ---
 <%= md_links %>
 <%= md_images %>
 
-
-<%= current_page.data.title %>
-==============================
-
 Getting Started
 ---------------
 
@@ -20,24 +15,18 @@ 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
+[Ruby](https://www.ruby-lang.org/) installed (it comes pre-installed on macOS
 and some Linuxes), and follow these steps below. 
 
-We now recommend the use of the Ruby Version Manager [(RVM)](https://rvm.io/).
+We 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}
-
-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.
-{:.note}
+tutorial, it avoids the use of `sudo` and the hassles involved with using the
+built in version of Ruby. This tutorial assumes the use of RVM.
+{: .note .callout}
 
 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.
-{:.note}
+{: .tip .callout}
 
 
 Quick version, if you don’t want to read details
@@ -45,7 +34,7 @@ Quick version, if you don’t want to read details
 
 In your Terminal, do each of the following:
 
-~~~ bash
+~~~
 xcode-select --install
 gem install middlemac
 middlemac documentation
@@ -56,48 +45,48 @@ bundle exec middleman --target free
 open middlemac.webloc
 ~~~
 
-Because the penultimate command started the server which keeps control of the
-terminal, you’ll have to open the `.webloc` file in another terminal session,
+Because the penultimate command started the server (which keeps control of the
+terminal), you’ll have to open the `.webloc` file in another terminal session,
 or simply double-click it.
 
 If you’re on Linux and `open middlemac.webloc` command doesn’t work for you,
 then use your preferred web browser and go to
-[http://localhost:4567/Resources/Base.lproj/](http://localhost:4567/Resources/Base.lproj/).
+[http://localhost:4567/Resources/index.html](http://localhost:4567/Resources/index.html).
 
 If you’ve setup your own custom domain, you’ll have to specify that instead of
 `localhost`.
 
 
-Similar to above, with a bit of handholding
-----------------------------------------
+Same as above, with explanations
+--------------------------------
 
 ### 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
+project to develop help for macOS 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 help book.
-Other than for generating your final help book, Linux makes a fine development
+the help indexing tool that’s required in order to build a proper Help Book.
+Other than for generating your final Help Book, Linux makes a fine development
 environment.
-{:.note} 
+{: .note .callout} 
 
 
 ### Install the `middlemac` gem
 
-~~~ bash
+~~~
 gem install middlemac
 ~~~
 
@@ -106,7 +95,7 @@ This will fetch the gem from `rubygems.org` and install it for you.
 
 ### Install the documentation
 
-~~~ bash
+~~~
 middlemac documentation
 ~~~
 
@@ -116,14 +105,14 @@ This will install Middlemac’s documentation project into a new directory
 
 ### Go into the documentation directory
 
-~~~ bash
+~~~
 cd middlemac-docs
 ~~~
 
 
 ### Install bundler (if not already installed)
 
-~~~ bash
+~~~
 gem install bundler
 ~~~
 
@@ -133,20 +122,27 @@ 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.
 
+If you see error messages reported, they will often be accompanied by advice
+for resolving the error. If this doesn’t work and `bundle install` doesn’t
+exit cleanly, you’ll have to Google for a solution. Sadly, sometimes Gems
+just don’t build right on certain systems, but luckily someone else will have
+already experienced and then solved the issue.
+{: .tip .callout}
+
 
 ### Start the _Middleman_ server
 
 _Middleman_ comes with its own HTTP server and requires no configuration. It
-simply works, serving your help book as a website.
+simply works, serving your Help Book as a website.
 
-~~~ bash
+~~~
 bundle exec middleman --target free
 ~~~
 
@@ -162,7 +158,7 @@ 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 go to
-[http://localhost:4567/Resources/Base.lproj/](http://localhost:4567/Resources/Base.lproj/).
+[http://localhost:4567/Resources/index.html](http://localhost:4567/Resources/index.html).
 
 If you’ve setup your own custom domain, you’ll have to specify that instead of
 `localhost`.