middlemac 2.0.0

data/documentation_project/Contents/Resources/Base.lproj/060_content/080_markdown_links_images.html.md.erb

@@ -0,0 +1,93 @@
+---
+title:  <code>md_links</code> and <code>md_images</code> helpers
+blurb:  Learn to take advantage of helpers that give you a hand using reference
+        style links to content and images.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+You’ll notice (as you look at the source files for this help content) that the
+first ERB instructions immediately after the frontmatter are:
+
+~~~ erb
+<%%= md_links %>
+<%%= md_images %>
+~~~
+
+These convenience helpers make it relatively simple to include Markdown links
+and images using the reference format.
+ 
+Links
+-----
+
+~~~ markdown
+[all help content][all_help_content-index]
+~~~
+
+…will generate the following link:
+
+[all help content][all_help_content-index]
+
+This is especially useful if your page source filenames stay constant.
+
+The reference name will always be the base output name of the file. For index
+files, the format will be `groupname-index`, where the groupname is the name of
+the containing directory, as you should already know. The top-level index file
+will conveniently, simply be `index`.
+
+You should strive to use unique filenames if you use this feature, as this will
+ensure that your references remain unique. In the event of reference name
+collisions, the reference name will be prepended with its nesting groups as many
+levels as necessary to become unique. For convenience items that are higher in
+your directory hierarchy are prioritized against prepending.
+
+Here’s the complete result of this helper for this help book:
+
+~~~ markdown
+<%= md_links %>
+~~~
+
+Pretty neat how it includes the titles, right? Try hovering your mouse over the
+example [all help content][all_help_content-incex] link. Including titles isn’t
+possible in Markdown without using reference links.
+{:.note}
+
+
+Images
+------
+
+Markdown also supports a reference format for images. It looks like this:
+
+~~~ markdown
+![this is alt tag content][middlemac-logo-small]
+~~~
+
+And will generate this:
+
+![this is alt tag content][middlemac-logo-small]
+
+
+Here’s the complete result of this helper for this help book:
+
+~~~ markdown
+<%= md_images %>
+~~~
+
+Note that using reference style Markdown images is performed by the Markdown
+processor directly. Using magic prefixes for automatic target-based images
+won’t work. However they will work with standard Markdown, non-reference
+images. Note how this next example includes the target-specific logo:
+{:.note}
+
+~~~ markdown
+![target specific logo](all-middlemac-logo-small)
+~~~
+
+![target specific logo](all-middlemac-logo-small)

data/documentation_project/Contents/Resources/Base.lproj/060_content/090_css_image_sizes.html.md.erb

@@ -0,0 +1,90 @@
+---
+title:  Automatic CSS Image Maximum Sizes
+blurb:  Ensure that your image sizes aren’t unexpectedly distorted by using this
+        special helper.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+This helper provides CSS code for each of your images, specifying a `max-width`
+and `max-height` for each image used in your Middleman project (except for SVG
+files, which don’t have dimensions).
+
+## Example
+
+When called like this:
+
+~~~ erb
+<%%= css_image_sizes %>
+~~~
+
+…the result is this:
+
+~~~ scss
+<%= css_image_sizes %>
+~~~
+
+## Use
+
+You could use this in an HTML `<style>` element on each of your pages, or better
+yet in your layouts. This has the unfortunate effect of including it in every
+one of your pages, however, and so this sample project uses it like this:
+
+Contents of `stylesheets/css_image_sizes.css.erb`:
+
+~~~ erb
+<%%= css_image_sizes %>
+~~~
+
+This will create `stylesheets/css_image_sizes.css` in your build output, and
+this file is included in the project layout file:
+
+~~~ haml
+= stylesheet_link_tag 'css_image_sizes'
+~~~
+
+You will be tempted to add this helper to your `style.css.scss` file, maybe
+even renaming it to `style.css.scss.erb`, but this will not work due to the
+order that Middleman and SASS build output.
+{:.note}
+
+
+## Technical details
+
+This CSS will control your image sizes by specifying a maximum width and height
+for each image in the project using the `src` attribute selector and matching
+against the end of that value. For example:
+
+~~~ scss
+img[src$='icon.png'] { max-width: 256px; max-height: 256px; }
+~~~
+
+CSS matches using literal text, and so will not respect relative paths. The
+simple rule above has a high possibility of naming collisions with other files
+named `icon.png`.
+
+If you follow Middleman’s best practices and keep most or all of your images in
+the defined `:images_dir` then the possibility of naming collisions will go
+away, as this helper will deliver the `src` attribute selectors starting with
+the final component of your `:images_dir`, for example:
+
+~~~ scss
+img[src$='images/logo-small.png'] { max-width: 128px; max-height: 128px; }
+img[src$='images/blog/logo-small.png'] { max-width: 160px; max-height: 160px; }
+img[src$='icon_32x32.png'] { max-width: 32px; max-height: 32px; }
+~~~
+
+In this example, the last image – `icon_32x32.png` – is not within `:images_dir`
+and so has no directory and is subject to naming collisions.
+
+The scheme above will work whether or not Middleman is configured with
+`relative_assets` because both relative and absolute links will always contain
+that last part of the path component. The only way this might break is by
+serving HTML pages from within your `:images_dir`.

