middlemac 2.0.0

data/documentation_project/Contents/Resources/Base.lproj/030_skills_refresher/index.html.md.erb

@@ -0,0 +1,35 @@
+---
+title:  Skills Refresher
+blurb:  If you don’t know a thing about Ruby or <em>Middleman</em>, don’t
+        worry; there’s enough information in this section to get you started.
+layout: template-logo-large
+navigate: true
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+_Middlemac_ uses tools you may already know. Or not.
+
+- [Markdown](http://kramdown.gettalong.org/) is the text-based, human-readable,
+  easy to use format that will make writing your documentation a real pleasure.
+  This file is written using Markdown.
+- [_Middleman_](http://middlemanapp.com) is a static HTML site generator, and is
+  the heart of _Middlemac_’s abilities, as well as an inspiration for the name.
+- [Ruby](https://www.ruby-lang.org/en/) is the language that _Middlemac_,
+  _Middleman_, and many of the others tools are written with. You do not have
+  to learn Ruby to take advantage of _Middlemac_, although some ability to work
+  with it will be invaluable to you.
+- HTML is the markup language that Apple requires for help books. But
+  _Middlemac_ promises to make things easy for you, and so…
+
+
+* * *
+
+<%= nav_legitimate_children %>
+
+* * *

data/documentation_project/Contents/Resources/Base.lproj/040_setup/index.html.md.erb

@@ -0,0 +1,88 @@
+---
+title:  "Workflow: Set up your Help Project"
+blurb:  Setting up your help project is the first step in <em>Middlemac</em>’s
+        workflow. Understand how to do this setup in this article.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= 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 HelpBook 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 several components, its key configuration
+is performed in several 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 Mac OS X knows which help bundle belongs
+    to which application. If they are not unique, Mac OS X _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 `shared/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`, and `ProductURI`
+  : 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.
+
+
+

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

@@ -0,0 +1,176 @@
+---
+title:  Directories, filenames, images, and paths
+blurb:  Learn about proper structure for your directory hierarchy, filenames,
+        and image locations, and discover some best practices related to paths.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+Directory conventions
+---------------------
+
+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 `Base.lproj` directory, 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. Also don’t forget to have a look
+later at [Apple Help setup][apple_help_setup].
+
+Note the many of the file names below are written with destination, _built_
+file extensions, and not the complete extension as it might appear in the source
+directory. For example, the top level source file for `index.html` could have
+the name `index.html.md.erb` or `index.html.haml`, as you see fit.
+{:.note}
+
+`Contents/`
+
+ : Contains everything in your help project that will be compiled into or
+   contribute to the final `.help` project.
+   
+`Contents/Info.plist`
+
+ : The `Info.plist` file is the file that _Middlemac_ will process into the
+   final `Info.plist` that your Mac OS X application needs in order to work with
+   your help book. For a basic project you shouldn’t have to modify anything in
+   this file, but if you want or need to have other key-value pairs in the final
+   `Info.plist`, then add them here. 
+   
+`Contents/Resources/shared`
+
+ : This directory contains assets that are common between all of your different
+   help language projects. Although _Middlemac_ is not a multilingual solution
+   _per se_, this is maintained because you can simply have a different
+   _Middlemac_ project per language, and then merge in the other language
+   `.lproj` directories into your final help book, sharing assets in this
+   directory.
+   
+`Contents/Resources/Base.lproj`
+
+ : This directory serves as your base [group][groups] and contains all of your
+   help book’s content as well as pieces that will contribute to your content
+   (such as templates).
+   
+   Any other files that result in `.html` in this directory level, except for
+   `index.html` constitute part of the `Base.lproj` group. At this level you
+   should start adding directories to contain your other groups.
+   
+`Contents/Resources/Base.lproj/index.html`
+
+ : This is the top level file in your entire project, and is also the Apple
+   Help System main landing page.
+ 
+`Contents/Resources/Base.lproj/InfoPlist.strings`
+
+ : The `InfoPlist.strings` file is the file that _Middlemac_ will process into
+   the final `InfoPlist.strings`, which contains the localized version of your
+   applications’ human-readable `Info.plist` data (specifically, `CFBundleName`
+   and `HPDBookTitle`).
+   
+   _Middlemac_ is a multi-target solution for a single language, and not a
+   multi-language solution _per se_, and so the `CFBundleName` in your
+   `config.rb` will be used, whether it’s English or German or Chinese. This is
+   one of the strengths of `Base.lproj`: it’s agnostic.
+
+`Contents/Resources/Base.lproj/assets/`
+
+ : This directory contains all of the non-content assets used in your help book
+   such as stylesheets, images, etc., as well as data source files, templates,
+   layouts and partials.
+   
+   You will notice that some of these classes of items are in unconventional
+   locations compared to a default _Middleman_ project. This was done on your
+   behalf for the sake of portability and for having a non-distracting directory
+   environment.
+   
+   `_data/`
+    : This directory contains data files that you can use to supply data for
+      [using local data][using_local_data]. This directory will not be
+      output in the final build.
+    
+   `_layouts/`
+    : All layouts and templates should go here. This directory will not be
+      output in the final build.
+      
+   `images/`
+    : All images should go here. _Middleman_ will find them automatically if
+      you use the helpers.
+ 
+   `javascripts/`
+    : Javascripts, if any, should go here. You should prefix each script with
+      an underscore so that they will _not_ be included. The already-present
+      file `all.js` will bundle them into a single file -- `all.js` -- and
+      _that’s_ the file loaded by the _Middlemac_ layouts.
+
+   `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.
+
+   `stylesheets/`
+    : Your `.css` and `.scss` files should go here. Read more about _Middlemac_
+      CSS organization [here][css].
+
+ 
+Images
+------
+
+Most images, of course, should go into the `images` directory of the `assets`
+directory.
+
+However _Middlemac_ also depends on some magic images being placed in
+`Contents/Resources/shared/`:
+
+`icon_32x32.png` and `icon_32x32@2x.png`
+
+ : These files are your help file icon at 32 × 32 pixels and @2x, and will be
+   used by the included templates 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` and `icon_256x256@2x.png`
+
+ : The same as above, but at 256 × 256 pixels and @2x.
+ 
+You will also notice that there are target-specific versions of these images
+located here, too. This documentation project takes advantage of them, and you
+can do the same. Note that the non-target specific versions are still required
+so that the Help Viewer knows to find them!
+
+
+Images Organization
+-------------------
+
+When your content images are located in the `assets/images/` directory,
+_Middleman_’s [helpers][middleman_helpers] can find them automatically
+without any worry about relative or absolute file paths.
+
+
+“Absolute” Paths
+----------------
+
+When using _Middleman_’s [helpers][middleman_helpers], absolute paths will be
+converted to relative paths during the build. Absolute paths are relative to the
+`Contents` directory and _not_ the filesystem root.
+
+In general it’s _not_ recommended to use absolute paths unless you need assets
+outside of _Middlemac_’s configuration. _Middleman_ will automatically build the
+correct path using only the asset name when you use its helpers, if the assets
+are in the correct directories (e.g., images in `images/`).
+
+However you will use absolute paths to refer to items in the `shared/` directory
+since this it outside of _Middlemac_’s normal search scope. The view templates
+use this approach, for example.

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

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

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

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