middlemac 2.0.0 → 3.0.0

data/documentation_project/Contents/Resources/{Base.lproj/060_content/030_helpers.html.md.erb → en.lproj/040_compose_project/080_helpers/010_helpers.html.md.erb}

@@ -1,17 +1,10 @@
 ---
-title:  Helpers
+title:  Basic Helpers
 blurb:  A brief look at how <em>Middlemac</em>’s Helpers can help you out.
-layout: template-logo-medium
 ---
 <%= md_links %>
 <%= md_images %>
 
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
 Helpers are methods that return a string, typically a snippet of HTML code, or
 sometimes a value that can be used with ERB. This page highlights some of the
 helpers available in _Middleman_ and added via _Middlemac_.
@@ -64,22 +57,18 @@ the most common ones you will use.
    of your images if you’ve followed the conventions.
    
    ~~~ erb
-   <%%= image_tag 'my_image.png' %>
+   <%%= image_tag 'all-sample' %>
    ~~~
 
-   ~~~ erb
-   <%= image_tag 'my_image.png' %>
-   ~~~
+   <%= image_tag 'all-sample', :figure => false %>
       
    You can also specify attributes:
    
    ~~~ erb
-   <%%= image_tag 'my_image.png', :alt => 'A murder of crows', :title => 'Birds' %>
+   <%%= image_tag 'all-sample', :alt => 'A murder of crows', :title => 'Birds' %>
    ~~~
    
-   ~~~ erb
-   <%= image_tag 'my_image.png', :alt => 'A murder of crows', :title => 'Birds' %>
-   ~~~
+   <%= image_tag 'all-sample', :alt => 'A murder of crows', :title => 'Birds', :figure => false %>
    
    Although these two examples describe _Middleman_’s built-in `image_tag`
    helper, _Middlemac_ can extend this functionality even more. 
@@ -99,7 +88,7 @@ the most common ones you will use.
 
    As you get more advanced with your use of _Middleman_, you will certainly
    think of more uses for this.
-
+{: .nontabular}
 
 Helpers that Middlemac Overrides
 --------------------------------
@@ -109,14 +98,15 @@ provide extra functionality and/or to provide backward compatibility. They are
 fully documented in [their reference section][helpers_ext_ref].
 
 `partial`
+
   : Starting with _Middleman_ version 4, the use of `partials_dir` was removed,
     and now _Middleman_ expects a full path to partials. _Middlemac_, though
     provides this helper with backwards compatibility. If you set `partials_dir`
-    in the `activate :Middlemac` portion of `config.rb`, then _Middlemac_ will
-    first check this directory for your partial before using _Middleman_’s
-    default behavior.
-    
+    in your `config.rb`, then _Middlemac_ will first check this directory for
+    your partial before using _Middleman_’s default behavior.
+
 `image_tag`
+
   : _Middlemac_ adds considerable functionality to the base `image_tag` helper.
   
       - If your image name begins with the magic prefix `all-`, then
@@ -124,10 +114,10 @@ fully documented in [their reference section][helpers_ext_ref].
         current target, if it exists (otherwise the `all-` image will be used).
         This magic prefix is configurable in your `config.rb` file.
         
