middlemac 2.0.0 → 3.0.0

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/030_directory_conventions.html.md.erb

@@ -0,0 +1,206 @@
+---
+title:  Directory Conventions
+blurb:  Learn about proper structure for your directory hierarchy, filenames,
+        and image locations, and discover some best practices related to 
+        paths.
+---
+<%= md_links %>
+<%= md_images %>
+
+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 `en.lproj` directory (or the directory of the
+locale for which you’re developing), 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 so that you can determine where to put your files.
+Also don’t forget to have a look later at the 
+[Directory and File Reference][directory_reference] topic for additional
+information about these directories and the specific files within them.
+
+`Contents/`
+
+  : Contains everything in your help project that will be compiled into or
+    contribute to the final `.help` project.
+   
+`Contents/Resources/SharedGlobalAssets/`
+
+  : This directory contains assets that are common between all of your 
+    different help language projects, as well as assets that _Middlemac_
+    requires by convention, such as Apple’s CSS and JavaScripts, certain image
+    files, data files, layouts, and so on. Full reference documentation is
+    available in the [Directory Layout][directory_reference] topic.
+   
+   
+`Contents/Resources/SharedGlobalAssets/_data/`
+
+  : This directory contains data files that you can use to supply data for
+    [using local data][local_data]. This directory will not be output in the
+    final build.
+
+`Contents/Resources/SharedGlobalAssets/_layouts/`
+
+  : All layouts exist here. This directory will not be output in the final
+    build. In general, you should have no reason to add additional layouts
+    when building current Apple Help Books.
+
+`Contents/Resources/SharedGlobalAssets/_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.
+
+`Contents/Resources/SharedGlobalAssets/convention/`
+
+  : Images that the Apple Help Book and _Middlemac_ require by convention go
+    here. This is separate from the `images/` directory simply to make
+    directory management simpler by avoiding the mixing of required and
+    non-required files. _Middleman_ helpers will find images that are in
+    this location automatically, if needed.
+  
+  
+`Contents/Resources/SharedGlobalAssets/css/`
+
+  : Your `.css` and `.scss` files, if any, should go here. They will not be
+    included automatically in your project unless you modify the main 
+    `index.html` file to include them.
+  
+
+`Contents/Resources/SharedGlobalAssets/fonts/`
+
+  : Any fonts that you wish to include should go here. In general if you are
+    building an Apple Help Book, additional fonts should not be needed.
+  
+
+`Contents/Resources/SharedGlobalAssets/images/`
+
+  : All images should go here. _Middleman_ will find them automatically if
+    you use the helpers.
+
+
+`Contents/Resources/SharedGlobalAssets/js/`
+
+  : Javascripts, if any, should go here. They will not be included
+    automatically in your project unless you modify the main `index.html`
+    file to include them.
+
+   
+`Contents/Resources/en.lproj`
+
+  : This directory serves as your base [group][groups] for the English version
+    of your Help Book, and it contains all of your Help Book’s content,
+    including locale-specific versions of your resources.
+   
+    Any other files that result in `.html` in this directory level, except for
+    `index.html` constitute part of the `en.lproj` group. At this level you
+    should start adding directories to contain your other groups.
+   
+    Certainly, you’re not required to develop in English, and _Middlemac_
+    supports multiple languages simultaneously. See **Locale Directories**,
+    below.
+   
+   
+`Contents/Resources/en.lproj/assets/`
+
+ : This directory contains all of the localized assets used in your Help Book.
+   In order for _Middlemac_’s asset helpers such as `image_tag` and `partial`
+   to find localized resources, and subdirectories of `assets/` must mirror
+   the subdirectories of `SharedGlobalAssets/`, e.g., `assets/images/`.  
+
+
+`Contents/Resources/en.lproj/asides/`
+
+ : This optional directory can be used to house your `.html.md.erb` files that
+   you use for the Help Book _asides_ feature. Any asides in this directory
+   will have the correct layout applied to them automatically, meaning that
+   it won’t be necessary to specify `layout: layout-apple-modern-aside` in
+   these files’ frontmatter.
+{: .nontabular}
+
+
+Locale Directories
+------------------
+
+Throughout this documentation we assume the use of the English locale, with
+your localized files placed into `en.lproj`. Apple’s JavaScripts do not
+support the use of `Base.lproj` or development regions, and so development in
+other languages must take place in language specific directories, as defined
+in `SharedGlobalAssets/_data/locale-list.json`:
+
+| Name                  | ISO Name                | Directory
+|-----------------------|-------------------------|-----------------------
+<% data[:'locale-list'].each do |locale| %>
+| <%= locale[:name] %>  | <%= locale[:isoName] %> | <%= locale[:folder] %>
+<% end %>
+
+The file `SharedGlobalAssets/_data/locale-list.json` is as it was provided by
+Apple; you are free to modify this file if you wish to add a localization that
+is not already present.
+{: .tip .callout}
+
+To rename an existing locale in your project, simply rename the `.lproj` folder
+to one of the supported folder names above. Everything else will be taken care
+of automatically when you build your project.
+
+To create an additional locale, create a new folder in `Resources/` with one of
+the supported names from the table above, and then copy into this new folder
+the following files from the `en.lproj` folder:
+
+- `ExactMatch.plist.erb`
+- `InfoPlist.strings.erb`
+- `locale-info.json.erb`
+- `navigation.json.erb`
+- `searchTree.json.erb`
+
+
+Images
+------
+
+Most images, of course, should go into the `images` directory of your locale’s
+`assets` folder or `SharedGlobalAssets/images`.
+
+However _Middlemac_ also depends on some magic images being placed in
+`SharedGlobalAssets/convention/`:
+
+`icon_32x32.png`
+`icon_32x32@2x.png`
+
+ : These files are your help file icon at 32 × 32 pixels and @2x, and will be
+   used by the included layouts 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`
+`icon_256x256@2x.png`
+
+ : The same as above, but at 256 × 256 pixels and @2x.
+ 
+`icon-webclip-*.png`
+
+ : These assets are used automatically by Apple Help when serving help content
+   to a browser, typically on a mobile device.
+ 
+
+### Images Organization
+
+When your content images are located in the `SharedGlobalAssets/images/`
+directory or your `en.lproj/assets/images/` directory (or directory as
+appropriate to your locale), then _Middleman_’s [helpers][helpers] can find
+them automatically without any worry about relative or absolute file paths.
+
+Images specified without paths are sought first in your `language.lproj/`
+directory, then `SharedGlobalAssets/images/`, and then finally in
+`SharedGlobalAssets/convention`.
+
+### Image Paths
+
+Apple’s JavaScript rewrites image paths to make them load properly from
+the main `index.html` file. Thus, when _Middlemac_ builds your pages, images
+will be root-relative when you examine the source, but relative to the main
+`index.html` when examined in your browser’s debugging tools.

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

