middlemac 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d2b3410abbcf1647fe5bb583455675fc72a44c94
-  data.tar.gz: 92adcc43e61ddf09e65e84c99eb031fb183b3cb1
+  metadata.gz: 31fee728bef8cc15a8f5fccde7b2fbefc66d918d
+  data.tar.gz: fffd42f0b926640d7863283438f4f31d53ce212d
 SHA512:
-  metadata.gz: b8ec6cd32d7a0f7c23fff233455cb8b9d52ab4031db52c3561516f06879ba07f915142f70c208f0da68c23d88ac696ecd1eb889c6a52a8dbbed059d30624fb0e
-  data.tar.gz: e523e9deb1141f927269495e61aa0fa8afdde9105f8e9fef6545e6cb88c12f156d599e708713b0e94a69968d7060a73cd8964606fbfe2d94c1ff69d3723019d4
+  metadata.gz: 68f9a4dc8fbf2d3c00c4066c2d22c5dba2b06c6fbe2b853b8d060af9ad02ec7f038aaa7674beb2008466f5a8cc81ff5f7961db391f0ce1b7bcc77b475d01af7a
+  data.tar.gz: 895b99f44d41673ccab7bf4de1b23fb5a6b6d1c80cd67c9bbee8b93e1607f43acd9dc447f0eed1f843b61d34eba7b59068ff1e4e4024e52f8ff97a0e2c2b8d04

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 middlemac change log
 ====================
 
+- Version 3.0.0 / 2018-June-18
+
+  - Major update to Middlemac to support modern macOS Help Books. Middlemac
+    now builds Help Books that take advantage of Apple’s “Eagle” framework for
+    providing a consistent look and feel across Help Books, and provides neat
+    browser-based features such as search and language switching.
+
 - Version 2.0.0 / 2016-May-15
 
   - All new Middlemac version 2.0.0!

data/Gemfile

@@ -2,7 +2,7 @@
 # the following line to use "http://" instead
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in middleman-pagegroups.gemspec
+# Specify your gem's dependencies in middlemac.gemspec
 gemspec
 
 group :development do
@@ -16,3 +16,13 @@ group :test do
   gem 'aruba'
   gem 'rspec'
 end
+
+
+# These are needed so that Cucumber will work with our fixture. As this
+# is not part of the gem, it's probably okay, but seems rather stupid.
+# It used to work without this, and Middleman would load its *own* gemfile
+# from the fixture. Not sure why that's not happening.
+gem 'middleman-targets'
+gem 'middleman-syntax'
+gem 'middleman-compass'
+

data/README.md

