middlemac 2.0.0 → 3.0.0

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

@@ -1,121 +0,0 @@
----
-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

@@ -1,60 +0,0 @@
----
-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

@@ -1,68 +0,0 @@
----
-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.
-

data/documentation_project/Contents/Resources/Base.lproj/060_content/080_markdown_links_images.html.md.erb

@@ -1,93 +0,0 @@
----
-title:  <code>md_links</code> and <code>md_images</code> helpers
-blurb:  Learn to take advantage of helpers that give you a hand using reference
-        style links to content and images.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-
-<%= current_page.data.title %>
-==============================
-
-<%= 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
-[all help content][all_help_content-index]
-~~~
-
-…will generate the following link:
-
-[all help content][all_help_content-index]
-
-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-index`, where the groupname is the name of
-the containing directory, as you should already know. The top-level index file
-will conveniently, simply be `index`.
-
-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:
-
-~~~ markdown
-<%= md_links %>
-~~~
-
-Pretty neat how it includes the titles, right? Try hovering your mouse over the
-example [all help content][all_help_content-incex] link. Including titles isn’t
-possible in Markdown without using reference links.
-{:.note}
-
-
-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:
-
-~~~ markdown
-<%= md_images %>
-~~~
-
-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/Base.lproj/060_content/090_css_image_sizes.html.md.erb

@@ -1,90 +0,0 @@
----
-title:  Automatic CSS Image Maximum Sizes
-blurb:  Ensure that your image sizes aren’t unexpectedly distorted by using this
-        special helper.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-This helper provides CSS code for each of your images, specifying a `max-width`
-and `max-height` for each image used in your Middleman project (except for SVG
-files, which don’t have dimensions).
-
-## Example
-
-When called like this:
-
-~~~ erb
-<%%= css_image_sizes %>
-~~~
-
-…the result is this:
-
-~~~ scss
-<%= css_image_sizes %>
-~~~
-
-## Use
-
-You could use this in an HTML `<style>` element on each of your pages, or better
-yet in your layouts. This has the unfortunate effect of including it in every
-one of your pages, however, and so this sample project uses it like this:
-
-Contents of `stylesheets/css_image_sizes.css.erb`:
-
-~~~ erb
-<%%= css_image_sizes %>
-~~~
-
-This will create `stylesheets/css_image_sizes.css` in your build output, and
-this file is included in the project layout file:
-
-~~~ haml
-= stylesheet_link_tag 'css_image_sizes'
-~~~
-
-You will be tempted to add this helper to your `style.css.scss` file, maybe
-even renaming it to `style.css.scss.erb`, but this will not work due to the
-order that Middleman and SASS build output.
-{:.note}
-
-
-## Technical details
-
-This CSS will control your image sizes by specifying a maximum width and height
-for each image in the project using the `src` attribute selector and matching
-against the end of that value. For example:
-
-~~~ scss
-img[src$='icon.png'] { max-width: 256px; max-height: 256px; }
-~~~
-
-CSS matches using literal text, and so will not respect relative paths. The
-simple rule above has a high possibility of naming collisions with other files
-named `icon.png`.
-
-If you follow Middleman’s best practices and keep most or all of your images in
-the defined `:images_dir` then the possibility of naming collisions will go
-away, as this helper will deliver the `src` attribute selectors starting with
-the final component of your `:images_dir`, for example:
-
-~~~ scss
-img[src$='images/logo-small.png'] { max-width: 128px; max-height: 128px; }
-img[src$='images/blog/logo-small.png'] { max-width: 160px; max-height: 160px; }
-img[src$='icon_32x32.png'] { max-width: 32px; max-height: 32px; }
-~~~
-
-In this example, the last image – `icon_32x32.png` – is not within `:images_dir`
-and so has no directory and is subject to naming collisions.
-
-The scheme above will work whether or not Middleman is configured with
-`relative_assets` because both relative and absolute links will always contain
-that last part of the path component. The only way this might break is by
-serving HTML pages from within your `:images_dir`.

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

@@ -1,21 +0,0 @@
----
-title:  "Workflow: Develop your Help Content"
-blurb:  Once you’ve learned of the possibilities when it comes to structuring
-        your help, discover all of the conveniences made possible by
-        <em>Middlemac</em>’s rich set of content features.
-layout: template-logo-large
-navigate: true
----
-<%= md_links %>
-<%= md_images %>
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-* * *
-
-<%= nav_legitimate_children %>
-
-* * *

data/documentation_project/Contents/Resources/Base.lproj/070_preview_build/index.html.md.erb

@@ -1,78 +0,0 @@
----
-title:  "Workflow: 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."
-layout: template-logo-medium
-navigate: true
----
-<%= md_links %>
-<%= md_images %>
-
-<%= current_page.data.title %>
-==============================
-
-<%= 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:
-
-~~~ bash
-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:
-
-~~~ bash
-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 Mac OS X
-help book requirements, the content actually begins at `/Resources/Base.lproj/`.
-
-
-Build your Help Book(s)
------------------------
-
-Build your projects is similarly easy:
-
-~~~ bash
-bundle exec middleman build
-~~~
-
-…to build the default target.
-
-~~~ bash
-bundle exec middleman build --target your_target_here
-~~~
-
-…to build the target named `your_target_here`.
-
-
-~~~ bash
-bundle exec middleman build_all
-~~~
-
-…to build all of your targets at once.
-
-
-Opening your Help Books
------------------------
-
-Mac OS X 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 help books, 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**.

data/documentation_project/Contents/Resources/Base.lproj/090_build_application/10_apple_help_setup.html.md.erb

@@ -1,110 +0,0 @@
----
-title:  Apple .help bundle setup
-blurb:  A reference to what <em>Middlemac</em> does to ensure that you build a
-        proper, working Apple Help Book.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-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`.
-
-Let’s use this information and start to setup Xcode.
-
-
-Xcode Configuration
--------------------
-
-### Add Files 
-
-Let’s first tell your Xcode 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.
-
-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.
-
-Just in case the bold sentence wasn’t reminder enough: make sure you select the
-option to create folder references when adding files.
-{:.note}
-
-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**.
-{:.note}
-
-In each of your `Info.plist` files, find or create the following keys:
-
-`Help Book directory name` (Xcode name)
-`CFBundleHelpBookFolder` (raw key name)
-
- : Ensure you use the appropriate `Middlemac (pro).help` or
-   `Middlemac (free).help`, depending on which target’s `.plist` this is.
-
-`Help Book identifier` (Xcode name)
-`CFBundleHelpBookName` (raw key name)
-
- : 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`.
-
-
-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.
-