Scripts Reference

Table of contents

Introduction

The app and documentation build process relies on several custom scripts written in various languages. The NodeJS scripts rely on the following npm packages, also recorded in the package.json in the project root:

Install them as follows:

npm install commander path png-to-ico puppeteer sharp xml2js

These packages may have other dependencies that depend on your operating system. Please see the package documentation.

Icon and splash screen generation

The <code>generateFavicon.js</code>, <code>generateIcon.js</code>, and <code>generateSplash.js</code> scripts are intended to generate the icons, favicons, and splash screens for POH Performance app with very little effort. ALl the tweaking of each icon and splash screen layout is avoided. The scripts all use puppeteer to build a web page for the requested image and snapshot the result to create the requested image file. The image is programmatically adjusted to meet padding or other formatting constraints. The technique will allow other programmatic tweaking in the future.

buildAirportDB.js

Builds the airport database for an app. See the Airport Database Reference. If no options are specified then all runway surfaces except water are included.

Arguments

Output

An airport database file in JSON format. See the Airport Database Reference.

buildConfigIcons.js

Usage

node buildConfigIcons.js <configFile>

This script automatically builds the icons and splash screens used by the specified Cordova config.xml file. It expects XML comments of the form <!-- iconArgs="<args>" ---> or <!-- splashArgs="<args>" --->on the same line following any <icon> or <splash> elements defining an icon or splash screen in the config.xml file. It will record the src file name in the element and the args string in the comment and call generateIcon.js or generateSplash.js with the src filename and specified args string to generate the output.

The script also detects XML comments of the form <!-- globalIconArgs="<args>" ---> or <!-- globalSplashArgs="<args>" --->. These will add the specified argument string to any iconArgs or splashArgs comments associated with individual <icon> or <splash> elements. Here's an example of the icon and splash screen portion of a config.xml file:

<!-- globalIconArgs="-t1 C182 -t2 Performance" -->
<!-- globalSplashArgs="-t1 C182 -t2 Performance -i logoImage.png" -->

<!-- android properties -->
<platform name="android">
	<icon src="res/icon/android/ldpi.png" density="ldpi" /> <!-- iconArgs="-s 36" -->
	<icon src="res/icon/android/hdpi.png" density="hdpi" /> <!-- iconArgs="-s 72" -->
	<splash src="res/screen/android/port-ldpi.png" density="port-ldpi" /> <!-- splashArgs="-w 200 -h 320 -p 28" -->
	<splash src="res/screen/android/port-hdpi.png" density="port-hdpi" /> <!-- splashArgs="-w 480 -h 800 -p 28" -->
</platform>

<!-- IOS properties -->
<platform name="ios">
	<icon src="res/icon/ios/icon-60.png" width="60" height="60" /> <!-- iconArgs="-s 60" -->
	<icon src="res/icon/ios/icon-167.png" width="167" height="167" /> <!-- iconArgs="-s 167" -->
	<!-- storyboard splash screens -->
	<splash src="res/screen/ios/Default@2x~iphone~anyany.png" />	<!-- splashArgs="-w 1334 -h 1334 -p 28" -->
	<splash src="res/screen/ios/Default@2x~ipad~anyany.png" />		<!-- splashArgs="-w 2732 -h 2732 -p 28" -->
</platform>

Calling generateIcon.js with this file will generate the following icons and splash screens:

Arguments

buildIndexIcons.js

Usage

node buildIndexIcons.js <indexFile>

This script automatically builds the icons and favicons used by the specified index.html file and any associated PWA manifest.json file. In the index.html file, it expects HTML comments of the form <!-- iconArgs="<args>" ---> or <!-- faviconArgs="<args>" ---> on the same line following any <link> elements with rel="icon" or rel="apple-touch-icon" in the index.html file. It will record the href file name in the element and the args string in the comment and call generateIcon.js or generateFavicon.js with the href filename and specified args string to generate the output.

The script also detects HTML comments of the form <!-- globalIconArgs="<args>" --->, which will add the specified argument string to any iconArgs or faviconArgs comments associated with individual <link> elements. Here's an example of the icon portion of an index.html file:

<!-- globalIconArgs="-t1 C182 -t2 Performance" -->
<!-- faviconGlobalArgs="-t1 C182 -t2 Performance" -->
<link rel="icon" href="buildStamp/image/favicon.ico" /> <!-- faviconArgs="" -->
<link rel="apple-touch-icon" href="buildStamp/image/icon-192.png" /> <!-- iconArgs="-s 192" -->

Calling generateIcon.js with this file will generate the following icons and splash screens:

Arguments

checkMdLinks.js

Usage

node checkMdLinks.js <mdFile>

This script checks that the links within the <mdFile> Markdown file point to valid target files and anchors.

Arguments

generateFavicon.js

Usage

node generateFavicon.js -o <file> -t1 <text1> [options]