@@ -1,23 +1,55 @@
-Middlemac, the Middleman Build System for Mac OS X Help Projects
-================================================================
+Middlemac, the Middleman Build System for macOS Help Projects
+=============================================================
 [![Gem Version](https://badge.fury.io/rb/middlemac.svg)](https://badge.fury.io/rb/middlemac)
 
 
 _Middlemac_
 
 This gem provides a complete solution to generating help documentation for
-Mac OS X applications in the form of Help Books, using Middleman and a
+macOS applications in the form of modern Help Books, using Middleman and a
 selection of custom extensions to provide everything a developer needs.
 
+The Help Books you make will be modern Apple Help Books, complete with Apple’s
+native look and feel, and having the same features as Apple’s own Help Books.
+These features aren’t a simulation by _Middlemac_, but are truly Apple native
+Help Book features.
+
 Using this Apple Help Book building system leverages the tools of _Middleman_ to
-make building end-user documentation for your Mac OS X applications a snap.
+make building end-user documentation for your macOS applications a snap.
 Whether you are targeting multiple versions of your application or a single
 version, once properly configured, _Middlemac_ will take all of the pain out of
 building help files.
 
+_Middlemac_ isn’t merely a text-to-HTML tool. It manages multiple languages,
+provides helpers to assist with asset management, supports multiple versions of
+your help (for multiple versions of your application), and more.
+
+
+Alternatives to _Middlemac_
+---------------------------
+
+If your needs are very little and you simply want something that resembles
+Apple’s Help Books without all of the extra features, then you cannot go wrong
+with [jekyll-apple-help](https://github.com/chuckhoupt/jekyll-apple-help). 
+
+
+Middlemac’s Manual
+------------------
+
+The steps below lead you through installing _Middlemac_ and building its manual
+using _Middlemac_. That’s asking an awful lot if you just want to take a look at
+what it does, so feel free to visit the manual on its website:
+
+- The manual built using the “free” target is [right here][1].
+- The manual built using the “pro” target can be looked at [here][2].
+
+ [1]: https://www.balthisar.com/manuals/Middlemac3_(free)/Contents/Resources/index.html
+ [2]: https://www.balthisar.com/manuals/Middlemac3_(pro)/Contents/Resources/index.html
+
 
 Simple README
 -------------
+
 Jump to the [verbose README](#verbose-readme) and instructions below, otherwise…
 
 
@@ -112,7 +144,7 @@ There are multiple ways you could be reading this content now, but for now we
 will assume that you have not yet installed _Middlemac_ and its dependencies.
 
 To get started and read the full documentation, make sure that your system has
-[Ruby](https://www.ruby-lang.org/) installed (it comes pre-installed on Mac OS X
+[Ruby](https://www.ruby-lang.org/) installed (it comes pre-installed on macOS
 and some Linuxes), and follow these steps below. 
 
 We now recommend the use of the Ruby Version Manager [(RVM)](https://rvm.io/).
@@ -143,7 +175,7 @@ xcode-select --install
 
 If that fails or the rest of the installation fails, then install all of XCode.
 It’s available in the App Store. It’s free of charge. And you’re using this
-project to develop help for Mac OS X applications that you’re developing using
+project to develop help for macOS applications that you’re developing using
 XCode anyway. Install it, already!
 
 Dependencies on Linux are left up to you. Most modern Linuxes will prompt you to

data/Rakefile

@@ -17,7 +17,11 @@ task :default => :test
 #   Perform Cucumber testing.
 ###############################################################################
 Cucumber::Rake::Task.new(:test, 'Features that must pass') do |task|
-  task.cucumber_opts = '--require features --color --tags ~@wip --strict --format QuietFormatter'
+  task.cucumber_opts = '--require features --color --tags "not @wip" --strict --format pretty'
+end
+
+Cucumber::Rake::Task.new(:testq, 'Features that must pass') do |task|
+  task.cucumber_opts = '--require features --color --tags "not @wip" --strict --format pretty 2>/dev/null'
 end
 
 
@@ -46,10 +50,11 @@ task :partials do
       { :file => '_yard_middlemac_helpers.erb',          :group => 'Helpers',  },
       { :file => '_yard_middlemac_helpers_extended.erb', :group => 'Extended Helpers' },
       { :file => '_yard_middlemac_config.erb',           :group => 'Extension Configuration' },
+      { :file => '_yard_middlemac_resources.erb',        :group => 'Resource Extensions',  },
   ]
   
   # Define the output directory.
-  dest = File.join('documentation_project', 'Contents', 'Resources', 'Base.lproj', 'assets', 'partials')
+  dest = File.join('documentation_project', 'Contents', 'Resources', 'SharedGlobalAssets', '_partials')
 
   # Run YARD multiple times, filtering the group that interests us.
   sections.each do |s|

data/documentation_project/.gitignore

@@ -21,7 +21,7 @@ Gemfile.lock
 .sassc
 .tmp
 build*
-Makefile
+!build.sh
 tmp
 
 # XCode user-specific files

data/documentation_project/Contents/Info.plist.erb

@@ -19,7 +19,7 @@
 	<key>CFBundleVersion</key>
 	<string><%= config[:targets][config[:target]][:CFBundleVersion] || product_version %></string>
 	<key>HPDBookIconPath</key>
-	<string><%= config[:targets][config[:target]][:HPDBookIconPath] || 'shared/icon_32x32@2x.png' %></string>
+	<string><%= config[:targets][config[:target]][:HPDBookIconPath] || 'SharedGlobalAssets/convention/icon_32x32@2x.png' %></string>
 	<key>HPDBookKBProduct</key>
 	<string><%= config[:targets][config[:target]][:HPDBookKBProduct] %></string>
 	<key>HPDBookKBURL</key>

data/documentation_project/Contents/Resources/SharedGlobalAssets/_data/locale-list.json

@@ -0,0 +1,318 @@
+[
+  {
+    "text-direction": "ltr",
+    "name": "English (U.S.)\u200e",
+    "isoName": "English (U.S.)\u200e",
+    "isoCodes": [
+      "en",
+      "en-us"
+    ],
+    "folder": "en.lproj"
+  },
+  {
+    "text-direction": "rtl",
+    "name": "\u0627\u0644\u0639\u0631\u0628\u064a\u0629",
+    "isoName": "Arabic",
+    "isoCodes": [
+      "ar"
+    ],
+    "folder": "ar.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Catal\u00e0",
+    "isoName": "Catalan",
+    "isoCodes": [
+      "ca"
+    ],
+    "folder": "ca.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "\u010ce\u0161tina",
+    "isoName": "Czech",
+    "isoCodes": [
+      "cs"
+    ],
+    "folder": "cs.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Dansk",
+    "isoName": "Danish",
+    "isoCodes": [
+      "da"
+    ],
+    "folder": "da.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Deutsch",
+    "isoName": "German",
+    "isoCodes": [
+      "de"
+    ],
+    "folder": "de.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "\u0395\u03bb\u03bb\u03b7\u03bd\u03b9\u03ba\u03ac",
+    "isoName": "Greek",
+    "isoCodes": [
+      "el"
+    ],
+    "folder": "el.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Espa\u00f1ol",
+    "isoName": "Spanish",
+    "isoCodes": [
+      "es"
+    ],
+    "folder": "es.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Espa\u00f1ol (Latinoam\u00e9rica)\u200e",
+    "isoName": "Latin American Spanish",
+    "isoCodes": [
+      "es-419",
+      "es-xl"
+    ],
+    "folder": "es_419.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Suomi",
+    "isoName": "Finnish",
+    "isoCodes": [
+      "fi"
+    ],
+    "folder": "fi.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Fran\u00e7ais",
+    "isoName": "French",
+    "isoCodes": [
+      "fr"
+    ],
+    "folder": "fr.lproj"
+  },
+  {
+    "text-direction": "rtl",
+    "name": "\u05e2\u05d1\u05e8\u05d9\u05ea",
+    "isoName": "Hebrew",
+    "isoCodes": [
+      "he"
+    ],
+    "folder": "he.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Hrvatski",
+    "isoName": "Croatian",
+    "isoCodes": [
+      "hr"
+    ],
+    "folder": "hr.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Magyar",
+    "isoName": "Hungarian",
+    "isoCodes": [
+      "hu"
+    ],
+    "folder": "hu.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Bahasa Indonesia",
+    "isoName": "Indonesian",
+    "isoCodes": [
+      "id"
+    ],
+    "folder": "id.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Italiano",
+    "isoName": "Italian",
+    "isoCodes": [
+      "it"
+    ],
+    "folder": "it.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "\u65e5\u672c\u8a9e",
+    "isoName": "Japanese",
+    "isoCodes": [
+      "ja"
+    ],
+    "folder": "ja.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "\ud55c\uad6d\uc5b4",
+    "isoName": "Korean",
+    "isoCodes": [
+      "ko"
+    ],
+    "folder": "ko.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Bahasa Melayu",
+    "isoName": "Malaysian",
+    "isoCodes": [
+      "ms"
+    ],
+    "folder": "ms.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Nederlands",
+    "isoName": "Dutch",
+    "isoCodes": [
+      "nl"
+    ],
+    "folder": "nl.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Norsk (bokm\u00e5l)\u200e",
+    "isoName": "Norwegian",
+    "isoCodes": [
+      "nb",
+      "nn",
+      "no"
+    ],
+    "folder": "no.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Polski",
+    "isoName": "Polish",
+    "isoCodes": [
+      "pl"
+    ],
+    "folder": "pl.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Portugu\u00eas (Brasil)\u200e",
+    "isoName": "Brazilian Portuguese",
+    "isoCodes": [
+      "pt-br",
+      "pt"
+    ],
+    "folder": "pt.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Portugu\u00eas (Portugal)\u200e",
+    "isoName": "Portuguese",
+    "isoCodes": [
+      "pt-pt"
+    ],
+    "folder": "pt_PT.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Rom\u00e2n\u0103",
+    "isoName": "Romanian",
+    "isoCodes": [
+      "ro"
+    ],
+    "folder": "ro.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "\u0420\u0443\u0441\u0441\u043a\u0438\u0439",
+    "isoName": "Russian",
+    "isoCodes": [
+      "ru"
+    ],
+    "folder": "ru.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Sloven\u010dina",
+    "isoName": "Slovak",
+    "isoCodes": [
+      "sk"
+    ],
+    "folder": "sk.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Svenska",
+    "isoName": "Swedish",
+    "isoCodes": [
+      "sv"
+    ],
+    "folder": "sv.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "\u0e20\u0e32\u0e29\u0e32\u0e44\u0e17\u0e22",
+    "isoName": "Thai",
+    "isoCodes": [
+      "th"
+    ],
+    "folder": "th.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "T\u00fcrk\u00e7e",
+    "isoName": "Turkish",
+    "isoCodes": [
+      "tr"
+    ],
+    "folder": "tr.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "\u0423\u043a\u0440\u0430\u0457\u043d\u0441\u044c\u043a\u0430",
+    "isoName": "Ukrainian",
+    "isoCodes": [
+      "uk"
+    ],
+    "folder": "uk.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "Ti\u1ebfng Vi\u1ec7t",
+    "isoName": "Vietnamese",
+    "isoCodes": [
+      "vi"
+    ],
+    "folder": "vi.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "\u7b80\u4f53\u4e2d\u6587",
+    "isoName": "Simplified Chinese",
+    "isoCodes": [
+      "zh-cn",
+      "zh-hans",
+      "zh"
+    ],
+    "folder": "zh_CN.lproj"
+  },
+  {
+    "text-direction": "ltr",
+    "name": "\u7e41\u9ad4\u4e2d\u6587",
+    "isoName": "Traditional Chinese",
+    "isoCodes": [
+      "zh-tw",
+      "zh-hk",
+      "zh-mo",
+      "zh-hant"
+    ],
+    "folder": "zh_TW.lproj"
+  }
+]

data/documentation_project/Contents/Resources/SharedGlobalAssets/_layouts/layout-apple-modern-aside.haml

@@ -0,0 +1,19 @@
+!!!
+%html{:lang => "#{current_page.hb_locale}"}
+  %head
+    %meta{:charset => 'UTF-8'}
+    %meta{:name => 'robots', :content => 'noindex'}
+    %title= current_page.data.title || "#{product_name} Help"
+  - classes = ["apd-topic", "Aside"]
+  - id = current_page.hb_NavId
+  %body{:dir => "ltr", :class => classes, :id => id}
+    %a{:name => id}
+
+    = yield
+
+-#
+  This layout will be used for every aside portion of your help book. The key
+  difference is that the meta robots prevents this page from being indexed,
+  because it's not a free-standing page. Additionally, it's a good idea to
+  assign your group-definition index files to this layout, as well, since
+  they have no content and we don’t want them indexed.

data/documentation_project/Contents/Resources/SharedGlobalAssets/_layouts/layout-apple-modern.haml

@@ -0,0 +1,61 @@
+- landing = current_page.data.categories && current_page.data.categories.include?('landing')
+- debug = extensions[:Middlemac].options[:show_debug]
+!!!
+%html{:lang => "#{current_page.hb_locale}"}
+  %head
+    - if !debug
+      :JavaScript
+        window.location.href = "#{current_page.hb_redirect_path}";
+    %meta{:charset => 'UTF-8'}
+    %meta{:'http-equiv' => 'refresh', :content => "#{debug ? 100 : 0}; url=#{current_page.hb_redirect_path}" }
+    - if current_page.data.blurb
+      %meta{:name => 'description', :content => strip_tags(current_page.data.blurb)}
+    - if current_page.data.keywords
+      %meta{:name => 'keywords', :content => current_page.data.keywords.join(', ')}
+    %title= current_page.data.title || "#{product_name} Help"
+  - classes = ["AppleTopic"]
+  - id = current_page.hb_NavId
+  - current_page.data.categories.each { |c| classes << c unless classes.include?(c) } if current_page.data.categories
+  %body{:dir => "ltr", :class => classes, :id => id}
+    %a{:name => current_page.data.anchor || current_page.page_name}
+
+    - if landing
+      = image_tag "icon_256x256"
+      %h1 #{product_name} #{product_version}
+      %h2
+        %a{:href => "#{product_uri}" } #{product_uri}
+    - else
+      = image_tag current_page.data.topicIcon || "icon_256x256", :figure_class => 'topicIcon'
+      %h1 #{current_page.data.title}
+    
+    = yield
+    
+    -# Need an empty <ul> for the show/hide topics to show up.
+    - if landing
+      %ul
+    
+    - if content_for?(:seeAlso)
+      .LinkUniversal
+        %strong
+          See Also
+        = yield_content :seeAlso
+    
+    - if debug
+      .middlemac-debug
+        %hr
+        %p
+          These following appear here because `config.rb` has `options.show_debug = true`.
+        %h2 Images Available with md_images
+        = md_images
+        %h2 Links Available with md_links
+        = md_links
+
+-#
+  This layout will be used for nearly every page of your help book. Apple’s
+  scripts will strip out everything from the head, and so everything set here
+  is really only useful for indexers and for Apple’s JavaScript to use; they
+  won’t appear in the finished document. Note, too, that when a client attempts
+  to load this page directly, the browser will be directed to the index page
+  instead, which loads this content via AJAX. This is important because the
+  Help Indexer will index the page, and the Help Viewer will attempt to load
+  the page, and it would be ugly and unstyled if that happened.

data/documentation_project/Contents/Resources/SharedGlobalAssets/_layouts/layout-blank.haml

@@ -0,0 +1,11 @@
+!!!
+%html{:lang => "#{current_page.hb_locale}"}
+  %head
+    %meta{:charset => 'UTF-8'}
+    %meta{:name => 'robots', :content => 'noindex'}
+    %title= current_page.data.title || "#{product_name} Help"
+  %body
+
+-#
+  This layout should be used for pages with no content, such as the index.html
+  pages used as group metadata containers.