middlemac 2.0.0 → 3.0.0

data/documentation_project/Contents/Resources/Base.lproj/050_structure/020_layouts_and_templates.html.md.erb

@@ -1,71 +0,0 @@
----
-title:  Layouts and Templates
-blurb:  Learn the details about how templates and layouts work with each other
-        as well as some best practices for their use.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-_Middlemac_ decouples your help _content_ from the display and final document
-structure by taking advantage of layouts and templates. In general both layouts
-and templates do the same thing; they wrap your content into the structure
-required of an HTML file.
-
-In practice, though, _Middlemac_ distinguishes between them in the manner: a
-_layout_ defines the formal HTML structure of the end document, and a template
-defines the superficial appearance of a particular page. For example a page
-might be wrapped in the `template-logo-medium` template to define its overall
-look, and then further wrapped in `layout-html4` to ensure that it has the
-required structure for an Apple help book.
-
-
-Templates
----------
-
-_Middlemac_ comes with three templates inspired by recent Mac OS X help files.
-Although you can certainly use any of the templates you desire (or create your
-own), the included templates were designed with specific purposes in mind.
-
-`template-logo-large`
- : This template features your help icon in a large size with your target’s
-   `ProductName` and `ProductURI` below it, in a left frame-like area. Your
-   content is in the right frame-like area. This template was designed to be
-   suited for the main landing page and for main section landing pages
-   consisting primarily of links and descriptions of other pages.
-
-`template-logo-medium`
- : This template places a smaller logo in a frame-like area to the right,
-   followed by automatically placed “related links” to other pages in the same
-   group. Your content will occupy the large, left side of the window. This
-   template is idea for multiple, related pages within a group.
-
-`template-logo-small`
- : The template places a very small logo at the top of your page. Related links
-   will appear at the bottom of the page after your content. This template is
-   most suited for topics that stand somewhat alone.
-
-Each of these templates will wrap a layout around them. By default they will
-always use `layout-html4`, although you can force _Middlemac_ to use the
-`layout-xhtml` template with the `:xhtml` frontmatter key. You should never do
-this, though, as Apple requires your content -- except the top level landing
-page -- to be HTML4.
-
-
-Layouts
--------
-
-`layout-html4`
-  : This is just an HTML 4.01 wrapper template and if you follow all of the
-    conventions there's nothing you should have to change here.
-
-`layout-xhtml`
-  : Apple's help landing page (the main page) is supposed to be an XHTML 1.0
-    Strict document. If you follow all of the conventions there's nothing you
-    should have to change here.

data/documentation_project/Contents/Resources/Base.lproj/050_structure/025_css.html.md.erb

