Merge pull request #2378 from keymanapp/auto/A19S18-merge-master-into-staging

auto: A19S18 merge master into staging

Author: keyman-status

_includes/includes/index-content.php

@@ -1,13 +1,50 @@
 <?php
 
+/**
+ * Sort the list of file titles according to the predefined order in
+ * __index.txt. If a filename in __index.txt is prefixed with a hyphen (-), then
+ * exclude it from the list. If a filename is missing from __index.txt, it will
+ * be appended to the bottom of the list.
+ */
+function get_file_titles_by_index($base, $unsorted_items) {
+  $order = str_replace("\r\n", "\n", @file_get_contents($base.'__index.txt'));
+  $order = explode("\n", $order);
+  foreach($order as $item) {
+    if(substr($item, 0, 1) == '-') {
+      // remove the item from the list
+      $item = substr($item, 1);
+      if(array_key_exists($item, $unsorted_items)) {
+        $unsorted_items[$item] = '';
+      }
+    }
+    else if(array_key_exists($item, $unsorted_items)) {
+      $items[$item] = $unsorted_items[$item];
+      $unsorted_items[$item] = '';
+    }
+  }
+
+  asort($unsorted_items, SORT_FLAG_CASE|SORT_STRING);
+  foreach($unsorted_items as $item => $title) {
+    if($title != '') {
+      $items[$item] = $title;
+    }
+  }
+  return $items;
+}
+
 function get_file_titles($base) {
+  $hasIndex = false;
   $files = glob($base.'*');
   $items = array(); $dirs = array();
   foreach($files as $file) {
     $basefile = basename($file);
     if($basefile == '.' || $basefile == '..') {
       continue;
     }
+    if($basefile == '__index.txt') {
+      $hasIndex = true;
+      continue;
+    }
     if($basefile == '_nav.php' || $basefile == 'index.php' || $basefile == 'index.md') {
       continue;
     }
@@ -37,6 +74,10 @@ function get_file_titles($base) {
     }
   }
 
+  if($hasIndex) {
+    return get_file_titles_by_index($base, $items + $dirs);
+  }
+
   asort($items, SORT_FLAG_CASE|SORT_STRING);
   asort($dirs, SORT_FLAG_CASE|SORT_STRING);
 

developer/19.0/guides/develop/tutorial/step-1.md

@@ -62,10 +62,10 @@ accent, and one for the vowel.
 | `Â, â, ...` | caret (<kbd>^</kbd>), then the vowel key.          |
 | `Ä, ä, ...` | double-quote (<kbd>"</kbd>), then the vowel key.   |
 | `Ç, ç`      | quote (<kbd>'</kbd>), then lower- or uppercase C.  |
-| `«, »`      | two less-than (<kbd>&lt;&lt;</kbd>) or greater-than (<kbd>&gt;&gt;</kbd>) symbols. |
+| `«, »`      | two less-than (<kbd>&lt;</kbd><kbd>&lt;</kbd>) or greater-than (<kbd>&gt;</kbd><kbd>&gt;</kbd>) symbols. |
 
 Now that we have decided which character to use and how the user can
 enter them, we can start to write the keyboard.
 
 -   [Continue with Step 2: Writing the Header](step-2)
--   [Back to the Introduction](index)
+-   [Back to the Introduction](index)

developer/19.0/reference/api/index.md

@@ -6,15 +6,101 @@
 
 ## Packages
 
-|  Package | Description |
-|  --- | --- |
-|  [@keymanapp/kmc-analyze](./kmc-analyze.md) | kmc-analyze - keyboard analysis classes, including tools for <code>&amp;displayMap</code>. |
-|  [@keymanapp/kmc-copy](./kmc-copy.md) |  |
-|  [@keymanapp/kmc-generate](./kmc-generate.md) |  |
-|  [@keymanapp/kmc-keyboard-info](./kmc-keyboard-info.md) |  |
-|  [@keymanapp/kmc-kmn](./kmc-kmn.md) | kmc-kmn - Keyman keyboard compiler |
-|  [@keymanapp/kmc-ldml](./kmc-ldml.md) |  |
-|  [@keymanapp/kmc-model](./kmc-model.md) |  |
-|  [@keymanapp/kmc-model-info](./kmc-model-info.md) |  |
-|  [@keymanapp/kmc-package](./kmc-package.md) |  |
+<table><thead><tr><th>
+
+Package
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[@keymanapp/kmc-analyze](./kmc-analyze.md)
+
+
+</td><td>
+
+kmc-analyze - keyboard analysis classes, including tools for `&displayMap`<!-- -->.
+
+
+</td></tr>
+<tr><td>
+
+[@keymanapp/kmc-copy](./kmc-copy.md)
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+[@keymanapp/kmc-generate](./kmc-generate.md)
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+[@keymanapp/kmc-keyboard-info](./kmc-keyboard-info.md)
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+[@keymanapp/kmc-kmn](./kmc-kmn.md)
+
+
+</td><td>
+
+kmc-kmn - Keyman keyboard compiler
+
+
+</td></tr>
+<tr><td>
+
+[@keymanapp/kmc-ldml](./kmc-ldml.md)
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+[@keymanapp/kmc-model](./kmc-model.md)
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+[@keymanapp/kmc-model-info](./kmc-model-info.md)
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+[@keymanapp/kmc-package](./kmc-package.md)
+
+
+</td><td>
+
+
+</td></tr>
+</tbody></table>
 

developer/19.0/reference/api/kmc-analyze.analyzeoskcharacteruse._constructor_.md

@@ -14,8 +14,51 @@ constructor(callbacks: CompilerCallbacks, options?: AnalyzeOskCharacterUseOption
 
 ## Parameters
 
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  callbacks | CompilerCallbacks |  |
-|  options | [AnalyzeOskCharacterUseOptions](./kmc-analyze.analyzeoskcharacteruseoptions.md) | _(Optional)_ |
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+callbacks
+
+
+</td><td>
+
+CompilerCallbacks
+
+
+</td><td>
+
+
+</td></tr>
+<tr><td>
+
+options
+
+
+</td><td>
+
+[AnalyzeOskCharacterUseOptions](./kmc-analyze.analyzeoskcharacteruseoptions.md)
+
+
+</td><td>
+
+_(Optional)_
+
+
+</td></tr>
+</tbody></table>
 

developer/19.0/reference/api/kmc-analyze.analyzeoskcharacteruse.analyze.md

@@ -16,9 +16,39 @@ analyze(file: string): Promise<boolean>;
 
 ## Parameters
 
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  file | string | relative or absolute path to a Keyman source file |
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+file
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+relative or absolute path to a Keyman source file
+
+
+</td></tr>
+</tbody></table>
 
 **Returns:**
 

developer/19.0/reference/api/kmc-analyze.analyzeoskcharacteruse.getstrings.md

@@ -22,9 +22,39 @@ getStrings(format?: '.txt' | '.md' | '.json'): string[];
 
 ## Parameters
 
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  format | '.txt' \| '.md' \| '.json' | _(Optional)_ file format to return - can be '.txt', '.md', or '.json' |
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+format
+
+
+</td><td>
+
+'.txt' \| '.md' \| '.json'
+
+
+</td><td>
+
+_(Optional)_ file format to return - can be '.txt', '.md', or '.json'
+
+
+</td></tr>
+</tbody></table>
 
 **Returns:**