middlemac 2.0.0 → 3.0.0

data/documentation_project/Contents/Resources/en.lproj/100_reference/030_backwards_compatibility.html.md.erb

@@ -0,0 +1,82 @@
+---
+title:  Backwards Compatibility
+blurb:  Notes about Backwards Compatibility with earlier versions of Middlemac.
+---
+<%= md_links %>
+<%= md_images %>
+
+_Middlemac_ version 3.0.0 is a **major** update. It’s an API-breaking update
+and projects using _Middlemac_ version 1._x_ or version 2._x_ will _not_ build
+without some changes to your project.
+
+This version of _Middlemac_ is a complete rewrite, and this was done in an
+effort to let Apple’s Help Book tools do their job and make modern Apple Help
+books. If you prefer full, manual control and custom styles that deviate from
+Apple’s look and feel, it’s suggested that you stick with _Middlemac_ version
+2.0.
+
+Middlemac 3.0 compared to older versions
+----------------------------------------
+
+_Middlemac_ versions prior to 3.0 were intended to provided tools giving you
+maximum control over page appearance while providing tools to allow automatic
+navigation within groups/sections. Although it shipped with layout templates
+and CSS to emulate the look of Apple’s Help Books for versions prior to
+macOS 10.10 (i.e., “Mavericks” and earlier), you were always encouraged to
+customize.
+
+_Middlemac_ 3.0, however, does away with _all of that_ in favor of building
+Apple Help Books that follow Apple’s own examples, standards, and practices.
+_Middlemac_ no longer builds Help Books that emulate a style, rather, Apple’s
+own tools provide the style and functionality. This necessarily represents a
+departure from the previous model of doing things.
+
+
+Project Upgrade Tips
+--------------------
+
+No automated method of upgrading a project is provided, but the steps for
+achieving an upgrade are fairly simple.
+
+The _vast_ majority of your source files will continue to work as they did in
+the past, although you may wish to reorganize them to align nicely with the way
+that modern Apple Help Books work. Here are some tips to help you migrate
+faster:
+
+- Begin by _reading_ this documentation and having a close look at the sample
+  project.
+
+- Take a look at the [Directory and File Reference][directory_reference],
+  to have a good understanding of what all of the new files do, and what their
+  functions are.
+
+- **It’s probably easiest to move your old source HTML files into the new sample
+  project.**
+
+- Some Markdown reference style links may have their references changed. Keep a
+  lookout for this.
+
+- There’s a new option called `show_debug` in the new `config.rb` file. Set this
+  to `true` to see all of the `md_links` and `md_images` values at the bottom
+  of each Help Book page. This setting will also highlight non-working Markdown
+  reference style links.
+
+- `Base.lproj` is not supported by modern Apple Help Books. Ensure that this
+  directory is named `en.lproj`, or some other locale name supported by Apple’s
+  Help Book system.
+  
+- Group landing pages are no longer supported, because modern Apple Help Books
+  do no use them. Instead, group landing pages are now used solely as metadata
+  containers to provide the name of the group. If you absolutely require a
+  landing page, you can create a topic page in the group.
+  
+- In Apple parlance, “groups” are now called “sections,” although in order to
+  preserve as much backwards compatibility as possible, functions relating to
+  groups, if you use them, refer to groups.
+
+- Most of the group navigation features and all of the helpers are no longer
+  included, nor are breadcrumbs. Modern Apple Help Books do not use them, and
+  handle all navigation via their JavaScript, so this support was dropped. If
+  you wish to go against Apple’s style, you can re-introduce these partials from
+  an older version of _Middleman_ yourself, as all of the internal logic is
+  still present.

data/documentation_project/Contents/Resources/en.lproj/100_reference/040_directory_reference.html.md.erb

