middlemac 2.0.0 → 3.0.0

data/documentation_project/config.rb

@@ -1,9 +1,19 @@
 ################################################################################
 #  config.rb
-#    Configure Middleman to generate Apple HelpBook containers for multiple
+#    Configure Middleman to generate Apple Help Book containers for multiple
 #    targets.
 ################################################################################
 
+##########################################################################
+# Build System Integration
+#  If built from Xcode (or another build system you create), then setup
+#  some of our variables automatically from the environment variables
+#  that the build system sets for us. You’ll have to set up Xcode to
+#  set this environment variable, of course.
+##########################################################################
+version_app = ENV.has_key?('MIDDLEMAC_CFBundleShortVersionString') ? ENV['MIDDLEMAC_CFBundleShortVersionString'] : nil
+
+
 ##########################################################################
 # Targets Configuration
 #  Middlemac is capable of building multiple targets for variants of your
@@ -40,12 +50,13 @@ config[:target] = :pro
 # If specified a target-specific icon will be used as the help book icon by
 # Apple’s help viewer. This path must be relative to the location of the
 # `Resources` directory per Apple’s specification. If `nil` (or not present) 
-# then the default `shared/icon_32x32@2x.png` will be used.
+# then the default `SharedGlobalAssets/convention/icon_32x32@2x.png` will be
+# used.
 
 # :CFBundleName
 # This value will be used for correct .plists and .strings setup, and will
 # determine final .help directory name. All targets should use the same
-# :CFBundleName. Built targets will be named `CFBundleName (target).help`.
+# :CFBundleName. Built targets will be named `CFBundleName_(target).help`.
 # This is *not* intended to be a product name, which is defined below.
 
 # :ProductName
@@ -61,6 +72,10 @@ config[:target] = :pro
 # You can specify different product URIs for each build target. The URI
 # for the current target will be available via the `product_uri` helper.
 
+# :ProductCopyright
+# You should specify a copyright string to be included in the Apple Help Book.
+# This typically appears when you print a Help Book.
+
 # (other)
 # You can specify additional .plist and .strings keys here, too. Have a look
 # at `Info.plist.erb` and `InfoPlist.strings.erb`; simply use the exact key