-      - If the image that you specify has an `@2x` version, then a `srcset`
-        attribute specifying this Retina image will automatically be added for
-        you (unless you’ve added a `srcset` attribute yourself. This even works
-        with magic prefixes.
+      - If the image that you specify has an `@2x`, `@3x`, and/or `@4x` version,
+        then a `srcset` attribute specifying this Retina image will 
+        automatically be added for you (unless you’ve added a `srcset` attribute
+        yourself. This even works with magic prefixes.
         
         For example if you specify image `all-example.png` and your target is
         "pro", _and_ if the images exist, then _Middlemac_ will generate an
@@ -139,6 +129,14 @@ fully documented in [their reference section][helpers_ext_ref].
         target, or if the target includes the specified feature. This provides
         a handy alternative to **if target_name?** and **if target_feature?**
         blocks in your code.
+      
+      - The help automatically embeds images in a `<figure>` element, as this is
+        what Apple’s own style is. You can specify `:figure => false` in the
+        options to prevent this.
+        
+      - Finally, you can specify `:figure_class => "someclass"` to provide a 
+        class to this framing `<figure>`, if desired.
+{: .nontabular}
 
 
 ### `image_tag` Target/Feature example
@@ -150,10 +148,6 @@ wherein the `@2x` resource is included as a `srcset` automatically.
 <%%= image_tag 'middlemac-logo-small.png' %>
 ~~~
 
-~~~ erb
-<%= image_tag 'middlemac-logo-small.png' %>
-~~~
-
 <%= image_tag 'middlemac-logo-small.png' %>
 
 * * *
@@ -166,26 +160,17 @@ though, so will be automatically used as the `srcset`.
 <%%= image_tag 'all-sample.png' %>
 ~~~
 
-~~~ erb
-<%= image_tag 'all-sample.png' %>
-~~~
-
 <%= image_tag 'all-sample.png' %>
 
 
 * * *
 
-The next example selects the image based on the target automatically. No `@2x`
-resources are available and so no `srcset` is added.
+The next example selects the image based on the target automatically.
 
 ~~~ erb
 <%%= image_tag 'all-middlemac-logo-small.png' %>
 ~~~
 
-~~~ erb
-<%= image_tag 'all-middlemac-logo-small.png' %>
-~~~
-
 <%= image_tag 'all-middlemac-logo-small.png' %>
 
 
@@ -199,10 +184,6 @@ there will be no image.
 <%%= image_tag 'all-sample.png', :target=>:pro %>
 ~~~
 
-~~~ erb
-<%= image_tag 'all-sample.png', :target=>:pro %>
-~~~
-
 <%= image_tag 'all-sample.png', :target=>:pro %>
 
 
@@ -213,35 +194,20 @@ _Middlemac_ helpers
 -------------------
 
 _Middlemac_ introduces several other helpers that are available in your files.
-A comprehensive list is available in the [reference section][reference-index],
-but these highlight some of the helpers that you’ll use quite often.
-
-`cfBundleIdentifier`
- : Returns the product `CFBundleIdentifier` for the current target.
-
-`cfBundleName`
- : Returns the product `CFBundleName` for the current
-   target.
-
-`product_name`
-  : Returns the `ProductName` for the current target.
-
-`product_uri`
-  : Returns the `ProductURI` for the current target.
-
-`target_name`
-  : Returns the current build target.
-
-`target_name?(proposal)`
-  : Is the current target `proposal`?
-
-`target_feature?(proposal)`
-  : Does the target have the feature `feature`?
+A comprehensive list is available in the **Reference**, but these highlight
+some of the helpers that you’ll use quite often.
 
+| `cfBundleIdentifier`        | Returns the product `CFBundleIdentifier` for the current target.
+| `cfBundleName`              | Returns the product `CFBundleName` for the current target.
+| `product_name`              | Returns the `ProductName` for the current target.
+| `product_uri`               | Returns the `ProductURI` for the current target.
+| `target_name`               | Returns the current build target.
+| `target_name?(proposal)`    | Is the current target `proposal`?
+| `target_feature?(proposal)` | Does the target have the feature `feature`?
 
 Other Helpers
 -------------
 
 _Middlemac_ is a system consisting of several gems, all of which contribute
-helpers of their own. These are completely documented in the [reference
-section][reference-index].
+helpers of their own. These are completely documented in the
+**API Reference** section.

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/080_helpers/020_markdown_links.html.md.erb

@@ -0,0 +1,51 @@
+---
+title:  ‹md_links› Helper
+blurb:  Learn to take advantage of helpers that give you a hand using 
+        reference style links to content and images.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+You’ll notice (as you look at the source files for this help content) that the
+first ERB instructions immediately after the frontmatter are:
+
+~~~ erb
+<%%= md_links %>
+<%%= md_images %>
+~~~
+
+These convenience helpers make it relatively simple to include Markdown links
+and images using the reference format.
+ 
+Links
+-----
+
+~~~ markdown
+[What is Middlemac?][what_is_middlemac]
+~~~
+
+…will generate the following link:
+
+[What is Middlemac?][what_is_middlemac]
+
+This is especially useful if your page source filenames stay constant.
+
+The reference name will always be the base output name of the file. For index
+files, the format will be `groupname`, where the groupname is the name of the
+containing directory, as you should already know. The top-level index file
+will conveniently, simply be `en.lproj` (or as appropriate for your
+development locale).
+
+You should strive to use unique filenames if you use this feature, as this
+will ensure that your references remain unique. In the event of reference name
+collisions, the reference name will be prepended with its nesting groups as
+many levels as necessary to become unique. For convenience items that are
+higher in your directory hierarchy are prioritized against prepending.
+
+Here’s the complete result of this helper for this Help Book:
+
+<% code('markdown', :css_class => 'shrink_code') do %>
+<%= md_links %>
+<% end %>

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/080_helpers/030_markdown_images.html.md.erb

@@ -0,0 +1,52 @@
+---
+title:  ‹md_images› Helper
+blurb:  Learn to take advantage of helpers that give you a hand using 
+        reference style links to content and images.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+You’ll notice (as you look at the source files for this help content) that the
+first ERB instructions immediately after the frontmatter are:
+
+~~~ erb
+<%%= md_links %>
+<%%= md_images %>
+~~~
+
+These convenience helpers make it relatively simple to include Markdown links
+and images using the reference format.
+ 
+ 
+Images
+------
+
+Markdown also supports a reference format for images. It looks like this:
+
+~~~ markdown
+![this is alt tag content][middlemac-logo-small]
+~~~
+
+And will generate this:
+
+![this is alt tag content][middlemac-logo-small]
+
+
+Here’s the complete result of this helper for this Help Book:
+
+<% code('markdown', :css_class => 'shrink_code') do %>
+<%= md_images %>
+<% end %>
+Note that using reference style Markdown images is performed by the Markdown
+processor directly. Using magic prefixes for automatic target-based images
+won’t work. However they will work with standard Markdown, non-reference
+images. Note how this next example includes the target-specific logo:
+{: .note}
+
+~~~ markdown
+![target specific logo](all-middlemac-logo-small)
+~~~
+
+![target specific logo](all-middlemac-logo-small)

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/080_helpers/index.html.md.erb

@@ -0,0 +1,4 @@
+---
+title:  Helpers
+layout: layout-blank
+---

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/090_partials.html.md.erb

@@ -0,0 +1,64 @@
+---
+title:  Partials
+blurb:  Use partials to keep yourself DRY.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+_Middlemac_ includes the ability to use partials, that is, bits of Markup, pure
+HTML, and/or ERB that can be included in other files, as often as you like.
+You might use partials to contain oft-used content. Maybe pieces of a change
+log, should you want to present that information to your users in multiple
+places. Maybe common warnings that can be included in multiple pages.
+
+
+Conventions
+-----------
+
+Partials should be placed into the correct `partials` directory so that
+_Middleman_’s `partial` helper can find them.
+
+Because partials are not rendered into final HTML output files, you should
+prefix their filenames with an underscore, and _not_ include `.html` in the
+extensions chain.
+
+When using the `partial` helper, _Middleman_ already expects the actual file
+to be prefixed with an underscore, therefore you should _not_ include the
+underscore when you use the helper.
+
+~~~ erb
+<%%= partial 'include_me' %>
+~~~
+
+_not_
+
+~~~ erb
+<%%= partial '_include_me' %>
+~~~
+
+You can pass data to partials as local variable context within the partial.
+For example:
+
+~~~ erb
+<%%= partial 'hello_world', :locals => { :one => 'Rabbit', :color => 'pink' } %>
+~~~
+
+Then, within the code of the partial, you will have local variables `one` and
+`color` available to you with their respective values.
+
+These hash key-values use a symbol as a key, and a value as the value for the
+key. This is not the same as assigning a value to the Ruby symbol, because the
+symbol’s value is simply itself. The hash key is like an `id` object in an
+`NSDictionary`. Then when passed to the partial, there will exist a new local
+variable using the symbol name. The symbol `:one` becomes the variable `one`
+having a string value “pink” in this example.
+{: .note .callout}
+
+
+Examples
+--------
+
+Have a look at the **Reference** section, where most of the API information is
+added to this project as partials.

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/100_resources.html.md.erb

@@ -0,0 +1,36 @@
+---
+title:  ‹resource› Methods
+blurb:  <em>Middlemac</em> extends <em>Middleman</em>’s built in resource
+        (page) methods by adding several methods that make developing Help
+        Books even easier.
+---
+<%= md_links %>
+<%= md_images %>
+
+<% content_for :seeAlso do %>
+<%= link_to 'Resource API Documentation', '../reference/api_reference/resource_ext_ref.html' %>
+<% end %>
+
+<%= current_page.data.blurb %>
+
+_Resources_ in _Middleman_-speak generally refers to pages in _Middleman_’s
+internal site-map. As Ruby objects, resources have a lot of useful information
+about them.
+
+There’s a lot you can do with _Middlemac_ without manipulating or using
+resources directly. The _Middlemac_ framework does a lot of this manipulation
+for you. There’s nothing in this documentation Help Book, for example, that
+uses features not provided by the conventions.
+{: .note .callout}
+
+
+Common _Middleman_ Resources
+----------------------------
+
+Because _Middlemac_’s resources depend so heavily on the built-in resources, a
+quick review and examples are in order.
+
+| `current_page` or `current_resource` | The `current_page` resource is available in all of your help pages, as well as the partials that your help pages include.
+| `current_page.breadcrumbs.first`     | This refers to the top level landing page of your help file.
+| _`resource`_`.parent`                | This references the parent resource. For example `current_page.parent` would refer to the parent container of this one: **<%= current_page.parent.data.title %>**.
+| _`resource`_`.brethren_next` and _`resource`_`.brethren_previous` | These _Middlemac_ supplied references refer to the next and previous pages, respectively, in the current group, and they are resources, too.

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/110_implement_features.html.md.erb

@@ -0,0 +1,197 @@
+---
+title:  Implement Apple’s Help Features
+blurb:  <em>Middlemac</em> makes it pretty easy to implement modern Apple 
+        Help Book features in your own Help Books. This page walks you
+        through them.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+
+Asides
+------
+
+“Asides” are loaded via AJAX from another file into a popup element on the
+current page. To create an aside, simply:
+
+- Create a file that will result in an html file, such as
+  `aside_description.html.md.erb`, as is used in this documentation.
+- Do not specify a page order for this file, as we do not want it included as
+  a standard page. 
+- Ensure that its `categories` [frontmatter][frontmatter] includes `aside`.
+- Ensure that its `layout` [frontmatter][frontmatter] is set to
+  `layout-apple-modern-aside`, or that the file is present in the magical
+  `asides/` directory.
+
+To implement the “aside” in your project, simply use the `link_to` helper,
+specifying the `:aside` option, like so:
+
+~~~ erb
+What is <%%= link_to "an aside", "aside_description.html", :aside => true %>?
+~~~
+
+Results in:
+
+What is <%= link_to "an aside", "aside_description.html", :aside => true %>?
+
+Because the `link_to` helper will search your sitemap for the specified file,
+it’s not usually necessary to specify a path, and as such, you can organize
+the aside files in any manner that you wish.
+{: .tip .callout}
+
+
+Copyright Information
+---------------------
+
+The `:ProductCopyright` value from `config.rb` will be displayed by Apple’s
+help system at the bottom of every help page, as well as on your project’s
+landing page, when served to a browser. Additionally, the message on the
+landing page will automatically become a link to any page that has `copyright`
+assigned as one of its `categories` in the [frontmatter][frontmatter].
+
+If you have multiple pages with `copyright` assigned to the `categories`
+frontmatter key, then the first one found in the sitemap will be the target
+of the link.
+
+
+Tasks
+-----
+
+To create “tasks” as demonstrated in [Apple Help Book Features][apple_help_features],
+use the `helpbook_task` helper provided by _Middlemac_. For example:
+
+~~~ erb
+<%% helpbook_task "task_id_1", "This is the title of the first task" do %>
+<%%= lorem.paragraphs 2 %>
+<%% end %>
+
+<%% helpbook_task "task_id_2", "I also have a title" do %>
+<%%= lorem.paragraphs 2 %>
+<%% end %>
+~~~
+
+
+Will result in:
+
+<% helpbook_task "task_id_1", "This is the title of the first task" do %>
+<%= lorem.paragraphs 2 %>
+<% end %>
+
+<% helpbook_task "task_id_2", "I also have a title" do %>
+<%= lorem.paragraphs 2 %>
+<% end %>
+
+Remember, 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.
+{: .tip .callout}
+
+Make sure you provide unique id’s to the tasks, because Apple’s help system
+keeps track of which one are revealed or hidden in between page visits.
+{: .tip .callout}
+
+
+
+Tips
+----
+
+If you would like to implement tips in the way that Apple does it exactly,
+then use a structure like this:
+
+~~~ html
+<div class="Alert">
+<p class="Tip">
+    <strong class="tip">Tip</strong> You can do lots of neat things like use 
+    Apple’s tip style, and it’s easy with the plethora of helpers. This tip
+    uses the official Apple way to make a tip, but you have to use HTML to
+    conform to Apple’s `&lt;div>` and `&lt;p>` structure.
+</p>
+</div>
+~~~
+
+Which yields:
+
+<div class="Alert">
+<p class="Tip">
+    <strong class="tip">Tip</strong> You can do lots of neat things like use 
+    Apple’s tip style, and it’s easy with the plethora of helpers. This tip
+    uses the official Apple way to make a tip, but you have to use HTML to
+    conform to Apple’s `&lt;div>` and `&lt;p>` structure.
+</p>
+</div>
+
+However, that’s cumbersome to use and remember, so _Middlemac_ has defined
+a style that approximates Apple’s, that’s really simply to use via native
+Markdown style tags. In Markdown you can simply do this:
+
+~~~ markdown
+However that’s kind of pain to remember, so _Middlemac_ makes it really
+easy to add single-paragraph tips right in Markdown, by assigning a style.
+The appearance is a _little_ bit different than Apple’s way, but honors the
+look and feel.
+{: .tip}
+~~~
+
+Which delivers this:
+
+However that’s kind of pain to remember, so _Middlemac_ makes it really
+easy to add single-paragraph tips right in Markdown, by assigning a style.
+The appearance is a _little_ bit different than Apple’s way, but honors the
+look and feel.
+{: .tip}
+
+Similarly, assigning the CSS classes `warning` or `note` with `{: .warning}`
+or `{: .note}` give you these next two callout styles:
+
+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}
+
+Can you guess that this is a note?
+{: .note}
+
+Finally, you can combine the `{: .tip}`, `{: .warning}`, and `{: .note}` with
+the class `callout` like, e.g., `{: .note .callout}` to inset the left and
+right margins by a couple of em. This isn’t Apple’s style, but it tends to
+introduce some much-needed whitespace that serves to highlight these types of
+paragraphs.
+{: .note .callout}
+
+
+Standard See Also
+-----------------
+
+Apple’s Help Books have a standard format for **See Also** sections of its
+content pages. _Middlemac_’s templates will automatically provide the proper
+HTML structure when you provide a `:seeAlso` block in any of your help pages.
+
+Apple’s JavaScript even recognizes when links are internal or external, and
+opens new tabs or windows as appropriate.
+
+This page’s **See Also** block is defined as so:
+
+~~~ erb
+<%% content_for :seeAlso do %>
+<%%= link_to 'Apple Help Book Features', 'apple_help_features/index.html' %>
+<%%= link_to 'Help Book Landing Page', 'index.html' %>
+<%% end %>
+~~~
+
+<% content_for :seeAlso do %>
+<%= link_to 'Apple Help Book Features', 'apple_help_features/index.html' %>
+<%= link_to 'Help Book Landing Page', 'index.html' %>
+<% end %>
+
+Although the **See Also** content is defined right here in the source file,
+it will appear (properly) at the bottom of this page.
+
+The use of the `md_links` helper to provide Markdown reference-style links is
+not supported in the `:seeAlso` block. This is a limitation of the way that
+_Middleman_ builds files. However, the `link_to` helper works just fine in
+this case.
+{: .note .callout}
+
+

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/120_preview_build.html.md.erb

@@ -0,0 +1,85 @@
+---
+title:  Preview and Build your Help Books
+blurb:  Your development be quicker by previewing your work with
+        <em>Middleman</em>’s preview server before the next step:
+        building your Help Book.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+Preview in a Web Browser
+------------------------
+
+_Middleman_ has its own web server so that you can preview your work during
+development. From within your project directory, simply do:
+
+~~~
+bundle exec middleman
+~~~
+
+This will start the server with your default target. To specify a specific
+target to serve, simply use the `--target` command line option:
+
+~~~
+bundle exec middleman --target your_target_here
+~~~
+
+In general the server address to connect to in your browser is
+`localhost:4567`, but your environment could be different. The server will
+always provide one or more addresses to try.
+
+Note also that if you try to connect to your Help Book project at the server
+root, you will receive a file not found error. Do remember that due to macOS
+Help Book requirements, the content actually begins at
+`/Resources/index.html`.
+
+
+Build your Help Book(s)
+-----------------------
+
+Building your projects is similarly easy:
+
+~~~
+bundle exec middleman build
+~~~
+
+…to build the default target.
+
+~~~
+bundle exec middleman build --target your_target_here
+~~~
+
+…to build the target named `your_target_here`.
+
+
+~~~
+bundle exec middleman build_all
+~~~
+
+…to build all of your targets at once.
+
+
+Opening your Help Books
+-----------------------
+
+macOS won't open Help Books that haven’t been indexed by the operating system,
+so you’ll have to preview them in a real application. Because you’re making
+a Help Book, it’s presumed that you have an application that can fill this
+role. If not, you can modify the included **HelpViewerApp** Xcode project
+that’s in this documentation project’s directory.
+
+To view the contents of the `.help` package in **Finder**, simply
+context-click it and choose **Show Package Contents**.
+
+
+Troubleshooting Caches
+----------------------
+
+Sometimes your Help Books will not function properly in Apple Help Viewer.
+This can occur during development particularly, because macOS performs caching
+to improve performance. If you experience difficulties with your Help Book
+in Apple Help Viewer, consider clearing the caches by deleting the directories
+`~/Library/Caches/com.apple.helpd/` and
+`~/Library/Caches/com.apple.helpviewer/`.