@@ -0,0 +1,260 @@
+---
+title:  Directory and File Reference
+blurb:  Let us examine all of the files and folders in a standard
+        <em>Middlemac</em> project folder.
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.blurb %>
+
+
+`your_project/`
+
+: This is the self-contained directory containing everything that you need to
+  configure and build your project.
+  
+`your_project/config.rb`
+
+: This file contains most of your project settings for configuring
+  _Middlemac_, _Middleman_, and other _Middleman_ extensions you might add
+  in the future. 
+
+`your_project/Gemfile`
+
+: This file keeps track of the Ruby dependencies that are required for
+  _Middleman_ to work. You can edit this file to add additional _Middleman_
+  extensions, should you wish _Middlemac_/_Middleman_ do something more.
+
+`your_project/Gemfile.lock`
+
+: This is the bundler-generated file specifying the _exact_ dependency
+  configuration used. As Ruby Gems are updated on your system, this file will
+  ensure that updated versions are _not_ used, so that your configuration
+  stays frozen and steady. You can `bundle update` when you are ready to use
+  the newest version of Gems; doing so regenerates this file.
+
+`your_project/middlemac.webloc`
+
+: This is a convenient shortcut that, when used, will open your Help Book
+  in the default browser to the main `index.html` file.
+
+`your_project/Contents/`
+
+: Contains everything in your help project that will be compiled into or
+  contribute to the final `.help` project.
+   
+
+`your_project/Contents/Info.plist.erb`
+
+: The `Info.plist.erb` file is the file that _Middlemac_ will process into the
+  final `Info.plist` that your macOS 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. 
+   
+
+`your_project/Contents/Resources/index.html`
+
+: This file is the heart of your entire modern Help Book. When the Help Book
+  is open in Apple Help Viewer or being served to your web browser, it is the
+  only page that you will ever truly see. The entire rest of your Help Book,
+  in any language, is loaded by this file for display via AJAX. Consequently,
+  it strips out most of the `<head>` information from your own files, loads
+  all of the JavaScripts and styles, and manages language selection, TOC, and
+  everything else in your Help Book.
+  
+  The data that appear in your generated HTML documents’ `<head>` is still
+  critical to the Apple Help Indexer. Don’t try to simplify things by removing
+  these items from the layout templates.
+  
+  You generally should never have to edit this file, unless you want to
+  include some CSS or JavaScript that is not provided by _Middlemac_.
+
+
+`your_project/Contents/Resources/locale-list.json.erb`
+
+: When served to a web browser, Apple’s JavaScript will refer to this file
+  to determine which languages are available. This file is managed
+  automatically by _Middlemac_ based on the actual `language.lproj` files
+  that are present in your project.
+   
+   
+`your_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.
+   
+   
+`your_project/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.
+    
+
+`your_project/Contents/Resources/SharedGlobalAssets/_data/locale-list.json`
+
+: This file contains all of the source information for the locales that
+  _Middlemac_ supports “out of the box,” and is the same that Apple
+  generally provides for most of its applications. You should consult this
+  file to determine the correct `language.lproj` directory name to use for
+  developing help for locales other then the default `en.lproj`.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/_layouts/`
+
+: All layouts and templates should go here. This directory will not be
+  output in the final build.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/_layouts/layout-apple-modern-aside.haml`
+
+: This is the layout use for “aside” files. Your asides should set their
+  `layout` frontmatter key to this layout.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/_layouts/layout-apple-modern.haml`
+
+: This is the layout for all content files, and is used by default when
+  the frontmatter does not override it with a different `layout` key.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/_layouts/layout-blank.haml`
+
+: This is a layout that generates no content, and should be used for group
+  metadata `index.html` files.
+
+
+`your_project/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.
+
+
+`your_project/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.
+  
+  
+`your_project/Contents/Resources/SharedGlobalAssets/css/`
+
+: Your `.css` and `.scss` files should go here.
+  
+
+`your_project/Contents/Resources/SharedGlobalAssets/css/apple/`
+
+: Apple’s CSS and CSS related files exist in this directory.
+  
+
+`your_project/Contents/Resources/SharedGlobalAssets/css/middlemac/`
+
+: _Middlemac_’s CSS and CSS related files exist in this directory.
+  
+
+`your_project/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.
+  
+
+`your_project/Contents/Resources/SharedGlobalAssets/images/`
+
+: All images should go here. _Middleman_ will find them automatically if
+  you use the helpers.
+
+
+`your_project/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.
+
+
+`your_project/Contents/Resources/SharedGlobalAssets/js/app.5.1.xx.js`
+`your_project/Contents/Resources/SharedGlobalAssets/js/middlemac-debug.js`
+`your_project/Contents/Resources/SharedGlobalAssets/js/vendor.js`
+
+: These are the Apple and _Middlemac_ JavaScript files that operate the
+  modern Apple Help Book. Note that the `app.5.1.xx.js` file is as Apple
+  originally provides it, with some minor editing to work with `<img>` tag
+  `srcset` attributes.
+  
+  You should add any JavaScripts that your HelpBook requires here, and then
+  modify the main `index.html` file to include them.
+
+   
+`your_project/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. Out of the box, you can use
+  any language supported by `SharedGlobalAssets/_data/locale-list.json`.
+
+`your_project/Contents/Resources/en.lproj/ExactMatch.plist.erb`
+
+: This file supplements the `.helpindex` file when the Help Book is viewed in
+  Apple Help Viewer by providing exact word matching. _Middlemac_ generates
+  the finished version of this file based on the `exactmatch` keys in your
+  pages’ frontmatter. See [Apple’s documentation][1] for details.
+
+   
+`your_project/Contents/Resources/en.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`).
+
+
+`your_project/Contents/Resources/en.lproj/locale-info.json.erb`
+
+: This file contains metadata used by Apple’s JavaScript to understand the
+  locale details for this locale’s directory. It is managed automatically by
+  _Middlemac_.  
+
+
+`your_project/Contents/Resources/en.lproj/navigation.json.erb`
+
+: _Middlemac_ builds the output version of this file from your Help Book’s
+  sitemap. It is used by Apple’s JavaScript to make all of the navigation
+  features possible.
+
+
+`your_project/Contents/Resources/en.lproj/searchTree.json..erb`
+
+: This file contains the search index used when your Help Book is viewed in
+  a browser. _Middlemac_ generates the final version of this file when it
+  indexes your Help Book.
+
+
+`your_project/Contents/Resources/en.lproj/asides/`
+
+: This optional folder can be used to hold your aside files. Besides being a
+  convenient organizational location, it has the magic property of not
+  requiring the `aside` category in their frontmatter.
+
+`your_project/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, any subdirectories of `assets/` must mirror
+ the subdirectories of `SharedGlobalAssets/`, e.g., `assets/images/`.  
+{: .nontabular}
+
+
+ [1]: https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CH206-SW5