This script generates an ICO favicon file containing multiple icon images of different sizes. The icon images can have one or two lines of text and a specified background color. The text will be automatically scaled so that the icon box has a specified padding. The default padding is 10% of the width. Each image is equal in width and height and may have rounded corners.

The default icon sizes are 16, 32, 48, 64, 128, and 256 pixels. For better readability, icons less than 64 pixels will only contain the first line.

Arguments

generateIcon.js

Usage

node generateIcon.js -o <file> -t1 <text1> [options]

This script generates a PNG icon file. The icon can have one or two lines of text and a specified background color. The text will be automatically scaled so the icon box has a specified padding. The default padding is 10% of the width. Each image is equal in width and height and may have rounded corners.

Arguments

generateSplash.js

Usage

node generateSplash.js -o <file> -t1 <text1> -w <width> -h <height> [options]

This script generates a PNG splash screen file of the specified width and height in pixels. The icon can have one or two lines of text, an optional image, and a specified background color.

The text and image will be automatically scaled so the icon box has a specified padding. The image will have the same width as the largest line of text and both will be scaled to fit the area inside the padding.

Arguments

mdToToc.js

Usage

node mdToToc.js <mdFile>

This script generates a Table of Contents in the <mdFile> Markdown file. The script looks for the following marker comments to delineate where to insert the Table of Contents:

The first time the script is run, it inserts the generated TOC between the markers. When the file is updated and the script is re-run, it deletes the content between the markers before generating and inserting a new TOC.

By default, the script will index all headers including the heading for the Table of Contents. You can prevent indexing by adding `` at the end of the line containing a heading that should not be indexed. The script will also look for a comment of the form <!-- toc opts:[string] -->. The [string] contains a comma-separated list of heading levels to index. All other heading levels will be omitted from the TOC. For example, a line containing <!-- toc opts:h2,h3 --> will restrict indexing to only heading levels 2 and 3.

The index is a simple list containing a link to the specified section that contains the section name. Here's an example from this page:

<!-- toc opts:h2,h3 -->
# Scripts Reference  <!-- index="Documents --><!-- omit from toc" -->

## Related documents 
* [Development, Debugging, and Troubleshooting](development.md)

## Table of contents 
<!-- toc start -->
* [Introduction](#introduction)
* [<code>buildAirportDB.js</code>](#buildairportdbjs)
* [<code>generateIcon.js</code>](#generateiconjs)
* [<code>buildConfigIcons.js</code>](#buildconfigiconsjs)
* [<code>buildIndexIcons.js</code>](#buildindexiconsjs)
* [<code>checkMdLinks.js</code>](#checkmdlinksjs)
* [<code>generateFavicon.js</code>](#generatefaviconjs)
* [<code>generateIcon.js</code>](#generateiconjs)
* [<code>generateSplash.js</code>](#generatesplashjs)
* [<code>mdToToc.js</code>](#mdtotocjs)
* [<code>mdToHtml.js</code>](#mdtohtmljs)
* [<code>mdToIndex.js</code>](#mdtoindexjs)
<!-- toc end -->

---
## Introduction
...

Arguments

mdToHtml.js

Usage

node mdToHtml.js -i <inputMdFile> -o <outputHtmlFile> [options]
node mdToHtml.js [options] < <inputMdFile> > <outputMdFile>

This script converts a Markdown file to an HTML file. The input Markdown can use GFM format. The input Markdown file can be on stdin or it can be specified using -i <inputMdFile>. Similarly the output file can be sent to stdout or it can be specified using -o <outputMdFile>. If a -c <cssFile> argument is provided, then the specified CSS file will be linked in the output HTML.

Arguments

mdToIndex.js

Usage

node mdToIndex.js [options]

This script generates an alphabetic or category index of Markdown files in a specified directory to stdout. It searches all files with a .md extension in the directory. The -a option specifies that an alphabetic index is to be generated. Otherwise, a category and sub-category index is generated.

The alphabetic index is a simple list with links to the indexed files and anchors. The category and sub-category index is an index of ### (h3) elements with the category name and #### (h4) subcategories, which contain a list of all the indexed items underneath. The categories, subcategories, and indexed lists are sorted alphabetically.

The script searches each Markdown file for comments of the form:

# <headingText> `<!-- index="<category>:<subcategory>" -->`

The heading can be at any level, but the comment must follow on the same line. This will generate a list item with a link containing the <headingText> with the file and heading as the target and anchor. The list item will be sorted into the alphabetic list when requested or placed in the correct sub-category list when a categorized list is requested.

The script also searches each Markdown file for comments of the form:

<!-- target="<targetText>" index="<category>:<subcategory>" -->

This will create a link to this file using <targetText> for the link text. This will add the link to both the alphabetical and category indexes. The latter will be under the requested <category> and <subcategory>.

The script is intended to be used by a build environment to create a Markdown file containing an index of the indexed Markdown targets in a directory. The build environment must create the surrounding elements and then use this script to generate the index contents where desired.

Arguments