@@ -0,0 +1,96 @@
+---
+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. They define the 
+        sections that will appear in Apple Help Viewer.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= 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 to _define_ the group, and if you use any helpers, it acts
+as a virtual _parent_ to the group. As such, 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.
+
+A group’s `index.html` file serves as a metadata container only! Their
+[frontmatter][frontmatter] defines the _title_ of the group. You should assign
+the `layout: layout-blank` frontmatter in these files, as well. The only
+`index.html` file with any content can be your top-level `en.lproj/index.html`
+file, which is defined used as the landing page.
+
+Groups are named (not titled) based on their containing directory. The highest
+level group is `en.lproj` (or respective locale folder) 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:
+
+~~~
+en.lproj/
+  index.html
+  introduction.html
+  basics/
+    index.html
+    counters.html
+~~~
+
+This entire project consists of three pages: the top level `index.html`, and
+`introduction.html`, and `counters.html`. The file `counters.html` is assigned
+the group name “basics”, and the group title is defined in the
+`basics/index.html` file’s frontmatter.
+
+Although groups can be nested to arbitrary levels, Apple’s JavaScripts begins
+to flatten groups at a depth of three levels (plus the root, level 0). Groups
+nested deeper than this will still appear in the Help Book, but they will be
+flattened to the bottom level. 
+{: .tip .callout}
+
+Page order in groups
+--------------------
+
+Apple’s scripts will generate the table of contents according to the pages’
+and groups’ sort order. Additionally, if `show_previous_next` is enabled, the
+scripts will provide navigation links according to the same sort order.
+
+A group member’s sort/navigation order can be 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 features. 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.
+
+
+File naming
+-----------
+
+Note that section names cannot begin with the letters “help” because doing so
+causes Apple’s JavaScript to break.

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/050_targets_and_features.html.md.erb

