middlemac 2.0.0 → 3.1.2

data/documentation_project/Contents/Resources/SharedGlobalAssets/_partials/_yard_middlemac_helpers_extended.erb

@@ -0,0 +1,369 @@
+
+
+
+
+
+  <div class="method_details_list">
+    
+    
+      
+        <div class="method_details first">
+  <h3 class="signature first" id="image_tag-instance_method">
+  
+    #<strong>image_tag</strong>(path, params = {})  &#x21d2; <tt>String</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>With the proper options enabled this helper extends
+the built-in functionality of <strong>Middleman</strong>’s helper
+in a couple of ways, as documented in the params
+hash.</p>
+
+<p>Note that Apple helpbooks embed nearly all <code>&lt;img&gt;</code>
+tags in a <code>&lt;figure&gt;</code>, so this is the default without
+the appropriate params, below.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>path</span>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>Specify path to the image file.</p>
+</div>
+      
+    </li>
+  
+    <li>
+      
+        <span class='name'>params</span>
+      
+      
+        <span class='type'>(<tt>Hash</tt>)</span>
+      
+      
+        <em class="default">(defaults to: <tt>{}</tt>)</em>
+      
+      
+        &mdash;
+        <div class='inline'><p>Optional parameters to pass to
+the helper. <strong>Middleman</strong> (and other extensions)
+provide other parameters in addition to these.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+  
+    
+    
+    
+    
+    <p class="tag_title">Options Hash (<tt>params</tt>):</p>
+    <ul class="option">
+      
+        <li>
+          <span class="name">:img_auto_extensions</span>
+          <span class="type">(<tt>Boolean</tt>)</span>
+          <span class="default">
+            
+          </span>
+          
+            &mdash; <div class='inline'><p>Allows
+control of the automatic image extensions option
+on a per-use basis.</p>
+</div>
+          
+        </li>
+      
+        <li>
+          <span class="name">:retina_srcset</span>
+          <span class="type">(<tt>Boolean</tt>)</span>
+          <span class="default">
+            
+          </span>
+          
+            &mdash; <div class='inline'><p>Allows control
+of the automatic @2x images feature on a per-use
+basis.</p>
+</div>
+          
+        </li>
+      
+        <li>
+          <span class="name">:figure</span>
+          <span class="type">(<tt>Boolean</tt>)</span>
+          <span class="default">
+            
+          </span>
+          
+            &mdash; <div class='inline'><p>Allows you to avoid
+the automatic framing of the image within a figure
+element, when set to <code>false</code>.</p>
+</div>
+          
+        </li>
+      
+        <li>
+          <span class="name">:figure_class</span>
+          <span class="type">(<tt>String</tt>)</span>
+          <span class="default">
+            
+          </span>
+          
+            &mdash; <div class='inline'><p>Specify the
+class, if any, to apply to the enclosing figure.</p>
+</div>
+          
+        </li>
+      
+    </ul>
+  
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>Returns an HTML <code>&lt;img&gt;</code> tag.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+</div>
+</div>
+      
+        <div class="method_details ">
+  <h3 class="signature " id="link_to-instance_method">
+  
+    #<strong>link_to</strong>(caption, url, options = {})  &#x21d2; <tt>String</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Returns a link in a form useful to helpbooks, i.e.,
+<code>#/hb_NavId</code>, so that Apple’s Javascript can load the
+correct file. Simply specify the path to the HTML
+file, and the helper will return an acceptable link.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>caption</span>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>The text of the link.</p>
+</div>
+      
+    </li>
+  
+    <li>
+      
+        <span class='name'>url</span>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>The path to the html file in the
+output hierarchy.</p>
+</div>
+      
+    </li>
+  
+    <li>
+      
+        <span class='name'>options</span>
+      
+      
+        <span class='type'>(<tt>Hash</tt>)</span>
+      
+      
+        <em class="default">(defaults to: <tt>{}</tt>)</em>
+      
+      
+        &mdash;
+        <div class='inline'><p>Optional parameters to pass to
+the helper. Consult Middleman’s documentation for
+most of these.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+  
+    
+    
+    
+    
+    
+    
+    <p class="tag_title">Options Hash (<tt>options</tt>):</p>
+    <ul class="option">
+      
+        <li>
+          <span class="name">:aside</span>
+          <span class="type">(<tt>Boolean</tt>)</span>
+          <span class="default">
+            
+          </span>
+          
+            &mdash; <div class='inline'><p>Returns the link in
+a format suitable for linking to a helpbook “aside”
+rather than the link to another page.</p>
+</div>
+          
+        </li>
+      
+    </ul>
+  
+
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>Returns an HTML <code>&lt;a&gt;</code> tag.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+</div>
+</div>
+      
+        <div class="method_details ">
+  <h3 class="signature " id="partial-instance_method">
+  
+    #<strong>partial</strong>(template, opts = {}, &amp;block)  &#x21d2; <tt>Object</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Extends the built-in <code>partials</code> helper to allow the
+use of a default partials directory as configured with
+<code>options[:partials_dir]</code>. Middleman 4.0 removed the
+option <code>partials_dir</code> which increased flexibility a
+lot, but hurt backwards compatibility. When used the
+default location will be searched first for the
+specified partial; if not found then the built-in
+behavior will be used.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  <p class="tag_title">Parameters:</p>
+<ul class="param">
+  
+    <li>
+      
+        <span class='name'>template</span>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>The partial file to use.</p>
+</div>
+      
+    </li>
+  
+    <li>
+      
+        <span class='name'>opts</span>
+      
+      
+        <span class='type'>(<tt>Hash</tt>)</span>
+      
+      
+        <em class="default">(defaults to: <tt>{}</tt>)</em>
+      
+      
+        &mdash;
+        <div class='inline'><p>Options to use for the partial.
+Consult <strong>Middleman</strong>’s documentation for possible
+options.</p>
+</div>
+      
+    </li>
+  
+    <li>
+      
+        <span class='name'>block</span>
+      
+      
+        <span class='type'>(<tt>Block</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>An option block as per the
+default implementation by <strong>Middleman</strong>.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+
+</div>
+</div>
+      
+    
+  </div>
+
+

data/documentation_project/Contents/Resources/{Base.lproj/assets/partials/_yard_pagegroups_resources.erb → SharedGlobalAssets/_partials/_yard_middlemac_resources.erb}

@@ -8,9 +8,52 @@
     
       
         <div class="method_details first">
-  <h3 class="signature first" id="resource.breadcrumbs-instance_method">
+  <h3 class="signature first" id="resource.asset_path_type-instance_method">
   
-    - (<tt>Array&lt;Sitemap::Resource&gt;</tt>) <strong>resource.breadcrumbs</strong> 
+    #<strong>resource.asset_path_type</strong>  &#x21d2; <tt>Symbol</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Indicates whether the asset is located in the :locale,
+the :global, the :convention, or an :other_dir folder.
+This can be useful to sort assets in a comparitor by
+priority if there are assets of the same name.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Symbol</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>:locale, :global, :convention, or
+:other_dir (in the event that it’s not expected).</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+</div>
+</div>
+      
+        <div class="method_details ">
+  <h3 class="signature " id="resource.breadcrumbs-instance_method">
+  
+    #<strong>resource.breadcrumbs</strong>  &#x21d2; <tt>Array&lt;Sitemap::Resource&gt;</tt> 
   
 
   
@@ -50,7 +93,7 @@ resources.</p>
         <div class="method_details ">
   <h3 class="signature " id="resource.brethren-instance_method">
   
-    - (<tt>Array&lt;Sitemap::Resource&gt;</tt>) <strong>resource.brethren</strong> 
+    #<strong>resource.brethren</strong>  &#x21d2; <tt>Array&lt;Sitemap::Resource&gt;</tt> 
   
 
   
@@ -100,7 +143,7 @@ resources.</p>
         <div class="method_details ">
   <h3 class="signature " id="resource.brethren_next-instance_method">
   
-    - (<tt>Sitemap::Resource</tt>) <strong>resource.brethren_next</strong> 
+    #<strong>resource.brethren_next</strong>  &#x21d2; <tt>Sitemap::Resource</tt> 
   
 
   
@@ -141,7 +184,7 @@ the next sibling.</p>
         <div class="method_details ">
   <h3 class="signature " id="resource.brethren_previous-instance_method">
   
-    - (<tt>Sitemap::Resource</tt>) <strong>resource.brethren_previous</strong> 
+    #<strong>resource.brethren_previous</strong>  &#x21d2; <tt>Sitemap::Resource</tt> 
   
 
   
@@ -182,7 +225,7 @@ the previous sibling.</p>
         <div class="method_details ">
   <h3 class="signature " id="resource.group_count-instance_method">
   
-    - (<tt>Integer</tt>) <strong>resource.group_count</strong> 
+    #<strong>resource.group_count</strong>  &#x21d2; <tt>Integer</tt> 
   
 
   
@@ -222,9 +265,9 @@ this page’s current group.</p>
 </div>
       
         <div class="method_details ">
-  <h3 class="signature " id="resource.legitimate_children-instance_method">
+  <h3 class="signature " id="resource.hb_locale-instance_method">
   
-    - (<tt>Array&lt;Sitemap::Resource&gt;</tt>) <strong>resource.legitimate_children</strong> 
+    #<strong>resource.hb_locale</strong>  &#x21d2; <tt>String</tt> 
   
 
   
@@ -232,17 +275,51 @@ this page’s current group.</p>
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Returns an array of all of the children of this
-resource, taking into account their eligibility for
-display. Each child is legitimate if it:</p>
+    <p>Returns the locale for the current resource, based on
+which language.lproj directory it’s in, or nil if it’s
+not in one.</p>
 
-<ul>
-  <li>has a sort_order.</li>
-  <li>is not ignored.</li>
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>The locale.</p>
+</div>
+      
+    </li>
+  
 </ul>
 
-<p>The returned array will be sorted by each item’s
-<code>sort_order</code>.</p>
+</div>
+</div>
+      
+        <div class="method_details ">
+  <h3 class="signature " id="resource.hb_NavId-instance_method">
+  
+    #<strong>resource.hb_NavId</strong>  &#x21d2; <tt>String</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Returns the navigation ID suitable for use in the
+modern Help’s <code>navigation.json</code> file. It is either a
+<code>topicId</code> or <code>sectionId</code>, depending on whether the 
+resource is a topic, or a section metadata resource.</p>
 
 
   </div>
@@ -255,13 +332,13 @@ display. Each child is legitimate if it:</p>
     <li>
       
       
-        <span class='type'>(<tt>Array&lt;Sitemap::Resource&gt;</tt>)</span>
+        <span class='type'>(<tt>String</tt>)</span>
       
       
       
         &mdash;
-        <div class='inline'><p>An array of
-resources.</p>
+        <div class='inline'><p>The navigation ID of the current
+resource.</p>
 </div>
       
     </li>
@@ -272,9 +349,9 @@ resources.</p>
 </div>
       
         <div class="method_details ">
-  <h3 class="signature " id="resource.navigator_eligible?-instance_method">
+  <h3 class="signature " id="resource.hb_Path-instance_method">
   
-    - (<tt>Boolean</tt>) <strong>resource.navigator_eligible?</strong> 
+    #<strong>resource.hb_Path</strong>  &#x21d2; <tt>String</tt> 
   
 
   
@@ -282,15 +359,145 @@ resources.</p>
   
 </h3><div class="docstring">
   <div class="discussion">
-    <p>Determines whether a page is eligible to include a
-previous/next page control. This is based on:</p>
+    <p>Returns the path as it should be used in the help book
+<code>navigation.json</code> file, i.e., relative to the
+<code>language.lproj</code> directory. Note that this is
+incomplete for use in <code>href</code> attributes, which require
+this path to be accessed via a javascript value, e.g.,
+<code>#/hb_path</code>.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>The navigation ID of the current
+resource.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+</div>
+</div>
+      
+        <div class="method_details ">
+  <h3 class="signature " id="resource.hb_redirect_path-instance_method">
+  
+    #<strong>resource.hb_redirect_path</strong>  &#x21d2; <tt>String</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Returns a path to this resource via the main file
+index.html file that runs the entire helpbook. Useful
+for redirecting naked pages in the site to index file
+for proper display in a meta refresh tag. For example,
+../../index.html?localePath=en.lproj#/topic-sample_group_number_one-page_one
+Note that in this case, the link <em>must</em> be relative,
+because the Apple Help Viewer doesn’t seem to work
+with book-absolute paths.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>String</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>Absolute path of this resource via
+index.html.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+</div>
+</div>
+      
+        <div class="method_details ">
+  <h3 class="signature " id="resource.hb_Section?-instance_method">
+  
+    #<strong>resource.hb_Section?</strong>  &#x21d2; <tt>Boolean</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Indicates whether or not a resource is a section entry
+for a modern Apple HelpBook.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Boolean</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>True if the resource represents a
+section heading.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+</div>
+</div>
+      
+        <div class="method_details ">
+  <h3 class="signature " id="resource.legitimate?-instance_method">
+  
+    #<strong>resource.legitimate?</strong>  &#x21d2; <tt>Boolean</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Indicates whether or not a page is “legitimate” in
+terms of automatic navigation, based in:</p>
 
 <ul>
-  <li>The group is set to allow navigation via the
-<code>:navigate</code> front matter key.</li>
-  <li>This page is not excluded from navigation via the
-use of <code>:navigator =&gt; false</code> in its front matter.</li>
-  <li>This page has a <code>sort_order</code>.</li>
+  <li>The resource has a sort order and isn’t zero.</li>
+  <li>The resource isn’t ignored.</li>
 </ul>
 
 
@@ -309,8 +516,58 @@ use of <code>:navigator =&gt; false</code> in its front matter.</li>
       
       
         &mdash;
-        <div class='inline'><p>Returns <code>true</code> if this pages is
-eligible for a previous/next page control.</p>
+        <div class='inline'><p>Returns <code>true</code> if this pages 
+participates in automatic navigation features.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
+</div>
+</div>
+      
+        <div class="method_details ">
+  <h3 class="signature " id="resource.legitimate_children-instance_method">
+  
+    #<strong>resource.legitimate_children</strong>  &#x21d2; <tt>Array&lt;Sitemap::Resource&gt;</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Returns an array of all of the children of this
+resource, taking into account their eligibility for
+display. Each child is legitimate if it:</p>
+
+<ul>
+  <li>has a sort_order.</li>
+  <li>is not ignored.</li>
+</ul>
+
+<p>The returned array will be sorted by each item’s
+<code>sort_order</code>.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Array&lt;Sitemap::Resource&gt;</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>An array of
+resources.</p>
 </div>
       
     </li>
@@ -323,7 +580,7 @@ eligible for a previous/next page control.</p>
         <div class="method_details ">
   <h3 class="signature " id="resource.page_group-instance_method">
   
-    - (<tt>String</tt>) <strong>resource.page_group</strong> 
+    #<strong>resource.page_group</strong>  &#x21d2; <tt>String</tt> 
   
 
   
@@ -333,7 +590,10 @@ eligible for a previous/next page control.</p>
   <div class="discussion">
     <p>Make <code>page_group</code> available for each resource.
 Useful for for assigning classes, and/or group
-conditionals.</p>
+conditionals. The page group is the enclosing folder;
+if it’s a content index.html alone in a folder, then
+it’s the grandfather folder, in order to preserve
+topics when carrot.html becomes carrot/index.html.</p>
 
 
   </div>
@@ -364,7 +624,7 @@ conditionals.</p>
         <div class="method_details ">
   <h3 class="signature " id="resource.page_name-instance_method">
   
-    - (<tt>String</tt>) <strong>resource.page_name</strong> 
+    #<strong>resource.page_name</strong>  &#x21d2; <tt>String</tt> 
   
 
   
@@ -373,7 +633,11 @@ conditionals.</p>
 </h3><div class="docstring">
   <div class="discussion">
     <p>Make <code>page_name</code> available for each resource. This is
-the file’s base name after any renaming has occurred.
+the file’s base name after any renaming has occurred,
+unless the file is a content index.html, in which
+case the name is the name of the containing folder.
+This ensures we keep the same name for cases such as
+carrot.html or carrot/index.html.
 Useful for assigning classes, etc.</p>
 
 
@@ -405,7 +669,7 @@ Useful for assigning classes, etc.</p>
         <div class="method_details ">
   <h3 class="signature " id="resource.page_sequence-instance_method">
   
-    - (<tt>Integer</tt>, <tt>Nil</tt>) <strong>resource.page_sequence</strong> 
+    #<strong>resource.page_sequence</strong>  &#x21d2; <tt>Integer</tt>, <tt>Nil</tt> 
   
 
   
@@ -448,7 +712,7 @@ this resource among its brethren.</p>
         <div class="method_details ">
   <h3 class="signature " id="resource.parent-instance_method">
   
-    - (<tt>Sitemap::Resource</tt>) <strong>resource.parent</strong> 
+    #<strong>resource.parent</strong>  &#x21d2; <tt>Sitemap::Resource</tt> 
   
 
   
@@ -491,7 +755,7 @@ the resource’s parent.</p>
         <div class="method_details ">
   <h3 class="signature " id="resource.sort_order-instance_method">
   
-    - (<tt>Integer</tt>) <strong>resource.sort_order</strong> 
+    #<strong>resource.sort_order</strong>  &#x21d2; <tt>Integer</tt> 
   
 
   
@@ -531,6 +795,47 @@ within its group, or 0 if no sort order was applied.</p>
   
 </ul>
 
+</div>
+</div>
+      
+        <div class="method_details ">
+  <h3 class="signature " id="resource.word_frequencies-instance_method">
+  
+    #<strong>resource.word_frequencies</strong>  &#x21d2; <tt>Hash</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    <p>Returns the word frequency hash for the content of 
+the resource.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+<p class="tag_title">Returns:</p>
+<ul class="return">
+  
+    <li>
+      
+      
+        <span class='type'>(<tt>Hash</tt>)</span>
+      
+      
+      
+        &mdash;
+        <div class='inline'><p>The :word =&gt; frequency content of the
+resource.</p>
+</div>
+      
+    </li>
+  
+</ul>
+
 </div>
 </div>