data/documentation_project/Contents/Resources/en.lproj/100_reference/050_xcode_integration.html.md.erb

@@ -0,0 +1,165 @@
+---
+title:  Xcode Integration
+blurb:  Integration with Xcode makes it simple to include the building of 
+        Help Books as part of your native Xcode workflow.
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.blurb %>
+
+If you choose to use optional integration, Xcode will build your Help Books
+for you, as needed, whenever you build your application. And if your Help Book
+has no updates, Xcode will be smart enough not to invoke _Middlemac_. You can
+reference the **HelpViewerApp** Xcode project that’s included in this
+documentation’s source distribution, and follow along below.
+
+GNU’s `make` is not happy with spaces in file paths. This is a shortcoming of
+`make`, and it will fail if there are any spaces in your Help Book source
+project directory or file names.
+{: .warning .callout}
+
+
+<% helpbook_task "xcode_integration_1", "Add the Help Book to your Project" do %>
+
+
+Built Help Books are just like any other asset in Xcode: as long as they are
+properly included in your project and part of a “Copy Resources” build phase,
+they will end up in the proper location in your application’s bundle when it
+is built.
+
+To make sure this happens, import your Help Book 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]
+
+
+<% end %>
+<% helpbook_task "xcode_integration_2", "Set up Target Membership" do %>
+
+
+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 "xcode_integration_3", "Create and Configure a Build Target" do %>
+
+
+Although Xcode provides its own build system, it also supports external build
+systems, including `make`, which is ubiquitous in the world. Even other build
+systems typically include `make` as a possible target.
+
+`make`, when executed, looks for a configuration file named `makefile` that
+contains all of the building instructions; _Middlemac_ provides this make file
+in new projects any time you `middlemac init` in terminal. The source for this
+documentation also includes _Middlemac_’s `makefile`.
+
+`make` has a superior advantage over shell scripts when it comes to automating
+builds: `make` will only perform the build if its necessary. Changes to your
+Help Book source project are detected, and if no files have changed, then
+`make` will simply report success instead of rebuilding your Help Book.
+{: .tip .callout}
+
+To instruct Xcode to use `make`, add a new target in Xcode, and choose the
+“External Build System” template for the target:
+
+![Xcode's target template chooser][xcode_integration_target_template]
+
+Give it a name appropriate to your Help Book.
+
+Next, set up the **External Build Tool Configuration**:
+
+- The **Build Tool** should be set to `/usr/bin/make`
+- Set **Arguments** to `$(ACTION) TARGET=pro`, where `pro` will be one of
+  your targets.
+- Set **Directory** to the location of the `makefile` in your project.
+
+![Configuring the external build target][xcode_integration_tool_configuration]
+
+Xcode will populate `$(ACTION)` with `clean` when you clean your project;
+otherwise it’s set to a null string. The `TARGET=` macro assignment
+is required.
+{: .note .callout}
+
+At this point, Xcode should have already created and selected a scheme for
+building this target, and so you should be able to conduct a build from within
+Xcode immediately.
+
+<% end %>
+<% helpbook_task "xcode_integration_4", "Set up Target Dependencies" do %>
+
+
+Because this integration uses `make`, your Help Books will only be built as
+needed. You can take advantage of this property to ensure that your macOS
+application never builds with an out-of-date Help Book that you forgot to
+rebuild, while allowing you to avoid the slow, Help Book building process
+every time you rebuild your application.
+
+To accomplish this, simply add the Help Book target as a dependency of your
+application.
+
+![Xcode target dependency][xcode_integration_target_dependencies]
+
+Now, like magic – or like any build system _should_ word – your Help Book will
+be created/updated when needed, and the latest version will always be included
+in your application builds.
+
+
+<% end %>
+<% helpbook_task "xcode_integration_5", "Passing Variables to Middlemac during Build" do %>
+
+
+Nothing is as disappointing as forgetting to update the version number in your
+Help Book when releasing a new version of your application. It looks sloppy
+and unprofessional. This can be avoided by using Xcode’s preprocessor
+definitions, which are exposed as environment variables during build operations.
+The included **HelpViewerApp** project is set up to get version and copyright
+information from its `versions.xcconfig` file:
+
+~~~ xcconfig
+MIDDLEMAC_CFBundleShortVersionString = 3.0.0
+MIDDLEMAC_CFBundleVersion = 3.0.0
+MIDDLEMAC_NSHumanReadableCopyright = Copyright ©2018 Jim Derry. All Rights Reserved.
+~~~
+
+In order to expose these to the environment during builds, though, Xcode must 
+know that this file is part of the configuration. In the **HelpViewerApp** this
+is simple:
+
+![Using configuration sets][xcode_integration_config_sets]
+
+
+The two target applications’ `.plist` files, of course, can use these
+definitions just as easily as the built-in definitions:
+
+![Using preprocessor definitions in plists][xcode_integration_plist_definitions]
+
+Because these variables are also passed to the environment during builds, you
+will notice that this documentation’s source code `config.rb` file contains
+this line near the top:
+
+~~~ ruby
+version_app = ENV.has_key?('MIDDLEMAC_CFBundleShortVersionString') ? ENV['MIDDLEMAC_CFBundleShortVersionString'] : nil
+~~~
+
+and 
+
+~~~ ruby
+:ProductVersion   => version_app || '3.0.0'
+~~~
+
+…in the the `:targets` configuration. This ensures that when Xcode builds your
+Help Book using `make`, the correct version information will be used. A fallback
+value ('3.0.0') is provided in the event that you build from the shell directly.
+
+<% end %>
+
+

data/documentation_project/Contents/Resources/{Base.lproj/100_reference/10_cli_ref.html.md.erb → en.lproj/100_reference/060_cli_ref.html.md.erb}

@@ -2,14 +2,10 @@
 title:  Command Line Interfaces
 blurb:  Discover the CLI’s offered by the various Ruby gems that compose
         <em>Middlemac</em>.
-layout: template-logo-medium
 ---
 <%= md_links %>
 <%= md_images %>
 
-<%= current_page.data.title %>
-==============================
-
 <%= current_page.data.blurb %>
 
 `middleman` command signature
@@ -17,7 +13,7 @@ layout: template-logo-medium
 
 You will use `middleman` to build `middlemac` projects.
 
-~~~ bash
+~~~
 bundle exec middleman [[build|server] [--target xxx]] | [build_all|all]
 ~~~
 
@@ -32,7 +28,7 @@ with a list of targets defined in the project.
 _Middlemac_ offers its own commands for generating new projects and getting
 help.
 
-~~~ bash
+~~~
 middlemac [init|documentation|help|--version]
 ~~~
 
@@ -40,32 +36,10 @@ Use `init` to generate the structure for a new, empty project, and use
 `documentation` to generate a project that can build this very documentation.
 
 
-`middlemac-extras` command signature
-------------------------------------
-
-~~~ bash
-middlemac-extras [documentation|help|--version]
-~~~
-
-Use `documentation` to generate a project that can build complete documentation.
-
-
-`middleman-pagegroups` command signature
-----------------------------------------
-
-~~~ bash
-middleman-pagegroups [documentation|partials|help|--version]
-~~~
-
-Use `documentation` to generate a project that can build complete documentation,
-or use `partials` to generate the partial files that you can use instead of
-helpers.
-
-
 `middlemac-targets` command signature
 -------------------------------------
 
-~~~ bash
+~~~
 middlemac-targets [documentation|help|--version]
 ~~~
 

data/documentation_project/Contents/Resources/en.lproj/100_reference/080_frontmatter_reference.html.md.erb

@@ -0,0 +1,111 @@
+---
+title:  Frontmatter and Keys Reference
+blurb:  Examine all of the different frontmatter keys and their use in a single
+        location.
+exactmatch:
+ - frontmatter
+ - frontmatterkeys
+ - exactmatch
+---
+<%= 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:  Examine all of the different frontmatter keys and their use in a single
+        location.
+exactmatch:
+ - frontmatter
+ - frontmatterkeys
+ - exactmatch
+---
+~~~
+
+You can also specify your own frontmatter keys and values. All frontmatter is
+available for use in your pages and templates via `current_page.data`, e.g.,
+`current_page.data.title`.
+
+
+Middlemac Frontmatter Keys
+--------------------------
+
+`anchor`
+
+ : Every Help Book page that you generate will include an anchor, which is
+   usually the page name determined by _Middlemac_, and can be found using
+   the `current_page.page_name` helper. You can specify your own anchor, if
+   you prefer, using this frontmatter key.
+   
+   Anchors are very useful when using `NSHelpManager` to open a Help Book to a
+   specific page.
+   
+`blurb`
+
+ : The blurb will be used as a `meta description` for each of your pages, where
+   it will be picked up and indexed by the Apple Help Indexer. This Help Book
+   also uses the blurb on most pages as the opening paragraph. Finally, the
+   blurb is used in building the `navigation.json` file.
+
+`categories`
+
+ : Pages can be assigned to one or more categories which _Middlemac_ and
+   Apple’s help system will use to control certain behaviors. Your landing
+   page should be assigned the category `landing`. If you have a copyright
+   page, it should be assigned `copyright`. Any “aside” pages should be
+   assigned `aside` among their categories.
+
+`exactmatch`
+
+ : You can add `ExactMatch.plist` entries, which will be added to the final
+   `ExactMatch.plist` when the Help Book is built.
+ 
+`exclude`
+
+ : Indicates which [targets and features][targets_and_features] this page should
+   be hidden from.
+   
+`keywords`
+
+ : Specify keywords for the `meta keywords` tag for each page of your Help
+   Book. These will be indexed by web crawlers (if your project is online),
+   and importantly, will be indexed by the Apple Help Indexer so that search
+   may work.
+
+`layout`
+
+ : Specify the layout or template to use to render the page. If you don’t
+   specify a layout, then the `layout-apple-modern` layout will be used by
+   default.
+   
+   In general, the default works perfectly fine for building a modern Apple
+   Help Book. However, [group][groups] `index.html` metadata files should be
+   set to `layout-blank`, and “aside” pages should be set to 
+   `layout-apple-modern-aside`.
+
+`order`
+
+ : Set the sorting/display order for a particular file within its group.
+
+`target`
+
+ : Indicates which [targets and features][targets_and_features] this page is
+   applicable for.
+
+`title`
+
+ : The page title will be used in to the HTML `<title>` tag for every page,
+   and more importantly, will be the text displayed for links by all of
+   _Middlemac_’s helpers and Apple’s Help Book navigation.
+