@@ -1,71 +0,0 @@
----
-title:  CSS and Fonts
-blurb:  Have a brief look at the included CSS so that you can decide how to best
-        use it or easily change it to suit your own needs.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-
-The included CSS and fonts are critical for ensuring that the templates work,
-but they also serve to provide a recent Apple-like look and feel to your help
-books.
-
-## The `assets/fonts/` directory
-
-`font-awesome/*` (directory)
- : The files here provide you the ability to use the icons in the font provided
-   by the [font-awesome](http://fortawesome.github.io/Font-Awesome/) project.
-   You can review their documentation if you’d like to include these easy to
-   use images in your project. This documentation uses icons in the navigator
-   buttons.
-   
-## The `assets/stylesheets/` directory
-
-`_apple_helpbook.scss`
- : This file contains all of the real styling for _Middlemac_ help books. This
-   should be the first place you check for making desired changes.
-   
-   Note that this `.scss` file will be processed but not output to the build
-   directory because it starts with an underscore.
- 
-`_github.scss`
- : This file contains the styling used for Markdown `<code>` blocks for syntax
-   highlighting, and provides highlighting similar to Github’s style.
- 
-   Note that this `.scss` file will not output to the build directory because it
-   starts with an underscore.
-
-`_normalize.scss`
- : Although _Middlemac_ is intended to build Apple Help Books, its content can
-   be viewed in web browsers, too. Therefore for convenience, this standard
-   normalize file will help ensure that your content looks nearly the same in
-   any modern, popular browser.
- 
-   Note that this `.scss` file will be processed but not output to the build
-   directory because it starts with an underscore.
-
-`breadcrumb-separator-light.png`
- : This image is used by CSS to provide a separator between breadcrumb items.
-   It’s not out of place being in a stylesheets directory.
-
-`images_sizes.css.erb`
- : This `.erb` file is processed into a stylesheet (via the `css_image_sizes`
-   helper) containing the maximum width and height of every image asset in your
-   project. This will ensure that strange scaling doesn’t occur, and can save
-   time by not having to specify fixed image widths and heights for images you
-   may want to use.
-   
-   This file will be copied to the build project and must be included in your
-   layouts if you wish to use it.
-
-`style.css.scss`
- : _This_ file, when compiled to CSS, `@include`’s the pertinent files above 
-   and bundles them into a single file that is included in the default layouts.

data/documentation_project/Contents/Resources/Base.lproj/050_structure/030_groups.html.md.erb

@@ -1,83 +0,0 @@
----
-title:  Groups
-blurb:  Groups are the fundamental organizational technique that enable
-        automatic page management, navigation, and tables of contents simple to
-        implement, and they help you stay organized.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-What are groups?
-----------------
-
-A Group is one of more files in a single level of directory, and also any
-`index.html` file of immediate subdirectories of the group.
-
-Group directories require one file that will compile into `index.html` file in
-that directory, e.g., `index.html.md.erb`. This file _is not part of the group_;
-it serves as the _parent_ to the group. The files in the group are all 
-_children_ of the `index.html` file. Each file in the group is a _sibling_ of
-the other files in the group.
-
-Groups are named based on their containing directory. The highest level group is
-`Base.lproj` and cannot be changed. Group names are generally not user-facing,
-and the Apple Help system requires this directory name, so don’t worry about it.
-
-Example:
-
-~~~
-Base.lproj/
-  index.html
-  introduction.html
-  basics/
-    index.html
-    counters.html
-~~~
-
-The `Base.lproj` consists of two pages: `introduction.html`, and
-`basics/index.html`. The highest-level `index.html` is the parent of this
-group.
-
-Groups can be nested to arbitrary levals.
-
-
-Page order in groups
---------------------
-
-Using the included [helpers][helpers], you can designate tables of contents,
-related pages, indices, etc., for groups with a single line of code. In addition
-_Middlemac_ includes built-in navigation widgets for groups, should you like to
-use them.
-
-A group member’s sort/navigation order is determined two ways.
-
-- Files in the group can have an `:order` key in the frontmatter, or
-- File names can be prefixed with an integer sort order followed by an
-  underscore, .e.g, `40_hello.html.md.erb` or `12345_big_numbers.html.md.erb`.
-
-Some important aspects about order numbers in groups are:
-
-- If both a prefix and `:order` key are present, then the `:order` key takes
-  precedence.
-- If any pages in the same group end up with the same sort order, then the
-  actual behavior is undefined.
-- Parent `index.html` files cannot be prefixed, and so must include an `:order`
-  key in their frontmatter, or prefix the containing directory name instead.
-- Pages without a sort order are _not_ present in any of the automatic 
-  navigation or contents partials or helpers. This is by design. You can still
-  link to them, though.
-- Prefixing file names can be convenient so that source files are sorted in your
-  file system the same way they will be displayed in your help system. Keep in
-  mind, though, that if you’re using the automatic markdown links from the
-  `md_links` helper and name collisions occur, then it’s possible that some of your
-  links will become invalid.
-- Finally, page orders do not have to be sequential. It may be helpful to space
-  them apart so that later insertions can be simplified.
-

data/documentation_project/Contents/Resources/Base.lproj/050_structure/040_breadcrumbs.html.md.erb

@@ -1,43 +0,0 @@
----
-title:  Breadcrumbs
-blurb:  Breadcrumbs help prevent your users from becoming lost, especially if
-        you have deeply nested content. Get to know your options here.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-Breadcrumbs by default appear on every page of your help file, except for the
-main landing page (which, as root, has no breadcrumb trail).
-
-There are two helpers that can each produce the breadcrumbs widget that’s at
-the top:
- 
-`nav_breadcrumbs`
- : Produces breadcrumbs ending with the title of the current page. 
- 
-`nav_breadcrumbs_alt`
- : Produces breadcrumbs with “Current page” at the end instead of the title of
-   the current page.
-
-
-Configuration
--------------
-Breadcrumbs are configured in your `config.rb` file using the `Breadcrumbs`
-option, which can be set to one of the two helpers above, or to `nil` to
-disable breadcrumbs completely.
-
-If you design your own breadcrumbs helper, you can use the same configuration
-setting to use it instead, too: simply specify the name of your own breadcrumbs
-helper.
-
-
-Including Breadcrumbs
----------------------
-_Middlemac_ includes breadcrumbs in the `layout-html4` template.

data/documentation_project/Contents/Resources/Base.lproj/050_structure/050_navigator.html.md.erb

@@ -1,26 +0,0 @@
----
-title:  Navigator
-blurb:  Learn how the page navigator can make navigation easy for your users, as
-        well as how to turn it on or off for groups and individual pages.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-Near the bottom of this page you can see the navigator. It’s visible because
-this page’s parent `index.html` file includes `navigate: true` in its
-frontmatter.
-
-Setting `:navigate` in the frontmatter will cause all pages with an
-[order][groups] to display the navigator. This can be overridden on a
-page-per-page basis by using the `:navigator` frontmatter key, e.g., `navigator:
-false`.
-
-The helper `nav_prev_next` provides the navigator structure, and the appearance
-is set in CSS.

data/documentation_project/Contents/Resources/Base.lproj/050_structure/060_targets.html.md.erb

@@ -1,63 +0,0 @@
----
-title:  Targets
-blurb:  Targets let you build help files that are specific to each version or
-        variant of your Mac OS X application.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-
-Demonstration
---------------
-<% if target_name?(:pro) %>
-You are reading this help book using the `:pro` target. You can try rebuilding
-the project or starting the server with the `:free` target to get a different
-result.
-<% end %>
-<% if target_name?(:free) %>
-You are reading this help book using the `:free` target. You can try rebuilding
-the project or starting the server with the `:pro` target to get a different
-result.
-<% end %>
-
-
-How did this work?
-------------------
-The source file uses a simple conditional and helper to display content based on
-the target name. Here’s the (nearly) exact code that was used:
-
-~~~ erb
-<%% if target_name?(:pro) %>
-You are reading this help book using the `:pro` target. You can try rebuilding
-the project or starting the server with the `:free` target to get a different
-result.
-<%% end %>
-<%% if target_name?(:free) %>
-You are reading this help book using the `:free` target. You can try rebuilding
-the project or starting the server with the `:pro` target to get a different
-result.
-<%% end %>
-~~~
-
-Why “nearly” exact code? If you examine the `.md.erb` file you will see how to
-escape ERB delimiters so that ERB doesn’t try to process them as Ruby code.
-In order to display `<%% %>` it is necessary to specify `<%%% %>` in code
-blocks. And of course you can read about code blocks and other Markdown
-formatting on
-[kramdown’s documentation site](http://kramdown.gettalong.org/documentation.html).
-
-
-Include or exclude entire pages
--------------------------------
-
-Whether you’re currently using the `:pro` or `:free` target, try visiting
-each of these pages:
-
-- [sample page excludes target `:free`](not_free.html)
-- [sample page excludes target `:pro`](not_pro.html)

data/documentation_project/Contents/Resources/Base.lproj/050_structure/070_features.html.md.erb

@@ -1,122 +0,0 @@
----
-title:  Features
-blurb:  Features work similarly to targets, but give you much more fine-grained
-        control.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-
-Demonstrations
----------------
-
-* * *
-
-<% if target_feature?(:feature_advertise_pro) %>
-**New! Today Only!!! Act before this special offer is gone forever!** Why settle
-for the limitations of _Middlemac Free_ when you can upgrade to _Middlemac Pro_
-for this limited time, special price of only $1299.99?
-
-(Note: there is no _Middlemac Pro_. This is part of the Features demonstration.)
-
-* * *
-<% end %>
-
-
-<% if target_feature?(:feature_performs_miracles) %>
-If you open your water faucet, clean, safe, potable water will flow out of it.
-_Middlemac_ has made this miracle happen for you.
-
-* * *
-<% end %>
-
-
-<% if target_feature?(:feature_insults_user) %>
-If you have made it this far, dear reader, you should know that if brains were
-dynamite, you wouldn’t have enough to blow your nose.
-<% else %>
-If you have made it this far, dear reader, you should know that you are one of
-the best people in the world.
-<% end %>
-
-* * *
-
-<% if target_feature?(:feature_shows_pink_rectangle) %>
-I made a special, pink rectangle just for you!
-<svg style="width:50px; height:35px; display:block; margin:auto;">
-  <rect width="50" height="35" style="fill:pink;stroke-width:0" />
-</svg>
-<% else %>
-Too bad; other people got to see a nice, pink rectangle.
-<% end %>
-
-* * *
-
-
-Recall our targets’ `feature` settings
---------------------------------------
-
-Our `:free` target uses these `feature` settings:
-
-~~~ ruby
-:feature_advertise_pro        => true,
-:feature_performs_miracles    => false,
-:feature_insults_user         => true,
-:feature_shows_pink_rectangle => true,
-~~~
-
-And `:pro` was setup with these `feature` settings:
-
-~~~ ruby
-:feature_advertise_pro        => false,
-:feature_performs_miracles    => true,
-:feature_insults_user         => false,
-:feature_shows_pink_rectangle => true,
-~~~
-
-Depending on the target that you are currently viewing, you should very easily
-be able to correlate what appears in the **Demonstrations** section with the
-`feature`s settings above. Try changing some of the values and see what happens
-to this page.
-
-
-Targets vs Features
--------------------
-
-While you can use targets exclusively, it’s then up to you to decide which
-content you want to include in each of your help books when your Mac OS X
-applications have different features. For example, what happens when you decide
-to enable or disable a feature in a future release of your application? If you
-use targets alone, you’ll have to go back and make a lot of changes to your
-help content. If you use **features**, instead, it’s as simple as toggling the
-value of your target’s `:features` sub-key between `true` and `false`.
-
-
-How did this work?
-------------------
-Features work nearly identically to [targets][targets]. Instead of using the
-`target_name?` helper, use the `target_feature?` helper instead. For example:
-
-~~~ erb
-<%% if target_feature?(:feature_insults_user) %>
-If you have made it this far, dear reader, you should know that if brains were
-dynamite, you wouldn’t have enough to blow your nose.
-<%% else %>
-If you have made it this far, dear reader, you should know that you are one of
-the best people in the world.
-<%% end %>
-~~~
-
-
-Include or exclude entire pages
--------------------------------
-
-Just as with targets, you can use front matter `target` and `exclude` to include
-or exclude entire pages.

data/documentation_project/Contents/Resources/Base.lproj/050_structure/index.html.md.erb

@@ -1,21 +0,0 @@
----
-title:  "Workflow: Develop your Help Structure"
-blurb:  Before you get busy writing all of your content, learn how
-        <em>Middlemac</em> expects your project to be structured, and how this
-        structure benefits you.
-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/060_content/010_frontmatter.html.md.erb

@@ -1,88 +0,0 @@
----
-title:  Frontmatter and keys
-blurb:  Examine all of the different frontmatter keys and their use in a single
-        location.
-layout: template-logo-medium
----
-<%= md_links %>
-<%= md_images %>
-
-
-<%= current_page.data.title %>
-==============================
-
-<%= current_page.data.blurb %>
-
-
-Frontmatter
------------
-Frontmatter is metadata that is included at the top of every content page but
-will not be present in the output. It is used to provide information to
-_Middleman_ and _Middlemac_ on a page by page and group basis.
-
-Here is the frontmatter from this very page’s source file:
-
-~~~ yaml
----
-title:  Frontmatter and keys
-blurb:  Examine all of the different frontmatter keys and their use in a single
-        location.
-layout: template-logo-medium
----
-~~~
-
-You can also specify your own frontmatter keys and values. All frontmatter is
-available for use in your pages and templates via `current_page.data`, e.g.,
-`current_page.data.title`.
-
-Also know that if you want to style content that will be rendered to HTML in
-the frontmatter, such as in a blurb, then HTML is required. HAML and Markdown
-do not touch content in the frontmatter. For example, if you want to emphasize
-text in a blurb, you will have do to something like this example:
-
-~~~ yaml
-blurb: I must <em>emphasize</em> that going to war with an empty treasury is bad.
-~~~
-
-
-Middlemac Frontmatter Keys
---------------------------
-
-`title`
- : The page title will be used in to the HTML `<title>` tag for every page,
-   and more importantly, will be the text displayed for links by all of
-   _Middlemac_’s built-in partials.
-
-`blurb`
- : The blurb will be used as a description for a link for the included
-   _Middlemac_ partials that render indexes. This help documentation also
-   repeats the blurb at the top of every article.
-
-`layout`
- : Specify the layout or template to use to render the page. If you don’t
-   specify a layout, then the `layout-html4` layout will be used by default.
-
-`xhtml`
- : Specify this key if you want to force a page to use the `layout-xhtml`
-   layout instead of an html4 layout. You should never do this, though, except
-   for the main, top-level landing page. Apple’s help specifications require
-   HTML4.
-
-`order`
- : Set the sorting/display order for a particular file within its group.
-
-`navigate`
- : When used in a group’s parent (i.e., the `index.html` for the group) then
-   members of the group will display the page navigator buttons.
-
-`navigator`
- : When set to `false`, overrides the display of the page navigator for this
-   page only.
-
-`target`
- : Indicates which [targets][targets] and [features][features] this page is
-   applicable for.
-
-`exclude`
- : Indicates which [targets][targets] and [features][features] this page should
-   be hidden from.