@@ -0,0 +1,220 @@
+---
+title:  Targets and Features
+blurb:  A lesson on how to use include and exclude targets and features.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= 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 Book 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 review the `target_name?` example and the
+`target_feature?` examples below 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`
+[frontmatter][frontmatter] keys. When used, you have excellent control over
+whether entire pages are visible or not.
+
+
+Targets 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)
+
+
+Features 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.
+
+
+### How did this work?
+
+Features work nearly identically to 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 [frontmatter][frontmatter] `target` and `exclude` to include
+or exclude entire pages.
+
+
+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 macOS
+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`.
+
+

data/documentation_project/Contents/Resources/en.lproj/040_compose_project/060_frontmatter.html.md.erb

@@ -0,0 +1,98 @@
+---
+title:  Frontmatter and Keys
+blurb:  Explore how frontmatter can be used to configure your Help Book pages
+        and the Apple Help System.
+keywords:
+ - pluto
+ - mercury
+ - venus
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= 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:  Explore how frontmatter can be used to configure your Help Book pages
+        and the Apple Help System.
+keywords:
+ - pluto
+ - mercury
+ - venus
+~~~
+
+You can also specify your own frontmatter keys and values. 
+{: .tip .callout}
+
+Required Frontmatter
+--------------------
+
+Any file processed by _Middlemac_ may contain frontmatter. Files that generate
+HTML _require_ a minimum amount of frontmatter in order for them to work with
+Apple’s help system.
+
+`title`
+
+  : All HTML-producing files require the `title` key. Additionally, the
+    group `index.html` metadata files, although not intended to produce HTML,
+    require this key as well in order to give a title to the group.
+    
+`categories`
+
+  : The `landing` category is required for you main `index.html` landing page,
+    and `copyright` is required if you wish to have a copyright page. In
+    addition, you can add your own categories to this array as well, and they
+    will be available as a class to your document when loaded. Asides require
+    the `aside` category.
+    
+`blurb`
+
+  : HTML-producing pages require a blurb that can be used as a description
+    by the help indexers.
+    
+`order`
+
+  : If you wish the page to appear in the navigation features, and you’ve not
+    specified a page order in the file name, then an `order` key and value
+    must be present.
+{: .width25}
+
+
+Frontmatter Availability
+------------------------
+
+All frontmatter is
+available for use in your pages and templates via `current_page.data`, e.g.,
+`current_page.data.title`. For example, this page has the title 
+"<%= current_page.data.title %>" and the following keywords:
+<ul>
+<% current_page.data.keywords.each do |word| %>
+<%= "<li>#{word}</li>" %>
+<% end %>
+</ul>
+
+
+HTML and Markdown In Frontmatter
+--------------------------------
+Markdown is not always rendered in frontmatter, meaning that any use of
+Markdown is likely to result in \_formatting_ that looks \**wrong** when
+displayed. Additionally, the help indexer does not know how to deal with 
+Markdown.
+
+Thus, it’ best to use pure text for `title`, and use HTML for `blurb`, which
+the help indexer knows how to deal with.
+
+
+<% content_for :seeAlso do %>
+<%= link_to 'Frontmatter and Keys Reference', 'reference/frontmatter_reference.html' %>
+<% end %>

data/documentation_project/Contents/Resources/{Base.lproj/060_content/100_using_local_data.html.md.erb → en.lproj/040_compose_project/070_local_data.html.md.erb}

@@ -1,21 +1,34 @@
 ---
-title:  Using local data
+title:  Local Data
 blurb:  You can use a local file as a datasource to generate data-based pages
-        automatically. Learn how in this reference section.
-layout: template-logo-medium
+        automatically. Learn how in this section.
 ---
 <%= md_links %>
 <%= md_images %>
 
-
-<%= current_page.data.title %>
-==============================
-
 <%= current_page.data.blurb %>
 
 You can use data from external sources with _Middleman_ and _Middlemac_, too.
-In `assets/data/` a sample `globals.yml` contains some sample data in YAML
-format. Let’s see what it contains:
+These data files must be in YAML or JSON format, and be present in
+`SharedGlobalAssets/_data/`.
+
+This project contains sample in YAML format called `globals.yml`. Let’s see
+what it contains:
+
+~~~ yaml
+famous_writers:
+  -
+    author: Douglas Adams
+    sample_work: The Restaurant at the End of the Universe
+  -
+    author: Edward Bulwer-Lytton
+    sample_work: Paul Clifford
+  -
+    author: Daniel Defoe
+    sample_work: Robinson Crusoe
+~~~
+
+We can use this data to build something more interesting. Let’s try this:
 
 <% data.globals.famous_writers.each do |writer| %>
 - A sample work of <%= writer.author %> is _<%= writer.sample_work %>_.