--- title: Set Up your Help Project blurb: Setting up your help project is the first step in Middlemac’s workflow. Understand how configure your project and Xcode in this article. --- <%= md_links %> <%= md_images %> <%= current_page.data.blurb %> The file `config.rb` has settings which both affect how _Middleman_ operates as well as how _Middlemac_ builds your Help Books. **If you follow the _Middlemac_ conventions, there should be no reason to change the _Middleman_ settings.** When you open `config.rb` in your text editor, at the top you will readily identify the start of the _Middlemac_ configuration section, which is delimited by this block at the beginning: ~~~ ruby ################################################################################ # config.rb # Configure Middleman to generate Apple Help Book containers for multiple # targets. ################################################################################ ~~~ And terminated by this block at the end: ~~~ ruby ################################################################ # STOP! There's nothing below here that you should have to # change. Just follow the conventions and framework provided. ################################################################ ~~~ ## Sections Because _Middlemac_ is made from a few different components, its key configuration is performed in a couple of different blocks. The file is also very well commented, and the [API Reference][config_ref] contains specific documentation for each setting. However the `targets` hash bears explaining. ## The `targets` hash explained At first the `targets` option looks complicated in that it consists of nested hashes, but the format is quite simple to get used to. Each root level item in `targets` consists of the following items, which are unique for each target. `:CFBundleID` : **Each help target must have a unique `CFBundleID` that matches a unique `CFBundleHelpBookName` in your applications’ `Info.plist` files**. This pairing is the mechanism by which macOS knows which help bundle belongs to which application. If they are not unique, macOS _will_ become confused, and your end-users, if they have multiple versions of your product installed, will not be very satisfied. `:HPDBookIconPath` : 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 `Info.plist` file per Apple’s specification. If `nil` (or not present) 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`. This is *not* intended to be a product name, which is defined below. `:ProductName` `:ProductVersion` `:ProductURI` `:ProductCopyright` : The default templates use these in a prominent way, and they’re also available to you using _Middlemac_’s helpers. `:Features` : Aside from **targets** the use of **features** can give you fine-grained control over what content appears in each target. It’s considered a best-practice to include all of the same features in the hash for each target, and specify a boolean (true/false) value for each key, as appropriate for your target. _Middlemac_ documentation has four features defined. {: .width25} 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`. If your `CFBundleName` contains any space characters, they will be replaced during build with underscores. This ensures that if you use `make` (e.g., such as from within Xcode) to build your Help Books, `make`’s broken handling of spaces won’t prevent a build. {: .note .callout} CFBundleID and Targets ---------------------- You will also have to have unique bundle identifiers for each of your Help Book targets, and you will have to have these available when you set up your `Info.plist` files in Xcode. As is standard with BundleID’s, reverse DNS notation is preferred. This documentation project uses `com.balthisar.middlemac.free.help` and `com.balthisar.middlemac.pro.help` for its two targets. Let’s use this information and start to set up Xcode. Xcode Configuration ------------------- ### Add Files Let’s first tell your Xcode application 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. Help Books are bundles with their own localizations inside of them. Don’t put Help Books in your application’s localized folders such as `Base.lproj/` or `en.lproj/`. Putting them into `Resources/` is the right thing to do. {: .tip .callout} 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. 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**. {: .tip .callout} In each of your `Info.plist` files, find or create the following keys: `Help Book directory name` (`CFBundleHelpBookFolder`) : Ensure you use the appropriate `Middlemac_(pro).help` or `Middlemac_(free).help`, depending on which target’s `.plist` this is. `Help Book identifier` (`CFBundleHelpBookName`) : 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`. {: .nontabular} 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.