data/documentation_project/Contents/Resources/Base.lproj/060_content/100_using_local_data.html.md.erb

@@ -0,0 +1,37 @@
+---
+title:  Using local data
+blurb:  You can use a local file as a datasource to generate data-based pages
+        automatically. Learn how in this reference section.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+You can use data from external sources with _Middleman_ and _Middlemac_, too.
+In `assets/data/` a sample `globals.yml` contains some sample data in YAML
+format. Let’s see what it contains:
+
+<% data.globals.famous_writers.each do |writer| %>
+- A sample work of <%= writer.author %> is _<%= writer.sample_work %>_.
+<% end %>
+
+These previous sentences were generated with this ERB code:
+
+~~~ erb
+<%% data.globals.famous_writers.each do |writer| %>
+- A sample work of <%%= writer.author %> is _<%%= writer.sample_work %>_.
+<%% end %>
+~~~
+
+
+Accessing data
+--------------
+
+This data is available to you via `data.file_name.top_level_key`.
+

data/documentation_project/Contents/Resources/Base.lproj/060_content/index.html.md.erb

@@ -0,0 +1,21 @@
+---
+title:  "Workflow: Develop your Help Content"
+blurb:  Once you’ve learned of the possibilities when it comes to structuring
+        your help, discover all of the conveniences made possible by
+        <em>Middlemac</em>’s rich set of content features.
+layout: template-logo-large
+navigate: true
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+* * *
+
+<%= nav_legitimate_children %>
+
+* * *

data/documentation_project/Contents/Resources/Base.lproj/070_preview_build/index.html.md.erb

@@ -0,0 +1,78 @@
+---
+title:  "Workflow: Preview and Build your Help Books"
+blurb:  "Your development be quicker by previewing your work with
+        <em>Middleman</em>’s preview server before the next step: building your
+        help book."
+layout: template-logo-medium
+navigate: true
+---
+<%= md_links %>
+<%= md_images %>
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+Preview in a Web Browser
+------------------------
+
+_Middleman_ has its own web server so that you can preview your work during
+development. From within your project directory, simply do:
+
+~~~ bash
+bundle exec middleman
+~~~
+
+This will start the server with your default target. To specify a specific
+target to serve, simply use the `--target` command line option:
+
+~~~ bash
+bundle exec middleman --target your_target_here
+~~~
+
+In general the server address to connect to in your browser is `localhost:4567`,
+but your environment could be different. The server will always provide one or
+more addresses to try.
+
+Note also that if you try to connect to your Help Book project at the server
+root, you will receive a file not found error. Do remember that due to Mac OS X
+help book requirements, the content actually begins at `/Resources/Base.lproj/`.
+
+
+Build your Help Book(s)
+-----------------------
+
+Build your projects is similarly easy:
+
+~~~ bash
+bundle exec middleman build
+~~~
+
+…to build the default target.
+
+~~~ bash
+bundle exec middleman build --target your_target_here
+~~~
+
+…to build the target named `your_target_here`.
+
+
+~~~ bash
+bundle exec middleman build_all
+~~~
+
+…to build all of your targets at once.
+
+
+Opening your Help Books
+-----------------------
+
+Mac OS X won't open help books that haven’t been indexed by the operating
+system, so you’ll have to preview them in a real application. Because you’re
+making help books, it’s presumed that you have an application that can fill this
+role. If not, you can modify the included **HelpViewerApp** Xcode project that’s
+in this documentation project’s directory.
+
+To view the contents of the `.help` package in **Finder**, simply context-click
+it and choose **Show Package Contents**.

data/documentation_project/Contents/Resources/Base.lproj/090_build_application/10_apple_help_setup.html.md.erb

