middlemac 2.0.0 → 3.1.2

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

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/030_directory_conventions.html.md.erb

@@ -0,0 +1,206 @@
+---
+title:  Directory Conventions
+blurb:  Learn about proper structure for your directory hierarchy, filenames,
+        and image locations, and discover some best practices related to 
+        paths.
+---
+<%= md_links %>
+<%= md_images %>
+
+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 `en.lproj` directory (or the directory of the
+locale for which you’re developing), 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 so that you can determine where to put your files.
+Also don’t forget to have a look later at the 
+[Directory and File Reference][directory_reference] topic for additional
+information about these directories and the specific files within them.
+
+`Contents/`
+
+  : Contains everything in your help project that will be compiled into or
+    contribute to the final `.help` project.
+   
+`Contents/Resources/SharedGlobalAssets/`
+
+  : This directory contains assets that are common between all of your 
+    different help language projects, as well as assets that _Middlemac_
+    requires by convention, such as Apple’s CSS and JavaScripts, certain image
+    files, data files, layouts, and so on. Full reference documentation is
+    available in the [Directory Layout][directory_reference] topic.
+   
+   
+`Contents/Resources/SharedGlobalAssets/_data/`
+
+  : This directory contains data files that you can use to supply data for
+    [using local data][local_data]. This directory will not be output in the
+    final build.
+
+`Contents/Resources/SharedGlobalAssets/_layouts/`
+
+  : All layouts exist here. This directory will not be output in the final
+    build. In general, you should have no reason to add additional layouts
+    when building current Apple Help Books.
+
+`Contents/Resources/SharedGlobalAssets/_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.
+
+`Contents/Resources/SharedGlobalAssets/convention/`
+
+  : Images that the Apple Help Book and _Middlemac_ require by convention go
+    here. This is separate from the `images/` directory simply to make
+    directory management simpler by avoiding the mixing of required and
+    non-required files. _Middleman_ helpers will find images that are in
+    this location automatically, if needed.
+  
+  
+`Contents/Resources/SharedGlobalAssets/css/`
+
+  : Your `.css` and `.scss` files, if any, should go here. They will not be
+    included automatically in your project unless you modify the main 
+    `index.html` file to include them.
+  
+
+`Contents/Resources/SharedGlobalAssets/fonts/`
+
+  : Any fonts that you wish to include should go here. In general if you are
+    building an Apple Help Book, additional fonts should not be needed.
+  
+
+`Contents/Resources/SharedGlobalAssets/images/`
+
+  : All images should go here. _Middleman_ will find them automatically if
+    you use the helpers.
+
+
+`Contents/Resources/SharedGlobalAssets/js/`
+
+  : Javascripts, if any, should go here. They will not be included
+    automatically in your project unless you modify the main `index.html`
+    file to include them.
+
+   
+`Contents/Resources/en.lproj`
+
+  : This directory serves as your base [group][groups] for the English version
+    of your Help Book, and it contains all of your Help Book’s content,
+    including locale-specific versions of your resources.
+   
+    Any other files that result in `.html` in this directory level, except for
+    `index.html` constitute part of the `en.lproj` group. At this level you
+    should start adding directories to contain your other groups.
+   
+    Certainly, you’re not required to develop in English, and _Middlemac_
+    supports multiple languages simultaneously. See **Locale Directories**,
+    below.
+   
+   
+`Contents/Resources/en.lproj/assets/`
+
+ : This directory contains all of the localized assets used in your Help Book.
+   In order for _Middlemac_’s asset helpers such as `image_tag` and `partial`
+   to find localized resources, and subdirectories of `assets/` must mirror
+   the subdirectories of `SharedGlobalAssets/`, e.g., `assets/images/`.  
+
+
+`Contents/Resources/en.lproj/asides/`
+
+ : This optional directory can be used to house your `.html.md.erb` files that
+   you use for the Help Book _asides_ feature. Any asides in this directory
+   will have the correct layout applied to them automatically, meaning that
+   it won’t be necessary to specify `layout: layout-apple-modern-aside` in
+   these files’ frontmatter.
+{: .nontabular}
+
+
+Locale Directories
+------------------
+
+Throughout this documentation we assume the use of the English locale, with
+your localized files placed into `en.lproj`. Apple’s JavaScripts do not
+support the use of `Base.lproj` or development regions, and so development in
+other languages must take place in language specific directories, as defined
+in `SharedGlobalAssets/_data/locale-list.json`:
+
+| Name                  | ISO Name                | Directory
+|-----------------------|-------------------------|-----------------------
+<% data[:'locale-list'].each do |locale| %>
+| <%= locale[:name] %>  | <%= locale[:isoName] %> | <%= locale[:folder] %>
+<% end %>
+
+The file `SharedGlobalAssets/_data/locale-list.json` is as it was provided by
+Apple; you are free to modify this file if you wish to add a localization that
+is not already present.
+{: .tip .callout}
+
+To rename an existing locale in your project, simply rename the `.lproj` folder
+to one of the supported folder names above. Everything else will be taken care
+of automatically when you build your project.
+
+To create an additional locale, create a new folder in `Resources/` with one of
+the supported names from the table above, and then copy into this new folder
+the following files from the `en.lproj` folder:
+
+- `ExactMatch.plist.erb`
+- `InfoPlist.strings.erb`
+- `locale-info.json.erb`
+- `navigation.json.erb`
+- `searchTree.json.erb`
+
+
+Images
+------
+
+Most images, of course, should go into the `images` directory of your locale’s
+`assets` folder or `SharedGlobalAssets/images`.
+
+However _Middlemac_ also depends on some magic images being placed in
+`SharedGlobalAssets/convention/`:
+
+`icon_32x32.png`
+`icon_32x32@2x.png`
+
+ : These files are your help file icon at 32 × 32 pixels and @2x, and will be
+   used by the included layouts 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`
+`icon_256x256@2x.png`
+
+ : The same as above, but at 256 × 256 pixels and @2x.
+ 
+`icon-webclip-*.png`
+
+ : These assets are used automatically by Apple Help when serving help content
+   to a browser, typically on a mobile device.
+ 
+
+### Images Organization
+
+When your content images are located in the `SharedGlobalAssets/images/`
+directory or your `en.lproj/assets/images/` directory (or directory as
+appropriate to your locale), then _Middleman_’s [helpers][helpers] can find
+them automatically without any worry about relative or absolute file paths.
+
+Images specified without paths are sought first in your `language.lproj/`
+directory, then `SharedGlobalAssets/images/`, and then finally in
+`SharedGlobalAssets/convention`.
+
+### Image Paths
+
+Apple’s JavaScript rewrites image paths to make them load properly from
+the main `index.html` file. Thus, when _Middlemac_ builds your pages, images
+will be root-relative when you examine the source, but relative to the main
+`index.html` when examined in your browser’s debugging tools.