remaining CLI help messages & tweaks

15 files changed, 60 insertions, 12 deletions

diff --git a/src/page/album-commentary.js b/src/page/album-commentary.js
index 74eee2b..5ac6cd2 100644
--- a/src/page/album-commentary.js
+++ b/src/page/album-commentary.js
@@ -4,6 +4,8 @@ import {generateAlbumExtrasPageNav} from './album.js';
 import {accumulateSum} from '../util/sugar.js';
 import {filterAlbumsByCommentary} from '../util/wiki-data.js';
 
+export const description = `per-album artist commentary pages & index`
+
 export function condition({wikiData}) {
   return filterAlbumsByCommentary(wikiData.albumData).length;
 }
diff --git a/src/page/album.js b/src/page/album.js
index 906c02e..90f6afa 100644
--- a/src/page/album.js
+++ b/src/page/album.js
@@ -12,6 +12,8 @@ import {
   getTotalDuration,
 } from '../util/wiki-data.js';
 
+export const description = `per-album info & track artwork gallery pages`;
+
 export function targets({wikiData}) {
   return wikiData.albumData;
 }
diff --git a/src/page/artist-alias.js b/src/page/artist-alias.js
index e2b1604..f867d12 100644
--- a/src/page/artist-alias.js
+++ b/src/page/artist-alias.js
@@ -1,6 +1,8 @@
 // Artist alias redirect pages.
 // (Makes old permalinks bring visitors to the up-to-date page.)
 
+export const description = `redirects for aliased artist names`;
+
 export function targets({wikiData}) {
   return wikiData.artistAliasData;
 }
diff --git a/src/page/artist.js b/src/page/artist.js
index 235fe11..af0c7c4 100644
--- a/src/page/artist.js
+++ b/src/page/artist.js
@@ -15,6 +15,8 @@ import {
   sortChronologically,
 } from '../util/wiki-data.js';
 
+export const description = `per-artist info & artwork gallery pages`;
+
 export function targets({wikiData}) {
   return wikiData.artistData;
 }
diff --git a/src/page/flash.js b/src/page/flash.js
index 8cffdcd..8cd8dcd 100644
--- a/src/page/flash.js
+++ b/src/page/flash.js
@@ -3,6 +3,8 @@
 import {empty} from '../util/sugar.js';
 import {getFlashLink} from '../util/wiki-data.js';
 
+export const description = `flash & game pages`;
+
 export function condition({wikiData}) {
   return wikiData.wikiInfo.enableFlashesAndGames;
 }
diff --git a/src/page/group.js b/src/page/group.js
index 6bfd153..54a8358 100644
--- a/src/page/group.js
+++ b/src/page/group.js
@@ -9,6 +9,8 @@ import {
   sortChronologically,
 } from '../util/wiki-data.js';
 
+export const description = `per-group info & album gallery pages`;
+
 export function targets({wikiData}) {
   return wikiData.groupData;
 }
diff --git a/src/page/homepage.js b/src/page/homepage.js
index cb1e1da..9722f10 100644
--- a/src/page/homepage.js
+++ b/src/page/homepage.js
@@ -11,6 +11,8 @@ import {
   getNewReleases,
 } from '../util/wiki-data.js';
 