@@ -0,0 +1,110 @@
+---
+title:  Apple .help bundle setup
+blurb:  A reference to what <em>Middlemac</em> does to ensure that you build a
+        proper, working Apple Help Book.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+CFBundleName and Targets
+------------------------
+
+The first thing we need to do is come up with a `CFBundleName` for our help
+projects, and decide what the targets are going to be. This will help us setup
+Xcode shortly.
+
+Xcode doesn’t know or care what the help bundle’s `CFBundleName` is, but
+_Middlemac_ uses it and the target to name the final, built help bundle, and
+Xcode _does_ have to know the name of those.
+
+All of your targets will share the same `CFBundleName`, so it should be
+descriptive of all of your targets and related to your product name. If the
+examples on this page, we’ll use `Middlemac`. This project also has the targets
+`pro` and `free`. What this means is _Middlemac_ will build help bundles named
+`Middlemac (pro).help` and `Middlemac (free).help`.
+
+Let’s use this information and start to setup Xcode.
+
+
+Xcode Configuration
+-------------------
+
+### Add Files 
+
+Let’s first tell your Xcode targets that the help bundle files are available. In
+your Xcode project, create folders named `Middlemac (pro).help` and `Middlemac
+(free).help`. They typically go into your project’s `Resources` folder. Mac OS
+will automatically display them as bundles. For now, these are just proxies for
+the bundles we’ll build later.
+
+Next you can add these files to Xcode the usual way (“Add files…”). **Make sure
+you add these by creating folder references. This is critical.** If you are
+able to browse the folder contents in Xcode, then they were not properly added
+and will not properly copy into the final application bundle.
+
+Just in case the bold sentence wasn’t reminder enough: make sure you select the
+option to create folder references when adding files.
+{:.note}
+
+Assuming you have a Pro and Free target in Xcode, you can use the file inspector
+to make sure the Pro `.help` and the Free `.help` have the appropriate, obvious
+target memberships.
+
+### Configure your applications’ `Info.plist` files
+
+If you have multiple Xcode targets, you may be using a different `Info.plist`
+file for each target. If not, then you’ll have to start because they contain
+information unique to each help book.
+ 
+Alternatively you can setup an `Info.plist` pre-processor (this is my preferred
+approach) that generates an `Info.plist` for each target when you build.
+_That’s_ beyond the scope of this document, though. You can begin by looking at
+your Xcode targets’ **Build Settings -> Packaging**.
+{:.note}
+
+In each of your `Info.plist` files, find or create the following keys:
+
+`Help Book directory name` (Xcode name)
+`CFBundleHelpBookFolder` (raw key name)
+
+ : Ensure you use the appropriate `Middlemac (pro).help` or
+   `Middlemac (free).help`, depending on which target’s `.plist` this is.
+
+`Help Book identifier` (Xcode name)
+`CFBundleHelpBookName` (raw key name)
+
+ : This must match the unique `CFBundleID` that you set for each of your
+   help targets in the help project’s `config.rb` file. If you’ve not setup
+   the `config.rb` yet, now is a good time to decide on the keys that you will
+   use. 
+   
+   This sample project uses `com.balthisar.middlemac.free.help` and
+   `com.balthisar.middlemac.pro.help`.
+
+
+Setup `config.rb` and especially `options.Help_Output_Location`
+-------------------------------------------------------------------
+
+Next make sure you setup `config.rb` with matching values from above.
+
+We setup empty proxy `.help` bundles for Xcode above. Make sure that you set
+your `config.rb`’s `options.Help_Output_Location` to the directory that you
+created the proxy files. Then, any time you build your help projects with
+_Middlemac_, they will be ready to go in Xcode automatically, the next time you
+build your Xcode project.
+
+
+_Middlemac_ takes care of everything else
+-----------------------------------------
+
+Once your `config.rb` is setup, _Middlemac_ takes care of setting all of the
+required keys and data in all of the help bundle `.plist`, `.strings`, and
+main `index.html` file, managing them for each target.
+

data/documentation_project/Contents/Resources/Base.lproj/090_build_application/20_xcode_integration.html.md.erb

@@ -0,0 +1,64 @@
+---
+title:  Optional Xcode Integration
+blurb:  Learn some tips and techniques for getting Xcode to cooperate with
+        <em>Middlemac</em> projects.
+layout: template-logo-medium
+---
+<%= md_links %>
+<%= md_images %>
+
+
+<%= current_page.data.title %>
+==============================
+
+<%= current_page.data.blurb %>
+
+In the [previous section][apple_help_setup] you learned how simple it is to make
+Xcode include your built help projects in your application, but with a little
+bit of extra work you can even have Xcode build your help projects for you.
+
+**HelpViewerApp**
+-----------------
+
+Included the the source directory for this documentation project is a directory
+named `HelpViewerApp` that includes a simple Xcode project. Aside from the
+ability to display this project’s built help files in Help Viewer (instead of
+a web browser), it demonstrates one technique for having Xcode build your help
+books for you.
+
+It consists of the following four targets:
+
+`Help (free)` 
+
+  : This is an external build system target that uses **Middlemac** to generate
+    the help files for the `HelpViewerApp (free)` target.
+  
+`Help (pro)`
+
+  : This is an external build system target that uses **Middlemac** to generate
+    the help files for the `HelpViewerApp (pro)` target.
+
+`HelpViewerApp (free)`
+
+  : The “free” version of this application will display the `:free` target in
+    the Help Viewer. It uses the target `Help (free)` as a build dependency.
+
+`HelpViewerApp (pro)`
+
+  : The “pro” version of this application will display the `:pro` target in the
+    Help Viewer.  It uses the target `Help (pro)` as a build dependency.
+
+
+## The Help file “build system”
+
+The build system is a bash script that executes the default version of
+**Middleman** on your system. In order to prevent re-building the help file
+every time you run the HelpViewerApp it tries to remember that it was already
+built using a marker file in the Xcode build directory.
+
+It's a simple script and doesn’t try at all to know whether or not you’ve made
+changes to the source. If you want to rebuild the help files using the build
+command in Xcode, then perform **Clean**, which will remove this marker file.
+
+Xcode’s **Clean** will _not_ remove the built help book using this script; you
+are free to make the script do so if you want, however.