middlemac 2.0.0 → 3.0.0

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

@@ -0,0 +1,4 @@
+---
+title:  Compose a Middlemac Project
+layout: layout-blank
+---

data/documentation_project/Contents/Resources/{Base.lproj/050_structure → en.lproj/040_compose_project}/not_free.html.md.erb

@@ -1,18 +1,13 @@
 ---
-title:     Invisible On Free
-blurb:     This page is not available for target `:free`, as a demonstration of
-           the use of targets.
-layout:    template-logo-small
-navigator: false
+title:   Invisible On Free
+blurb:   This page is not available for target `:free`, as a demonstration 
+         of the use of targets.
 exclude:
  - :free
 ---
 <%= md_links %>
 <%= md_images %>
 
-<%= current_page.data.title %>
-==============================
-
 <%= current_page.data.blurb %>
 
 
@@ -28,8 +23,6 @@ build output.
 title:     Invisible On Free
 blurb:     This page is not available for target `:free`, as a demonstration of
            the use of targets.
-layout:    template-logo-small
-navigator: false
 exclude:
  - :free
 ---
@@ -40,4 +33,4 @@ included in the target list will be included in _Middlemac_ navigation.
 Using `exclude` overrides `target`.
 
 Note that `target` and `exclude` are lists; you can specify multiple targets and
-[features][features_overview] (which also can be used).
+features (which also can be used).

data/documentation_project/Contents/Resources/{Base.lproj/050_structure → en.lproj/040_compose_project}/not_pro.html.md.erb

@@ -1,18 +1,13 @@
 ---
-title:     Invisible On Pro
-blurb:     This page is not available for target `:pro`, as a demonstration of
-           the use of targets.
-layout:    template-logo-small
-navigator: false
+title:   Invisible On Pro
+blurb:   This page is not available for target `:pro`, as a demonstration of
+         the use of targets.
 exclude:
  - :pro
 ---
 <%= md_links %>
 <%= md_images %>
 
-<%= current_page.data.title %>
-==============================
-
 <%= current_page.data.blurb %>
 
 
@@ -28,8 +23,6 @@ build output.
 title:     Invisible On Pro
 blurb:     This page is not available for target `:pro`, as a demonstration of
            the use of targets.
-layout:    template-logo-small
-navigator: false
 exclude:
  - :pro
 ---
@@ -40,4 +33,4 @@ included in the target list will be included in _Middlemac_ navigation.
 Using `exclude` overrides `target`.
 
 Note that `target` and `exclude` are lists; you can specify multiple targets and
-[features][features_overview] (which also can be used).
+features (which also can be used).

data/documentation_project/Contents/Resources/en.lproj/100_reference/010_apple_help_books/010_dissect_help_book.html.md.erb

