middlemac 2.0.0

data/documentation_project/Contents/Resources/Base.lproj/060_content/030_helpers.html.md.erb

@@ -0,0 +1,247 @@
+---
+title:  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_.
+
+
+_Middleman_ helpers
+-------------------
+
+_Middleman_ has several useful, built-in helpers documented on its 
+[web site](http://middlemanapp.com/basics/helper_methods/). These are some of
+the most common ones you will use.
+
+`link_to`
+
+ : This helper greatly simplifies links when you’re not able or willing to use
+   Markdown links.
+   
+   ~~~ erb
+   <%%= link_to 'Content text', 'http://example.com' %>
+   ~~~
+   
+   ~~~ erb
+   <%= link_to 'Content text', 'http://example.com' %>
+   ~~~
+   
+   You can even use a _Middleman_ resource for the second parameter:
+   
+   ~~~ erb
+   <%%= link_to 'Main Page', current_page.breadcrumbs.first %>
+   ~~~
+
+   ~~~ erb
+   <%= link_to 'Main Page', current_page.breadcrumbs.first %>
+   ~~~
+   
+   And you can specify one or more attributes like so:
+   
+   ~~~ erb
+   <%%= link_to 'test', '#', :title => 'test' , :'data-test' => 'data attribute test' %>
+   ~~~
+
+   ~~~ erb
+   <%= link_to 'test', '#', :title => 'test' , :'data-test' => 'data attribute test' %>
+   ~~~
+   
+
+`image_tag`
+
+ : This helper simplifies adding images to your documents. It knows the location
+   of your images if you’ve followed the conventions.
+   
+   ~~~ erb
+   <%%= image_tag 'my_image.png' %>
+   ~~~
+
+   ~~~ erb
+   <%= image_tag 'my_image.png' %>
+   ~~~
+      
+   You can also specify attributes:
+   
+   ~~~ erb
+   <%%= image_tag 'my_image.png', :alt => 'A murder of crows', :title => 'Birds' %>
+   ~~~
+   
+   ~~~ erb
+   <%= image_tag 'my_image.png', :alt => 'A murder of crows', :title => 'Birds' %>
+   ~~~
+   
+   Although these two examples describe _Middleman_’s built-in `image_tag`
+   helper, _Middlemac_ can extend this functionality even more. 
+
+
+`content_for`
+
+ : The built-in templates include an area for “See Also” where you might want to
+   include links in addition to the automatically generated links. You can do
+   this with the `contentfor` helper.
+   
+   ~~~ erb
+   <%% content_for :seeAlso do %>
+   <%%= link_to 'Some interesting site', 'http://example.com' %>
+   <%% end %>
+   ~~~
+
+   As you get more advanced with your use of _Middleman_, you will certainly
+   think of more uses for this.
+
+
+Helpers that Middlemac Overrides
+--------------------------------
+
+_Middlemac_ overrides the behavior to some _Middleman_ partials in order to
+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.
+    
+`image_tag`
+  : _Middlemac_ adds considerable functionality to the base `image_tag` helper.
+  
+      - If your image name begins with the magic prefix `all-`, then
+        _Middlemac_ will substitute an image prefixed with the name of the
+        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.
+        
+        For example if you specify image `all-example.png` and your target is
+        "pro", _and_ if the images exist, then _Middlemac_ will generate an
+        image tag specifying "pro-example.png" and "pro-example@2x.png" for
+        you.
+        
+      - You can specify `:target` and/or `:feature` in the `image_tag` options
+        to ensure that a tag is only generated if you are building the correct
+        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.
+
+
+### `image_tag` Target/Feature example
+
+This example is a standard use of the `image_tag` helper with an ordinary file
+wherein the `@2x` resource is included as a `srcset` automatically.
+
+~~~ erb
+<%%= image_tag 'middlemac-logo-small.png' %>
+~~~
+
+~~~ erb
+<%= image_tag 'middlemac-logo-small.png' %>
+~~~
+
+<%= image_tag 'middlemac-logo-small.png' %>
+
+* * *
+
+This example shows an icon with an image prefixed `all-`, however no target
+specific images are in the image directory. There is an `@2x` version available,
+though, so will be automatically used as the `srcset`.
+
+~~~ erb
+<%%= 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.
+
+~~~ erb
+<%%= image_tag 'all-middlemac-logo-small.png' %>
+~~~
+
+~~~ erb
+<%= image_tag 'all-middlemac-logo-small.png' %>
+~~~
+
+<%= image_tag 'all-middlemac-logo-small.png' %>
+
+
+* * *
+
+Finally, let’s add a `:target` option to the `image_tag` helper. If you’re
+using the Pro version of this documentation, you will see the logo, otherwise
+there will be no image.
+
+~~~ erb
+<%%= image_tag 'all-sample.png', :target=>:pro %>
+~~~
+
+~~~ erb
+<%= image_tag 'all-sample.png', :target=>:pro %>
+~~~
+
+<%= image_tag 'all-sample.png', :target=>:pro %>
+
+
+
+* * *
+
+_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`?
+
+
+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].

data/documentation_project/Contents/Resources/Base.lproj/060_content/040_partials.html.md.erb

@@ -0,0 +1,121 @@
+---
+title:  Partials
+blurb:  Take advantage of <em>Middlemac</em>’s partials, and maybe even learn to
+        write your own!
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+_Middlemac_ includes several partials that it uses to provide a structured,
+easy to use framework for generating Apple Help Books. You can use these 
+partials as they are or modify them to suit your preferences.
+
+The included partials are mostly functional, but you can also make partials for
+other content that you use repeatedly throughout your project.
+
+Note that all partials source filenames are prefixed with an underscore, and
+they also don’t have an `.html` extension. Partials will be included in your
+content pages; we don’t want _Middleman_ to output them into the build
+directory!
+{:.note}
+
+Although the partials discussed below are included in the source code for this
+documentation project, they’re not used in this project. Instead this project
+uses the helpers that correspond to the partials below.
+{:.note}
+
+
+Included partials
+-----------------
+
+Note: because partials are included with the `partial` helper without the
+leading underscore and extension, by convention they are mentioned in this
+documentation without these decorations, too.
+
+`nav_breadcrumbs` and `nav_breadcrumbs_alt`
+ : These (two variations) render the breadcrumbs widget at the top of the 
+   window.
+
+`nav_brethren` and `nav_brethren_index`
+ : These partials render lists of all sibling pages that have a sort order and
+   are part of the current target and feature settings. `nav_brethren` includes
+   the page’s `:blurb` front matter data, and `nav_brethren_index` lacks this.
+ 
+`nav_legitimate_children`
+ : Renders a list with link and blurb for all legitimate children, i.e.,
+   children that have a sort order and are allowed by the current target and
+   features settings.
+
+`nav_prev_next`
+ : This partial renders the navigation widget on pages that have it enabled.
+
+`nav_toc_index`
+ : Renders a site-map style index starting at `current_page` or at a passed-in
+   resource.
+   
+Partials are an excellent alternative to the provided helpers, especially if
+you want to make modifications. Because they correspond exactly with their
+eponymic helpers, you should refer to the [helper API reference][helpers_ref].
+
+
+Your Own Partials
+-----------------
+
+The included partials are purely functional, i.e., they provide service to key
+parts of _Middlemac_’s framework. You can write your own partials that provide
+functionality, too, such as rendering something from a
+[local data file][using_local_data].
+
+You can also 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 and 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.
+
+Note: 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}

data/documentation_project/Contents/Resources/Base.lproj/060_content/050_resources.html.md.erb

@@ -0,0 +1,60 @@
+---
+title:  Middlemac extended <em>resource</em> 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.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<% content_for :seeAlso do %>
+<ul>
+  <li><%= link_to 'Resource API Documentation', '../reference/resource_ext_ref.html' %></li>
+</ul>
+<% end %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= 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.
+
+Note: 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}
+
+
+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 page 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.
+
+
+API Reference
+-------------
+
+Have a closer look at all of the _Middlemac_-provided resource extensions in
+the [Resource API Documentation][resource_ext_ref].

data/documentation_project/Contents/Resources/Base.lproj/060_content/070_including_excluding.html.md.erb

@@ -0,0 +1,68 @@
+---
+title:  Including and excluding targets and features
+blurb:  A reference of how to use targets and features in more detail than that
+        provided in the Help Structure section.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+
+Why include and exclude?
+------------------------
+
+Although _Middlemac_ is an excellent tool for developing single-target Apple
+Help Books, it really shines when you want to develop multiple versions of
+help books for multiple versions of your application.
+
+Delivering a help system tailored _specifically_ for the version of the
+application that it belongs to will increase user satisfaction by allowing them
+to focus on the aspects of the help that’s applicable to them. No one wants to
+attempt to solve a problem and then learn, during troubleshooting, that some
+fancy feature is only available in some other version of your application.
+
+You want to promote other versions of your application, certainly. Multiple
+targets allows you appropriately place upsell messages without distracting
+your users. It also allows you to avoid upselling the users who are already
+using your premium or top-level version.
+
+Maybe your application is available on your website and also the Mac App Store?
+In this case there are certainly going to be feature differences. You web
+version uses _Sparkle_ for updates, but the MAS version doesn’t. Your MAS
+version requires users to authorize writing to user directories because of
+sandboxing, whereas your web-distributed version does not.
+
+Make your help files as polished as your applications, and users will be happy
+and delighted without even really knowing why!
+
+
+Include and Exclude Parts of Pages
+----------------------------------
+
+In the simplest case you have help page that is present for all versions of your
+help book, but some of the content will be different for different targets and
+features. You can re-visit the [`target_name?`][targets] example and the
+[`target_feature?`][features] example to review how to show and hide specific
+content on each page.
+
+Limit Images to Particular Targets and Features
+-----------------------------------------------
+
+Don't forget that the [`image_tag` helper][helpers_ext_ref] can be used with
+parameters to limit images to certain targets and features, too.
+
+
+Include and Exclude Entire Pages
+--------------------------------
+
+In the case of wanting to hide or show entire pages based on target or feature,
+you’ve also seen the `target` and `exclude` [front matter][frontmatter] keys.
+When used, you have excellent control over whether entire pages are visible or
+not.
+