middlemac 2.0.0 → 3.1.2

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 %>_.