+export const description = `main wiki homepage`;
+
 export function writeTargetless({wikiData}) {
   const {newsData, homepageLayout, wikiInfo} = wikiData;
 
diff --git a/src/page/listing.js b/src/page/listing.js
index dce3852..37f4d15 100644
--- a/src/page/listing.js
+++ b/src/page/listing.js
@@ -12,6 +12,8 @@ import {empty} from '../util/sugar.js';
 
 import {getTotalDuration} from '../util/wiki-data.js';
 
+export const description = `wiki-wide listing pages & index`;
+
 export function condition({wikiData}) {
   return wikiData.wikiInfo.enableListings;
 }
diff --git a/src/page/news.js b/src/page/news.js
index 61a52dc..e042e8a 100644
--- a/src/page/news.js
+++ b/src/page/news.js
@@ -1,5 +1,7 @@
 // News entry & index page specifications.
 
+export const description = `per-entry news pages & index`;
+
 export function condition({wikiData}) {
   return wikiData.wikiInfo.enableNews;
 }
diff --git a/src/page/static.js b/src/page/static.js
index 1689d16..2da71b7 100644
--- a/src/page/static.js
+++ b/src/page/static.js
@@ -2,6 +2,8 @@
 // wiki data folder, used for a variety of purposes, e.g. wiki info,
 // changelog, and so on.)
 
+export const description = `static wiki-wide content pages specified in data`;
+
 export function targets({wikiData}) {
   return wikiData.staticPageData;
 }
diff --git a/src/page/tag.js b/src/page/tag.js
index da4f194..ee62038 100644
--- a/src/page/tag.js
+++ b/src/page/tag.js
@@ -1,5 +1,7 @@
 // Art tag page specification.
 
+export const description = `per-artwork-tag gallery pages`;
+
 export function condition({wikiData}) {
   return wikiData.wikiInfo.enableArtTagUI;
 }
diff --git a/src/page/track.js b/src/page/track.js
index 94c9c40..495bf42 100644
--- a/src/page/track.js
+++ b/src/page/track.js
@@ -18,6 +18,8 @@ import {
   sortChronologically,
 } from '../util/wiki-data.js';
 
+export const description = `per-track info pages`;
+
 export function targets({wikiData}) {
   return wikiData.trackData;
 }
diff --git a/src/upd8.js b/src/upd8.js
index a1a499d..3bcdf88 100755
--- a/src/upd8.js
+++ b/src/upd8.js
@@ -58,7 +58,7 @@ import {findFiles} from './util/io.js';
 import link from './util/link.js';
 import {isMain} from './util/node-utils.js';
 import {validateReplacerSpec} from './util/replacer.js';
-import {empty, showAggregate} from './util/sugar.js';
+import {empty, showAggregate, withEntries} from './util/sugar.js';
 import {replacerSpec} from './util/transform-content.js';
 import {generateURLs} from './util/urls.js';
 import {sortByName} from './util/wiki-data.js';
@@ -104,9 +104,11 @@ async function main() {
   const defaultQueueSize = 500;
 
   const buildModeFlagOptions = (
-    Object.fromEntries(
-      Object.keys(buildModes)
-        .map(key => [key, {type: 'flag'}])));
+    withEntries(buildModes, entries =>
+      entries.map(([key, mode]) => [key, {
+        help: mode.description,
+        type: 'flag',
+      }])));
 
   const selectedBuildModeFlags = Object.keys(
     await parseOptions(process.argv.slice(2), {
@@ -115,9 +117,11 @@ async function main() {
     }));
 
   let selectedBuildModeFlag;
+  let usingDefaultBuildMode;
 
   if (empty(selectedBuildModeFlags)) {
     selectedBuildModeFlag = 'static-build';
+    usingDefaultBuildMode = true;
     logInfo`No build mode specified, using default: ${selectedBuildModeFlag}`;
   } else if (selectedBuildModeFlags.length > 1) {
     logError`Building multiple modes (${selectedBuildModeFlags.join(', ')}) at once not supported.`;
@@ -125,6 +129,7 @@ async function main() {
     return;
   } else {
     selectedBuildModeFlag = selectedBuildModeFlags[0];
+    usingDefaultBuildMode = false;
     logInfo`Using specified build mode: ${selectedBuildModeFlag}`;
   }
 
@@ -148,7 +153,7 @@ async function main() {
     // and like a jillion other things too. Pretty much everything which
     // makes an individual wiki what it is goes here!
     'data-path': {
-      help: `Specify path to data directory, including YAML files that cover all info about wiki content, layout, and structure; always required for wiki building, but may be provided by the HSMUSIC_DATA environment variable instead`,
+      help: `Specify path to data directory, including YAML files that cover all info about wiki content, layout, and structure\n\nAlways required for wiki building, but may be provided via the HSMUSIC_DATA environment variable instead`,
       type: 'value',
     },
 
@@ -156,7 +161,7 @@ async function main() {
     // categorized; check out MEDIA_ALBUM_ART_DIRECTORY and other constants
     // near the top of this file (upd8.js).
     'media-path': {
-      help: `Specify path to media directory, including album artwork and additional files, as well as custom site layout media and other media files for reference or linking in wiki content; always required for wiki building, but may be provided by the HSMUSIC_MEDIA environment variable instead`,
+      help: `Specify path to media directory, including album artwork and additional files, as well as custom site layout media and other media files for reference or linking in wiki content\n\nAlways required for wiki building, but may be provided via the HSMUSIC_MEDIA environment variable instead`,
       type: 'value',
     },
 
@@ -282,7 +287,7 @@ async function main() {
           wrappedHelpLines = wrappedHelp.split('\n').length;
         }
 
-        if (wrappedHelpLines > 1 && !justInsertedPaddingLine) {
+        if (wrappedHelpLines > 0 && !justInsertedPaddingLine) {
           console.log('');
         }
 
@@ -331,7 +336,9 @@ async function main() {
     showOptions(`Build mode selection`, buildModeFlagOptions);
 
     if (buildOptions) {
-      showOptions(`Build options for --${selectedBuildModeFlag}`, buildOptions);
+      showOptions(`Build options for --${selectedBuildModeFlag} (${
+        usingDefaultBuildMode ? 'default' : 'selected'
+      })`, buildOptions);
     }
 
     return;
diff --git a/src/write/build-modes/live-dev-server.js b/src/write/build-modes/live-dev-server.js
index 81ae5b8..39229a9 100644
--- a/src/write/build-modes/live-dev-server.js
+++ b/src/write/build-modes/live-dev-server.js
@@ -25,13 +25,20 @@ import {
   generateRedirectHTML,
 } from '../page-template.js';
 
+const defaultHost = '0.0.0.0';
+const defaultPort = 8002;
+
+export const description = `Hosts a local HTTP server which generates page content as it is requested, instead of all at once; reacts to changes in data files, so new reloads will be up-to-date with on-disk YAML data (<- not implemented yet, check back soon!)\n\nIntended for local development ONLY; this custom HTTP server is NOT rigorously tested and almost certainly has security flaws`;
+
 export function getCLIOptions() {
   return {
     host: {
+      help: `Hostname to which HTTP server is bound\nDefaults to ${defaultHost}`,
       type: 'value',
     },
 
     port: {
+      help: `Port to which HTTP server is bound\nDefaults to ${defaultPort}`,
       type: 'value',
       validate(size) {
         if (parseInt(size) !== parseFloat(size)) return 'an integer';
@@ -57,8 +64,8 @@ export async function go({
   developersComment,
   getSizeOfAdditionalFile,
 }) {
-  const host = cliOptions['host'] ?? '0.0.0.0';
-  const port = parseInt(cliOptions['port'] ?? 8002);
+  const host = cliOptions['host'] ?? defaultHost;
+  const port = parseInt(cliOptions['port'] ?? defaultPort);
 
   let targetSpecPairs = getPageSpecsWithTargets({wikiData});
   const pages = progressCallAll(`Computing page data & paths for ${targetSpecPairs.length} targets.`,
diff --git a/src/write/build-modes/static-build.js b/src/write/build-modes/static-build.js
index 220e51f..fa72453 100644
--- a/src/write/build-modes/static-build.js
+++ b/src/write/build-modes/static-build.js
@@ -15,7 +15,7 @@ import {serializeThings} from '../../data/serialize.js';
 import * as pageSpecs from '../../page/index.js';
 
 import link from '../../util/link.js';
-import {empty, queue} from '../../util/sugar.js';
+import {empty, queue, withEntries} from '../../util/sugar.js';
 
 import {
   logError,
@@ -34,6 +34,8 @@ import {
 
 const pageFlags = Object.keys(pageSpecs);
 
+export const description = `Generates all page content in one build (according to the contents of data files at build time) and writes them to disk, preparing the output folder for upload and serving by any static web host\n\nIntended for any production or public-facing release of a wiki; serviceable for local development, but can be a bit unwieldy and time/CPU-expensive`;
+
 export function getCLIOptions() {
   return {
     // This is the output directory. It's the one you'll upload online with
@@ -43,6 +45,7 @@ export function getCLIOptions() {
     // couple symlinked directories, so if you're uploading, you're pro8a8ly
     // gonna want to resolve those yourself.
     'out-path': {
+      help: `Specify path to output directory, into which HTML page files and other output are written and other directories are linked\n\nAlways required alongside --static-build mode, but may be provided via the HSMUSIC_OUT environment variable instead`,
       type: 'value',
     },
 
@@ -51,12 +54,14 @@ export function getCLIOptions() {
     // the site. Not recommended for production, since it isn't guaranteed
     // 100% error-free (and index.html-style links are less pretty anyway).
     'append-index-html': {
+      help: `Apply "index.html" to the end of page links, instead of just linking to the directory (ex. "/track/ng2yu/"); useful when no local server hosting option is available and browsing build output directly off the disk drive\n\nDefinitely not intended for production: this option isn't extensively tested and may include conspicuous oddities`,
       type: 'flag',
     },
 
     // Only want to 8uild one language during testing? This can chop down
     // 8uild times a pretty 8ig chunk! Just pass a single language code.
     'lang': {
+      help: `Skip rest and build only pages for this locale language (specify a language code)`,
       type: 'value',
     },
 
@@ -65,7 +70,12 @@ export function getCLIOptions() {
     // They're here to make development quicker when you're only working
     // on some particular area(s) of the site rather than making changes
     // across all of them.
-    ...Object.fromEntries(pageFlags.map((key) => [key, {type: 'flag'}])),
+    ...withEntries(pageSpecs, entries => entries.map(
+      ([key, spec]) => [key, {
+        help: spec.description &&
+          `Skip rest and build only:\n${spec.description}`,
+        type: 'flag',
+      }])),
   };
 }