@@ -0,0 +1,295 @@
+---
+title:  Apple Help Book Structure
+blurb:  What is an Apple Help Book composed from, anyway? Why are they so hard
+        to write, and why are they such a mystery?
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+Apple’s [Authoring Apple Help][1] documentation, while still accurate, is
+horribly outdated and a little bit misleading at times. There are countless
+Stack Overflow and Apple Support forum posts requesting help for developing
+Help Books, and several blog posts with instructions on how to build a working
+Help Book (and some of this advice doesn’t always work).
+
+In essence, though, Help Books are just websites put into Apple’s bundle
+format, and registered with macOS via a Cocoa application’s `Info.plist` file
+and matching Help Book bundle `Info.plist` file. Help Books also have a help
+index file so that your Help Book can be searched (even when not running your
+application).
+
+In this topic, we’ll examine some of these inconsistencies, and look at the
+minimum requirements to build a valid Apple Help Book.
+
+
+Inconsistencies
+---------------
+
+Inconsistencies in Apple’s documentation make it burdensome to create Apple
+Help Books. For example, this [Authoring Help Pages][1] paragraph states:
+
+> After you have identified the subjects covered in your help book, you need
+  to create HTML files for your help pages. To ensure that your help displays
+  properly in Help Viewer, _your help files should comply with the HTML 4.01
+  specification_.
+  
+And then:
+  
+> _Your main file—which contains the AppleTitle meta tag—should conform to 
+  the XHTML 1.0 specification_.
+  
+Later:
+
+> Most of the metadata recognized by Help Viewer is optional. However, you 
+  must include the AppleTitle meta tag on one page in the root of your help
+  book for Help Viewer to properly identify and display your help book.
+
+These are nonsense! Apple’s own Help Files have been written in HTML5
+since at least macOS 10.10, and none of them contain some mystical 
+`AppleTitle` meta tag.
+
+Others have tried to demystify the creation of Help Books, too, but they tend to
+muddy the waters. Without embarrassing anyone, a highly-ranked blog article
+states:
+
+> The second thing to note is that in spite of the documentation implying that
+  you can use your help bundle identifier to refer to your help bundle (which
+  would, admittedly, make sense), you can’t. You need to use the `HPDBookTitle`
+  value. 
+
+The `HPDBookTitle` doesn’t work. Or perhaps it did before macOS 10.10, but on
+all of my test systems going back to 10.10, the use of the Help Book’s
+`CFBundleIdentifier` is required to be referenced in your application’s 
+`Info.plist` file.
+
+The same article goes on to state:
+
+> The third thing relates to `HPDBookAccessPath`. The file referred to there
+  must be a valid XHTML file. In particular, it cannot be an HTML5 document —
+  that will simply not work, and the error messages you get on the system
+  console are completely uninformative.
+
+Again, this might have been true in the old days (_Middlemac_ 2.0 and earlier
+made pains to follow this rule), but this hasn’t been the case since at least
+macOS 10.10. Apple’s own help ships with HTML5 files at the `HPDAccessPath`.
+
+
+Working Help Books, Made Simple
+-------------------------------
+
+The make a working Help Book for any macOS Cocoa application, you need simply
+three things:
+
+<% helpbook_task "help_archi_1", "A valid macOS bundle containing your help contents…" do %>
+
+
+Bundles in macOS nearly always have the same structure:
+
+~~~
+Contents/
+  Info.plist
+  {stuff}    
+~~~
+
+An application or extension might look like this:
+
+~~~
+Contents/
+  Info.plist
+  MacOS/
+  Resources/   
+~~~
+
+A Help Bundle should look like similar to an application bundle, but given
+that it has no executable code (in the `MacOS` directory), it will contain
+only resources:
+
+~~~
+Contents/
+  Info.plist
+  Resources/
+    index.html
+~~~
+
+If we put an HTML file into `Resources/` and configure the `.plist` files
+correctly, this will produce a working Help Book. However, bundles can be
+localized, and support for localized resources is built into the operating
+system. Thus, a help bundle should look like this:
+
+~~~
+Contents/
+  Info.plist
+  Resources/
+    en.lproj/
+    {non-localized resources}
+~~~
+
+These “non-localized resources” can be loose files or directories, having any
+name allowed by the operating system.
+
+A Help Book consisting of multiple languages might look like this:
+
+~~~
+Contents/
+  Info.plist
+  Resources/
+    en.lproj/
+    es.lproj/
+    ru.lrpoj/
+    logo.png
+    shared_resources/
+~~~
+
+Now all we have to do is ensure that our valid bundle is truly valid is ensure
+that its `Info.plist` identifies it as a proper bundle, and points the Apple
+help system toward the correct resources.
+
+In contrary to [Apple’s documentation][1], this table only shows keys that are
+used and relevant today:
+
+| Raw Key Name                  | Sample Value (bold values must be as shown) | Comments
+|-------------------------------|---------------------------------------------|---------
+| CFBundleDevelopmentRegion     | en-us                                       | Note the use of a hyphen, whereas Apple demonstrates an underscore.
+| CFBundleIdentifier            | com.balthisar.middlemac.free.help           | To be used in your application’a `CFBundleHelpBookName`.
+| CFBundleInfoDictionaryVersion | **6.0**                                     | Required as is.
+| CFBundleName                  | Middlemac                                   | This name can be localized.
+| CFBundlePackageType           | **BNDL**                                    | Required as is.
+| CFBundleShortVersionString    | 3.0.0                                       | Short version of your version string.
+| CFBundleSignature             | **hbwr**                                    | Required as is.
+| CFBundleVersion               | 3.0.0                                       | Long version of your version string.
+| HPDBookAccessPath             | index.html                                  | The file that should be loaded when Apple Help Viewer starts.
+| HPDBookIconPath               | SharedGlobalArt/free-icon_32x32@2x.png      | Icon used to represent the Help Book, especially during system-wide searches.
+| HPDBookIndexPath              | Middlemac.helpindex                         | The name of your index file, relative to your `.lproj` directory.
+| HPDBookTitle                  | Middlemac Help                              | The title of the Help Book, and it can be localized.
+| HPDBookType                   | **3**                                       | Required as is.
+
+
+<% end %>
+<% helpbook_task "help_archi_2", "Located in the Resources/ directory of your application, and…" do %>
+
+
+The requirement is satisfied by putting the help bundle into your application
+here:
+
+~~~
+YourApp.app/
+  Contents/
+    Resources/
+      YourHelpFile.help/
+~~~
+
+Do _not_ put a help bundle into your localized resources folder in your
+application, even if it’s a `Base.lproj`. It may look like it works for
+your development language, but it will break on other Macs operating with
+different locales:
+
+~~~
+YourApp.app/
+  Contents/
+    Resources/
+      Base.lproj/
+        YourHelpFile.help/   <- don't do this!
+      en.lproj/
+        YourHelpFile.help/   <- don't do this!
+      YourHelpFile.help/     <- this is correct
+        Contents/
+          Resources/
+            en.lproj/
+            es.lproj/
+            ru.lrpoj/
+~~~
+
+To ensure that your Help Book ends up in the correct directory when you build
+your application, make sure you import it to your project as a
+_folder reference_; if it’s shown in the organizer with a disclosure triangle
+that lets you browse the contents, then you’ve done it wrong, and it will not
+copy properly during your “Copy Resources” build phase!
+
+![Import as folder reference][apple_help_books_folder_reference]
+
+Additionally, make sure that the Help Book has the correct target membership,
+in order to ensure that it will be copied during the “Copy Resources” build
+phase, _and_ do _not_ localize this file. It’s already localized internally
+by virtue of being a localized bundle.
+
+![Correct project membership][apple_help_books_project_membership]
+
+
+<% end %>
+<% helpbook_task "help_archi_3", "Two correct keys in your application’s Info.plist" do %>
+
+
+This last point is satisfied by ensuring that your application’s `Info.plist`
+points to the correct help bundle and knows the bundle ID of the bundle.
+
+`CFBundleHelpBookFolder`
+
+  : What’s the name of your help bundle in the file system? In the examples
+    above, we’ve been showing `YourHelpFile.help`. This is the only value
+    you need to specify in your application. No paths are needed; Cocoa knows
+    how to find resources, such as your help bundle, within its own bundle.
+  
+`CFBundleHelpBookName`
+
+  : What’s the `CFBundleIdentifier` of the bundle that you want to use for
+    your application’s help? This is specified in your help bundle’s
+    `Info.plist` file.
+
+<% end %>
+
+
+Special Features
+----------------
+
+Although principally a glorified web browser, Apple Help Viewer and Help Books
+do provide a couple of advantages not enjoyed by standard browser-based systems:
+
+- Anchor-based navigation using Apple’s `NSHelpManager` methods, as well as
+  special anchor `href` values, if desired.
+- The ability to search your Help Book within Apple Help Viewer.
+- The ability for your application’s Help Book to be searched and display
+  results while searching from within another Help Book.
+  
+This is all enabled by including a `.helpindex` file within your Help Book,
+and can be supplemented by including an `ExactMatch.plist` file to aid in
+searching.
+
+The fact is, Apple's `helpd` (Help Data) daemon will create this help index for
+you automatically if you fail to include one, and it will be kept for handy
+reference in its caches. However, you have much more fine-grained control over
+the indexing process if you use `hiutil` yourself in order to create these
+indexes to your own specifications.
+{: .note .callout}
+
+The help index contains, among other things, a list of all of the files and
+anchors in your Help Book and some word frequency lists that provided weighted
+results for searching. In addition, this index contains summary information for
+each of the pages, and some additional metadata. You can use `hiutil` to
+examine most of the contents of a help index, and use a tool such as
+[`hiextract`][2] to examine the word frequency lists.
+
+If you’re using _Middlemac_ on a macOS computer, then `hiutil` will
+be handled automatically for you, and `ExactMatch.plist` will be created for
+you, too.
+{: .tip .callout}
+
+
+
+Style and Functionality
+-----------------------
+
+While these few, simple requirements produce a working Help Book, they won’t
+produce a very pretty or usable one. Like any complex or simple web site,
+everything else is typically up to you. Navigation, styles, JavaScripts,
+correct `<HEAD>` information, and so on. Apple Help Viewer is simply a
+browser with a couple of added features, after all.
+
+And certainly you’re interested in using a tool like _Middlemac_ so that you
+can avoid all of that hassle. If you’re interested in how modern Apple Help
+Books work, though, continue on to the [next section][dissect_modern_help].
+
+
+ [1]: https://developer.apple.com/library/content/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html
+ [2]: https://github.com/balthisar/hiextract