@@ -76,11 +91,12 @@ config[:targets] = {
         :free =>
             {
                 :CFBundleID       => 'com.balthisar.middlemac.free.help',
-                :HPDBookIconPath  => 'shared/free-icon_32x32@2x.png',
+                :HPDBookIconPath  => 'SharedGlobalArt/free-icon_32x32@2x.png',
                 :CFBundleName     => 'Middlemac',
                 :ProductName      => 'Middlemac',
-                :ProductVersion   => '2.0.0',
+                :ProductVersion   => version_app || '3.0.0',
                 :ProductURI       => 'http://www.balthisar.com/developer',
+                :ProductCopyright => '© 2018 Jim Derry. All rights reserved.',
                 :features =>
                     {
                         :feature_advertise_pro        => true,
@@ -93,11 +109,12 @@ config[:targets] = {
         :pro =>
             {
                 :CFBundleID       => 'com.balthisar.middlemac.pro.help',
-                :HPDBookIconPath  => 'shared/pro-icon_32x32@2x.png',
+                :HPDBookIconPath  => 'SharedGlobalArt/pro-icon_32x32@2x.png',
                 :CFBundleName     => 'Middlemac',
                 :ProductName      => 'Middlemac Pro',
-                :ProductVersion   => '2.0.0',
+                :ProductVersion   => version_app || '3.0.0',
                 :ProductURI       => 'http://www.balthisar.com/developer',
+                :ProductCopyright => '© 2018 Jim Derry. All rights reserved.',
                 :features =>
                     {
                         :feature_advertise_pro        => false,
@@ -121,64 +138,6 @@ config[:target_magic_images] = true
 config[:target_magic_word] = 'all'
 
 
-################################################################
-# Page Groups Configuration
-#  Middlemac uses the `middleman-pagegroups` gem in order to
-#  automate nearly all of the navigation in your help book
-#  project.
-################################################################
-activate :MiddlemanPageGroups do |config|
-
-  # Indicate whether or not numeric file name prefixes used for sorting
-  # pages should be eliminated during output. This results in cleaner
-  # URI's. Helpers such as `page_name` and Middleman helpers such as
-  # `page_class` will reflect the pretty name.
-  config.strip_file_prefixes = true
-
-  # Indicates whether or not Middleman's built-in `page_class` helper is
-  # extended to include the page_group and page_name.
-  config.extend_page_class = true
-
-  # the following options provide defaults for the built-in helpers and
-  # sample partials. They'll also work in your own partials and helpers.
-
-  config.nav_breadcrumbs_class = 'breadcrumbs'
-  config.nav_breadcrumbs_alt_class = 'breadcrumbs'
-  config.nav_breadcrumbs_alt_label = 'Current page'
-  config.nav_brethren_class = 'table_contents'
-  config.nav_brethren_index_class = 'related-topics'
-  config.nav_legitimate_children_class = 'table_contents'
-  config.nav_prev_next_class = 'navigate_prev_next'
-  config.nav_prev_next_label_prev = 'Previous'
-  config.nav_prev_next_label_next = 'Next'
-  config.nav_toc_index_class = 'help_map'
-
-end
-
-
-################################################################
-# Extras Configuration
-#  Middlemac uses the `middlemac-extras` gem in order to
-#  provide other useful tools. They can be configured here.
-################################################################
-activate :MiddlemacExtras do |config|
-
-  # If set to true, then the enhanced image_tag helper will be used
-  # to include @2x srcset automatically, if the image asset exists.
-  config.retina_srcset = true
-
-  # If set to true then the `image_tag` helper will work for images even
-  # if you don't specify an extension, but only if a file exists on disk
-  # that has one of the extensions in :img_auto_extensions_order.
-  config.img_auto_extensions = true
-
-  # Set this to an array of extensions in the order of precedence for
-  # using `image_tag` without file extensions.
-  config.img_auto_extensions_order = %w(.svg .png .jpg .jpeg .gif .tiff .tif)
-
-end
-
-
 ################################################################
 # Configuration
 #  Change the option values to suit your needs.
@@ -191,16 +150,35 @@ activate :Middlemac do |options|
   # named in the form `#{CFBundleName} (target).help`. You might want to target
   # the `Resources` directory of your XCode project so that your XCode project
   # is always up to date.
-  options.Help_Output_Location = nil
+  options.help_output_location = nil
 
-  # Indicates the name of the breadcrumbs helper to use for breadcrumbs.
-  # Built-in breadcrumbs are "nav_breadcrumbs" and "nav_breadcrumbs_alt".
-  # Change to `nil` to disable breadcrumbs completely.
-  options.Breadcrumbs = 'nav_breadcrumbs'
+  # If set to true, then the enhanced image_tag helper will be used
+  # to include @2x, @3x, and @4x srcset automatically, if the image assets
+  # exist.
+  options.retina_srcset = true
+
+  # If set to an array of possible image extension values, then the `image_tag`
+  # helper will work for images even if you don't specify an extension, but only
+  # if a file exists in the sitemap that has one of these extensions. Set this to
+  # an array of extensions in the order of precedence.
+  options.img_auto_extensions = %w(.svg .png .jpg .jpeg .gif .tiff .tif)
+
+  # If set to true, some of the templates will show additional information
+  # when pages are generated, such as contents of md_links and md_images.
+  # Also, JavaScript redirects will be omitted from naked pages, and the
+  # meta refresh will be set to 100 seconds for such pages.
+  options.show_debug = false
+
+  # If set to true, Apple will provide next page and previous page navigation
+  # gadgets automatically at the bottom of each content page. Apple itself
+  # does not use this feature currently.
+  options.show_previous_next = false
 
-  # This was removed in Middleman version 4.0. We are reintroducing it
-  # as a Middlemac feature.
-  options.partials_dir = 'Resources/Base.lproj/assets/partials'
+  # Indicate whether or not numeric file name prefixes used for sorting
+  # pages should be eliminated during output. This results in cleaner
+  # URI's. Helpers such as `page_name` and Middleman helpers such as
+  # `page_class` will reflect the pretty name.
+  config.strip_file_prefixes = true
 
 end #activate
 
@@ -214,42 +192,32 @@ end #activate
 #===============================================================
 # Setup directories to mirror Help Book directory layout.
 #===============================================================
-set :source,       'Contents'
-set :build_dir,    'Contents (build)'
-
-set :fonts_dir,    'Resources/Base.lproj/assets/fonts'
-set :images_dir,   'Resources/Base.lproj/assets/images'
-set :js_dir,       'Resources/Base.lproj/assets/javascripts'
-set :css_dir,      'Resources/Base.lproj/assets/stylesheets'
-
-set :layouts_dir,  'Resources/Base.lproj/assets/_layouts'
-set :data_dir,     'Contents/Resources/Base.lproj/assets/_data'
-
-
-#===============================================================
-# Ignore items we don't want copied to the destination
-#===============================================================
-#ignore 'data/*'
+set :source,         'Contents'
+set :data_dir,       'Contents/Resources/SharedGlobalAssets/_data'
+set :assets_dir,     'Resources/SharedGlobalAssets'
+set :partials_dir,   '_partials'
+set :layouts_dir,    '_layouts'
+set :convention_dir, 'convention'
+set :css_dir,        'css'
+set :fonts_dir,      'fonts'
+set :images_dir,     'images'
+set :js_dir,         'js'
 
 
 #===============================================================
-# All of our links and assets must be relative to the file
-# location, and never absolute. However we will *use* absolute
-# paths with root being the source directory; they will be
-# converted to relative paths at build.
+# Other required setup. Note: don't use relative assets or
+# links here, as Apple require very specific hrefs.
 #===============================================================
 set :strip_index_file, false
-set :relative_links, true
-activate :relative_assets do |options|
-  options.rewrite_ignore = [/image_sizes\.css/]
-end
 
 
 #===============================================================
-# Default to Apple-recommended HTML 4.01 layout.
+# Default to HTML5 Layout.
 #===============================================================
-set :haml, :format => :html4
-page 'Resources/Base.lproj/*.html', :layout => :'layout-html4'
+Haml::TempleEngine.disable_option_validator!
+set :haml, :format => :html5
+page 'Resources/*.lproj/*.html', :layout => :'layout-apple-modern'
+page 'Resources/*.lproj/asides/*.html', :layout => :'layout-apple-modern-aside'
 
 
 #===============================================================

data/documentation_project/makefile

@@ -0,0 +1,93 @@
+###############################################################################
+# Building from make rather than the previous shell script gives us a lot of
+# flexibility and is a bit simpler to integrate with Xcode.
+#
+# Usage:
+# make build|clean TARGET=target
+# Specifying a target is required.
+#
+# Make will assume that this makefile is in the root of your project, at the
+# same level as your source Contents/ directory. To use this file from Xcode,
+# create an External Build System target, and specify `/usr/bin/make` as the
+# build tool, `$(ACTION) TARGET=your_target_or_variable` as the arguments,
+# and for Directory, a path to this file, e.g., `$(PROJECT_DIR)/path/to/me`.
+###############################################################################
+
+
+#====================================================================
+# Prerequisites:
+# - Ensure that a TARGET is specified.
+# - Make sure Middlemac is installed and reachable. Although we
+#   could do that in a recipe, we need to discover our BUILD_DIR, 
+#   which cannot be done in a recipe.
+# - Discover our BUILD_DIR, by asking Middleman for the build 
+#   directory for the specified target.
+# Output will be provided in a target recipe if these conditions
+# cannot be met.
+#====================================================================
+
+ifdef TARGET
+	MM_EXISTS := $(shell [[ -s "$(HOME)/.rvm/environments/default" ]] && source "$(HOME)/.rvm/environments/default" ; which middlemac)
+endif
+ifdef MM_EXISTS
+	BUILD_DIR := $(shell export LANG=en_US.UTF-8 && [[ -s "$(HOME)/.rvm/environments/default" ]] && source "$(HOME)/.rvm/environments/default" ; bundle exec middleman list_all | grep "$(TARGET)," | cut -d\  -f2- )
+endif
+
+
+#====================================================================
+# "Source" files to monitor for changes. If any of these change,
+# then they will have a new file modification date than the
+# $(BUILD_DIR), causing the action to execute.
+#====================================================================
+SRC_FILES = $(shell find Contents)
+SRC_FILES += config.rb Gemfile Gemfile.lock
+
+#====================================================================
+# The default action, will build the specified TARGET using
+# Middleman, by depending on the $(BUILD_DIR).
+#====================================================================
+.PHONY: build
+build: check_prerequisites $(BUILD_DIR)
+
+
+#====================================================================
+# The action that will actually perform the building of the help
+# book. If the directory specified by $(BUILD_DIR) is older than
+# any of the given source files, then this action will be executed.
+# NOTE: make does NOT work with spaces in filenames.
+#====================================================================
+$(BUILD_DIR): $(SRC_FILES)
+	@echo "Make will have Middleman build target '$(TARGET)'"
+# 	@echo "RECIPE AS KNOWN TO MAKE: $@"
+# 	@echo "       ACTUAL BUILD_DIR: $(BUILD_DIR)"
+# 	@echo "       EXECUTION REASON: $?"
+	@export LANG=en_US.UTF-8 && \
+	[[ -s "$(HOME)/.rvm/environments/default" ]] && source "$(HOME)/.rvm/environments/default" ; \
+	bundle exec middleman build --target "$(TARGET)"
+	@touch "$(BUILD_DIR)"
+
+
+#====================================================================
+# Clean the given target.
+#====================================================================
+.PHONY: clean
+clean: check_prerequisites
+	@echo "Cleaning $(BUILD_DIR)…"
+	@rm -rf "$(BUILD_DIR)"
+
+
+#====================================================================
+# Ensure that we have everything that we need to proceed with doing
+# something with Middlemac and with the target.
+#====================================================================
+.PHONY: check_prerequisites
+check_prerequisites:
+ifndef TARGET
+	$(error "ERROR: It's required to specify a target macro, e.g., TARGET=default.")
+endif
+ifndef MM_EXISTS
+	$(error "ERROR: Middlemac was not found, and is required to continue.")
+endif
+ifndef BUILD_DIR
+	$(error "ERROR: Target ${TARGET} was specified, but Middlemac did not find any valid targets.")
+endif

data/features/helpers_features.feature

@@ -0,0 +1,59 @@
+Feature: Provide helpers and resource items to make multiple targets easy to manage.
+
+  As a software developer
+  I want to use helpers and resource items
+  In order to enable automatic navigation of items.
+  
+  Background:
+    Given a built app at "middlemac_app"
+    
+  Scenario:
+    The css_image_sizes helper should return CSS for every image in the project
+    and @2x images should have proper widths and heights, too.
+    When I cd to "New_Project_(pro).help/Contents/Resources/en.lproj/"
+    And the file "goodbye_world_file.html" should contain "img[src$='SharedGlobalAssets/convention/icon_256x256.png'] { max-width: 256px; max-height: 256px; }"
+    And the file "goodbye_world_file.html" should contain "img[src$='SharedGlobalAssets/convention/icon_256x256@2x.png'] { max-width: 256px; max-height: 256px; }"
+    And the file "goodbye_world_file.html" should contain "img[src$='SharedGlobalAssets/convention/icon_32x32.png'] { max-width: 32px; max-height: 32px; }"
+    And the file "goodbye_world_file.html" should contain "img[src$='SharedGlobalAssets/convention/icon_32x32@2x.png'] { max-width: 32px; max-height: 32px; }"
+
+
+  Scenario:
+    The md_images helper should return Markdown references for every image in
+    the project.
+    When I cd to "New_Project_(pro).help/Contents/Resources/en.lproj/"
+    And the file "goodbye_world_file.html" should contain "[icon_256x256@2x]: /Resources/SharedGlobalAssets/convention/icon_256x256@2x.png"
+    And the file "goodbye_world_file.html" should contain "[icon_32x32]: /Resources/SharedGlobalAssets/convention/icon_32x32.png"
+    And the file "goodbye_world_file.html" should contain "[icon_32x32@2x]: /Resources/SharedGlobalAssets/convention/icon_32x32@2x.png"
+
+
+  Scenario:
+    The md_links helper should return Markdown references for every HTML file
+    in the project, and should include a title generated from the front matter.
+    When I cd to "New_Project_(pro).help/Contents/Resources/en.lproj/"
+    And the file "goodbye_world_file.html" should contain '[goodbye_world_file]: #/topic-en.lproj-goodbye_world_file "Goodbye World"'
+    And the file "goodbye_world_file.html" should contain '[hello_world_file]: #/topic-en.lproj-hello_world_file "Hello World"'
+    And the file "goodbye_world_file.html" should contain '[testing_world_file]: #/topic-en.lproj-testing_world_file "Testing World"'
+    
+    
+  Scenario:
+    The extended image tag should include srcset automatically if @2x images are
+    present, and not include a srcset if not.
+    When I cd to "New_Project_(pro).help/Contents/Resources/en.lproj/"
+    And the file "goodbye_world_file.html" should contain 'img src="/Resources/SharedGlobalAssets/convention/icon_32x32.png" srcset="/Resources/SharedGlobalAssets/convention/icon_32x32.png 1x, /Resources/SharedGlobalAssets/convention/icon_32x32@2x.png 2x" alt="Icon 32x32"'
+    And the file "goodbye_world_file.html" should contain 'img src="/Resources/SharedGlobalAssets/convention/icon_256x256.png" srcset="/Resources/SharedGlobalAssets/convention/icon_256x256.png 1x, /Resources/SharedGlobalAssets/convention/icon_256x256@2x.png 2x" alt="Icon 256x256"'
+    And the file "goodbye_world_file.html" should contain 'img src="/Resources/en.lproj/assets/images/subdirectory/logo_32x32.png" alt="Logo 32x32"'
+    And the file "goodbye_world_file.html" should contain 'img src="/Resources/en.lproj/assets/images/neat_thing_32x32.png" alt="Neat thing 32x32"'
+    And the file "goodbye_world_file.html" should contain 'img src="/Resources/en.lproj/assets/images/subdirectory/pro-image_32x32.png" alt="Pro image 32x32"'
+    And the file "goodbye_world_file.html" should contain 'img src="/Resources/en.lproj/assets/images/all-graphic_32x32.png" alt="All graphic 32x32'
+    And the file "goodbye_world_file.html" should contain 'img src="/Resources/SharedGlobalAssets/images/myfile-NOT_IN_SITEMAP" alt="Myfile not in sitemap"'
+    And the file "goodbye_world_file.html" should contain 'img src="/Resources/SharedGlobalAssets/images/myfile-NOT_IN_SITEMAP.png" alt="Myfile not in sitemap"'
+
+
+  Scenario:
+    The link_to helper should return links that are useful to the Apple help
+    book engine instead of normal HTML links, unless the link is to a page
+    that is not in the project.
+    When I cd to "New_Project_(pro).help/Contents/Resources/en.lproj/"
+    And the file "goodbye_world_file.html" should contain 'a href="#/topic-en.lproj-hello_world_file"'
+    And the file "goodbye_world_file.html" should contain 'a href="#/topic-sample_group_number_two-page_two"'
+    And the file "goodbye_world_file.html" should contain 'a href="doesntexist.html"'

data/features/main_features.feature

@@ -2,20 +2,19 @@ Feature: Middlemac produces plist and strings files, uses correct HTML formats,
   and provides useful helpers to generate content.
 
   As a software developer
-  I want to build useable Mac OS X help books.
+  I want to build useable macOS help books.
   
   Background:
     Given a built app at "middlemac_app"
     
   Scenario:
-    The correct HTML version must be used on the top level index page versus
-    other pages in the project.
-    When I cd to "New Project (pro).help/Contents/Resources/Base.lproj/"
-    And the file "index.html" should contain "DTD XHTML 1.0 Strict"
-    And the file "testing_world_file.html" should contain "DTD HTML 4.01"
+    The correct HTML version must be used on generated files.
+    When I cd to "New_Project_(pro).help/Contents/Resources/en.lproj/"
+    And the file "index.html" should contain "<html lang='en'>"
+    And the file "testing_world_file.html" should contain "<html lang='en'>"
 
   Scenario: The Info.plist file must be processed with relevant data.
-    When I cd to "New Project (pro).help/Contents/"
+    When I cd to "New_Project_(pro).help/Contents/"
     And the file "Info.plist" should contain "<string>com.sample.project.pro.help</string>"
     And the file "Info.plist" should contain "<string>New Project</string>"
     And the file "Info.plist" should contain "<string>New Project.helpindex</string>"
@@ -23,22 +22,27 @@ Feature: Middlemac produces plist and strings files, uses correct HTML formats,
     And the file "Info.plist" should contain "<string>http://www.sample.com</string>"
       
   Scenario: The InfoPlist.strings file must be processed with relevant data.
-    When I cd to "New Project (pro).help/Contents/Resources/Base.lproj/"
+    When I cd to "New_Project_(pro).help/Contents/Resources/en.lproj/"
     And the file "InfoPlist.strings" should contain "<string>New Project</string>"
     And the file "InfoPlist.strings" should contain "<string>New Project Help</string>"
 
   Scenario: The help index file should have been produced.
-    When I cd to "New Project (pro).help/Contents/Resources/Base.lproj/"
+    When I cd to "New_Project_(pro).help/Contents/Resources/en.lproj/"
     And the file "New Project.helpindex" should exist
+    
+  Scenario: The navigation.json file must have relevant data.
+    When I cd to "New_Project_(pro).help/Contents/Resources/en.lproj/"
+    And the file "navigation.json" should contain "sample_group_number_two/nested_group_example/page_san.html"
+    And the file "navigation.json" should contain '"landing": "topic-Resources-en.lproj",'
+
 
   Scenario: The helpers will produce correct output.
-    When I cd to "New Project (pro).help/Contents/Resources/Base.lproj/"
-    And the file "testing_world_file.html" should contain "breadcrumbs:nav_breadcrumbs"
-    And the file "testing_world_file.html" should contain "partials_dir:Resources/Base.lproj/assets/partials"
-    And the file "testing_world_file.html" should contain "cfBundleIdentifier:com.sample.project.pro.help"
-    And the file "testing_world_file.html" should contain "cfBundleName:New Project"
-    And the file "testing_world_file.html" should contain "product_name:New Project Pro"
-    And the file "testing_world_file.html" should contain "product_version:2.0.0.wip"
-    And the file "testing_world_file.html" should contain "product_uri:http://www.sample.com"
+    When I cd to "New_Project_(pro).help/Contents/Resources/en.lproj/"
+    And the file "testing_world_file.html" should contain "Resources/SharedGlobalAssets/_partials"
+    And the file "testing_world_file.html" should contain "com.sample.project.pro.help"
+    And the file "testing_world_file.html" should contain "New Project"
+    And the file "testing_world_file.html" should contain "New Project Pro"
+    And the file "testing_world_file.html" should contain "3.0.0.wip"
+    And the file "testing_world_file.html" should contain "http://www.sample.com"
     And the file "testing_world_file.html" should contain "_new_style_partial"
     And the file "testing_world_file.html" should contain "_partials_dir_partial"

data/features/support/env.rb

@@ -4,17 +4,3 @@ ENV['TEST'] = 'true'
 require 'middleman'
 require 'middleman-core/step_definitions'
 require File.join(PROJECT_ROOT_PATH, 'lib', 'middlemac')
-
-
-require 'cucumber/formatter/pretty'
-class QuietFormatter < Cucumber::Formatter::Pretty
-  def initialize(runtime, io, options)
-     $stderr = File.new( '/dev/null', 'w' )
-    super(runtime, io, options)
-  end
-  
-  def after_features(features)
-    $stderr = STDOUT
-    super(features)
-  end
-end

data/fixtures/middlemac_app/.gitignore

@@ -21,5 +21,4 @@ Gemfile.lock
 .sassc
 .tmp
 build*
-Makefile
 tmp

data/fixtures/middlemac_app/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>