data/documentation_project/Contents/Resources/en.lproj/100_reference/010_apple_help_books/020_dissect_modern_help.html.md.erb

@@ -0,0 +1,246 @@
+---
+title:  Modern Apple Help Books
+blurb:  Apple doesn’t showcase it, but it provides the tools to build their
+        Help Books with every shipping version of macOS.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+Since macOS 10.10 (“Yosemite”), Apple has been using a JavaScript-based
+Help Book engine named “Eagle,” and has been gradually updating most of their
+application and macOS documentation to take advantage of it. You can find
+all of this engine located in `/Library/Documentation/Resources/Eagle/` on
+macOS 10.10 through macOS 10.13 (macOS 10.14 doesn’t seem to include it).
+
+This engine provides a common look, feel, and experience across all of Apple’s
+Help Books, and by taking advantage of Eagle, _Middlemac_ ensures that your
+own Help Books enjoy this same consistency.
+
+
+“Modern” Help
+-----------
+
+Modern Help Books are the Help Books you’ve seen on macOS Help, built-in
+application Help, and Apple software Help since macOS 10.10 was released. The
+term “modern” is only as valid as the term “next gen,” in that something newer
+always comes along.
+
+So it is with Apple, in that starting with macOS 10.13, some of the built in
+applications have been shipping with Help Books using their new “Harrier”
+Help Book development system. It’s likely that over time, shipping applications
+will be migrated toward this new look, too.
+
+_Middlemac_ will try to keep up with Apple Help technologies, and in the 
+meantime, version 3.0 produces Help Books meeting the same standards as current,
+shipping Apple Products.
+
+
+Modern Help Universal Deployment
+--------------------------------
+
+With Eagle, Apple has strived towards universal deployment of its Help Books,
+meaning that they are just as functional when served to a browser as they are
+when used in Apple Help Viewer. This also means that Apple strives to provide
+visual and functional consistency from Help Book to Help Book. This means that
+when served to a browser:
+
+- You have the same navigation menu that you would have in Apple Help Viewer.
+- You have the ability to search your Help Book within the browser environment,
+  just as you do within Apple Help Viewer.
+- The pages have the same appearance and behavior in the browser as they do in
+  Apple Help Viewer.
+- Certain features are automatic if the right conditions exist for them to
+  exist, such as Copyright Pages, navigation, Copyright Notices, and so on.
+- A single Help Book can provide its content in multiple languages, just as it
+  would in the browser.
+
+In short, an Eagle Help Book (or a Help Book produced by _Middlemac_) will work
+equally well when used in Apple Help Viewer as it does in a browser. And I mean
+the same Help Book; there’s no need to generate separate “Help Viewer” and
+“browser” versions.
+
+
+Eagle’s Heart
+-------------
+
+A modern Help Book is operated completely from a single HTML file within the
+Help Book. The `Resources/index.html` file uses JavaScript to load the content
+from your HTML files (in any localized directory) and presents them to the
+viewer. It also handles loading of all styles, operates special features such
+as tasks, performs searching, generates the navigation sidebar, and enables
+Copyright Pages, loads asides, and so on. 
+
+All of these functions fall into three broad categories:
+
+<% helpbook_task "help_modern_1", "Navigation" do %>
+
+“Navigation” encompasses things such a providing a nested menu structure for the
+Table of Contents, and enabling links to Copyright pages, if provided. The
+structure, depth, and relationships between Help Book pages which is required to
+provide this functionality is defined in the `navigation.json` file, which
+_Middlemac_ builds for you automatically based on your sitemap and the data that
+you provide in frontmatter.
+
+Using this Help Book’s `free` target `navigation.json` as an example (with much
+of the content stripped away for brevity), we can examine how Eagle constructs
+its navigation.
+
+| Key                                                | Sample Value (bold values static)   | Comments
+|----------------------------------------------------|-------------------------------------|----------
+| birdseed_version                                   | **5**                               | Probably an internal Apple framework version.
+| build_id                                           | "3.0.0"                             | Doesn’t affect Help Book.
+| build_date                                         | "2018.06.09-16:00:31"               | Doesn’t affect Help Book.
+| collect_feedback                                   | **false**                           | Probably refers to Apple’s "Was this page helpful?" feature. Unused by _Middlemac_.
+| copyright                                          | "topic-en.lproj/-acknowledgements"   | This is the `$topic_id` of the page to be used as the Copyright Page.
+| copyright_text                                     | "© 2018 Jim Derry."                 | Displayed on every page when viewed in browser, or when Help Viewer prints output.
+| css                                                | **""**                              | Unknown. Seems to have no effect on Help Book.
+| enable_tracking                                    | **false**                           | Probably an Apple tracking system. Unused by _Middlemac_.
+| framework                                          | "middlemac-3.0.0"                   | Probably an internal Apple framework reference.
+| icon                                               | "SharedGlobalArt/icon_32x32@2x.png" | Icon for the book. Unsure why this is different than the .plist’s HPDBookIconPath.
+| landing                                            | "topic-Resources-en.lproj/"          | This is the `$topic_id` of the page to be used as the Landing Page.
+| locale                                             | "en"                                | The locale of the JSON file.
+| platform                                           | **"mac"**                           | Probably because iTunes also supports Windows.
+| printable_page                                     | **""**                              | Unknown.
+| product                                            | "Middlemac"                         | Seems to be inactive.
+| quick_links                                        | **[]**                              | Unknown.
+| sections                                           | [Array]                             | Sections appear in the TOC with their given childen. Child order is important, but order of the sections in this array is not.
+| &nbsp;&nbsp;$section_id                            | "section-compose_project-helpers"   | Specify a $section_id for this section. Used to build the TOC.
+| &nbsp;&nbsp;&nbsp;&nbsp;name                       | "Helpers"                           | The name of the section as it will appear in the TOC.
+| &nbsp;&nbsp;&nbsp;&nbsp;children                   | [Array]                             | An array of `$topic_id` indicating the pages that constitute this section.
+| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$topic_id      | "topic-helpers-helpers"             | An element of the `$topic_id` list.
+| show_previous_next                                 | false                               | When set to true, enables previous and next page navigators.
+| source_schema                                      | **"apd-schema"**                    | Unknown.
+| title                                              | "Middlemac Help"                    | This will be used as the `<title>` of your landing page, reguardless of the `<title>` you set in the HTML document. Of course, it’s also used in the Help Viewer title bar and browser title banner.
+| toc                                                | [Array]                             | This array of `$topic_id` or `$section_id` defines the table of contents used in the sidebar.
+| &nbsp;&nbsp;$topic_id -or- $section_id             | "section-en.lproj/-reference"        | An element of the list.
+| topics                                             | [Array]                             | An array of `$topic_id`, as defined below.
+| &nbsp;&nbsp;$topic_id                              | "topic-asides-aside_description"    | Specify a `$topic_id` to represent a particular page.
+| &nbsp;&nbsp;&nbsp;&nbsp;name                       | "What is an aside?"                 | The name of the topic. Will be used in the TOC.
+| &nbsp;&nbsp;&nbsp;&nbsp;summary                    | "A short article describing…"       | The summary is shown in search results.
+| &nbsp;&nbsp;&nbsp;&nbsp;href                       | "asides/aside_description.html"     | The lproj-relative path of the file.
+| &nbsp;&nbsp;&nbsp;&nbsp;categories                 | [Array]                             | An array of `$category_name`; these will be applied as body classes when the document it loaded. Some categories have special purposes in Eagle, such a `aside` and `copyright`.
+| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$category_name | "aside"                             | An element of the list.
+| urls                                               | **{}**                              | Unknown.
+| version                                            | "3.0.0"                             | Probably the application version, but it’s not known where this is used in the Help Book.
+
+
+_Middlemac_ build this file for you automatically based on the `.lproj/` language,
+settings from your `config.rb` file, and page data including the overall site
+map as well as data from the pages’ frontmatter. If you feel like
+reverse-engineering Apple’s feedback and tracking mechanisms, then feel free
+to modify this file to your liking.
+
+
+<% end %>
+<% helpbook_task "help_modern_2", "Search" do %>
+
+When viewing a Help Book in Apple Help Viewer, the `.helpindex` file generated
+by `hiutil` is used. However this is a file produced by the old, deprecated
+`NSArchiver`, and is a binary format that JavaScript cannot parse or
+understand. Thus Eagle Help Books when viewed in the web browser refer to a
+different file in order to provide search results: `searchTree.json`.
+
+This file is a trie in JSON format, which is a very efficient structure for
+searching words.
+
+Apple _probably_ builds this file from the word frequency information gathered
+by `hiutil`, but because unarchiving the `.helpindex` requires the use of
+private Apple API’s, _Middlemac_ will generate this file from the contents of
+your pages itself. Thus there's the possibility that if Apple were to generate
+this file for you, there might be differences; however Apple is unlikely to
+perform this service for you.
+
+Words encountered as frontmatter `keywords` are given extra weight, and words
+encountered as frontmatter `exactmatch` are given a _lot_ of extra weight. The
+same list of stopwords (words ignored for searches) is used to build this file
+as to build the `.helpindex`.
+
+##### Search Redirects
+
+Both Apple’s `hiutil` and _Middlemac_’s `searchTree.json` indexer index
+individual pages. Search results link to those individual pages. However, recall
+that an Eagle Help Book never displays those pages directly; every page is
+loaded via JSON by the main `index.html` file, which is the only real “page”
+ever displayed.
+
+This means that when a page is listed as a search result, the link will
+attempt to deliver that specific page to you. That specific page is not
+`index.html`, and so there’s no loaded JavaScript or CSS. That’s not a good
+experience for users, and so _Middlemac_ addresses this issue by adding
+JavaScript to each of these individual pages which directs to the main
+`index.html`, including the correct URL query to load the desired page. By
+placing this redirect in the `<head>`, it’s usually fast enough to prevent
+loading the entire page into Apple Help Viewer, thus avoiding temporarily
+displaying unstyled pages.
+
+Apple’s JavaScript, of course, strips everything from the `<head>`, so when
+the file is ultimately AJAX-loaded into `index.html`, no circular refresh
+loops occur.
+
+
+<% end %>
+<% helpbook_task "help_modern_3", "Localization" do %>
+
+Eagle also provides localization features for browser-served pages that are
+handled automatically by Apple Help Viewer. For example, Apple Help Viewer
+knows that the OS is configured for Spanish, and will use the `Spanish.lproj/`
+or `es.lproj/` directory contents automatically. Apple Help Viewer will also
+fall back to `Base.lproj/` or `en.lproj/` if the localized directories are not
+part of the Help Book.
+
+Browsers, while they can provide the locale, aren’t nearly so smart about
+selecting paths properly, so Apple’s JavaScripts assume this role. The only
+caveat is that these JavaScripts don’t honor any type of `Base.lproj/`
+directory and `CFBundleDevelopmentRegion`. And because the browser is unable
+to select a proper `.lproj/` on its own, we have to provide some data that
+allows the JavaScript to select the proper folder.
+
+Additionally, because the locale determined by the browser is potentially not
+accurate for a variety of reasons, Apple’s JavaScripts present a language
+switcher on your Help Book’s landing page, if your project is multilingual.
+
+Thus, to make multilingual Help Books work in Apple Help Viewer, simply place a
+localized `.lproj/` for each language you support into the Help Book. To make
+multilingual Help Books work in the browser, though, we need to specify some
+additional metadata files: `Resources/locale-info.json` and
+`*.lproj/locale-list.json`.
+
+Of course, _Middlemac_ handles these two files for you, as long as you use the
+correct `.lproj/` directory name per
+`SharedGlobalAssets/_data/locale-list.json`, which is Apple’s standard locale
+list file. The [Directory Conventions][directory_conventions] topic shows which
+locales are supported out of the box.
+{: .tip .callout}
+
+Each `.lproj/` directory must contain a `locale-info.json`, which simply
+indicates some basic data about the locale present in that particular directory.
+
+More importantly, the site root must contain a `locale-list.json` which 
+indicates all of the locales in the present Help Book, and, importantly, which
+`.lproj/` directory the contents can be found.
+
+The `_data/locale-list.json` serves as a master list of all of the possible
+localizations. It may not be all inclusive, so feel free to add additional
+localizations if not already covered by this file. The 
+`Resources/locale-list.json`, generated by _Middlemac_, contains _only_ the
+locales used in the current project.
+{: .tip .callout}
+
+
+<% end %>
+
+
+## Middlemac and Eagle
+
+_Middlemac_ builds Eagle Help Books. Apple’s JavaScript has been modified
+slightly to provide support for non-flat file structures, and support for
+`<image>` tag `srcset` attributes.
+
+Some of Apple’s CSS has been overridden with more specificity to provide
+improvements to things such as `<dl>` that Apple doesn’t use often, but are
+critical for certain workflows.
+
+When you use _Middlemac_, you are building a real, true, Eagle Help Book, and
+not a copy, clone, or simulation.

data/documentation_project/Contents/Resources/en.lproj/100_reference/010_apple_help_books/index.html.md.erb

@@ -0,0 +1,4 @@
+---
+title:  Apple Help Books
+layout: layout-blank
+---