use single-quotes in md2html.cfg comments
Using single-quotes in md2html.cfg comments will make it easier to include some of that information in the any usage string, or related documentation.
This commit is contained in:
Landon Curt Noll committed
1 parent
f16ff5bcfe
commit
71e84553cc
1 file changed
+68
-68
+68
-68
@@ -11,8 +11,8 @@
|
||||
#
|
||||
# file_glob [cfg_options ..]
|
||||
#
|
||||
# where "file_glob" is a Bash Extended Glob (not a regular expression).
|
||||
# and where "cfg_options .." are zero or more configuration file options.
|
||||
# where 'file_glob' is a Bash Extended Glob (not a regular expression).
|
||||
# and where 'cfg_options ..' are zero or more configuration file options.
|
||||
#
|
||||
# File paths are evaluated from under the top of the repo. A leading / in a file_glob
|
||||
# is assumed to be under the topdir directory.
|
||||
@@ -22,19 +22,19 @@
|
||||
# https://www.linuxjournal.com/content/bash-extended-globbing
|
||||
# https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html
|
||||
#
|
||||
# For a given file, the first "file_glob" Bash Extended Glob that matches is used.
|
||||
# If no "file_glob" matches, the file is ignored.
|
||||
# For a given file, the first 'file_glob' Bash Extended Glob that matches is used.
|
||||
# If no 'file_glob' matches, the file is ignored.
|
||||
#
|
||||
# Any "options.." are processed between the options from the command line
|
||||
# Any 'options..' are processed between the options from the command line
|
||||
# and any filename arguments on the command line. For example:
|
||||
#
|
||||
# command [command_options ..] [cfg_options ..] [output_tool_options ..] [--] [filename_arg ..]
|
||||
#
|
||||
# Here the "command" first processes any command line options, then
|
||||
# it processes "cfg_options" obtained from this file from a 1st match of a given file_glob, then
|
||||
# it processes "output tool" (i.e., -o tool) options found in "command_options", and "cfg_options", then
|
||||
# Here the 'command' first processes any command line options, then
|
||||
# it processes 'cfg_options' obtained from this file from a 1st match of a given file_glob, then
|
||||
# it processes 'output tool' (i.e., -o tool) options found in 'command_options', and 'cfg_options', then
|
||||
# an optional -- (end of all options), then
|
||||
# zero of more "filename_arg" filename arguments.
|
||||
# zero of more 'filename_arg' filename arguments.
|
||||
|
||||
##################
|
||||
# import options #
|
||||
@@ -50,102 +50,102 @@
|
||||
# -n go thru the actions, but do not update any files (def: do the action)
|
||||
# -N do not process file, just ignore the file (def: process the file)
|
||||
#
|
||||
# -d topdir set topdir (def: if "git rev-parse --is-inside-work-tree" is true, then
|
||||
# topdir is output of "git rev-parse --show-toplevel")
|
||||
# -D def "def" is default HTML phase name (def: "default" is default phase name)
|
||||
# -d topdir set topdir (def: if 'git rev-parse --is-inside-work-tree' is true, then
|
||||
# topdir is output of 'git rev-parse --show-toplevel')
|
||||
# -D def 'def' is default HTML phase name (def: 'default' is default phase name)
|
||||
#
|
||||
# -i inc inc files are located under topdir/inc (def: inc files are under topdir/inc)
|
||||
#
|
||||
# -c md2html.cfg Use md2html.cfg as the configuration file (def: use inc/md2html.cfg)
|
||||
# -C dir cd dir (def: if "git rev-parse --is-inside-work-tree" is true, then
|
||||
# cd to the output of "git rev-parse --show-cdup")
|
||||
# -C dir cd dir (def: if 'git rev-parse --is-inside-work-tree' is true, then
|
||||
# cd to the output of 'git rev-parse --show-cdup')
|
||||
#
|
||||
# -H phase=name use "phase.name.html" file for HTML phase named "phase" (def: use "phase.default.html")
|
||||
# -H phase=. ignore processing for HTML phase "phase" (def: process HTML phase)
|
||||
# NOTE: The "phase" string may not contain = (equal), nor / (slash).
|
||||
# NOTE: The "phase.name.html" file is assumed under the "topdir/inc" directory.
|
||||
# -H phase=name use 'phase.name.html' file for HTML phase named 'phase' (def: use 'phase.default.html')
|
||||
# -H phase=. ignore processing for HTML phase 'phase' (def: process HTML phase)
|
||||
# NOTE: The 'phase' string may not contain = (equal), nor / (slash).
|
||||
# NOTE: The 'phase.name.html' file is assumed under the 'topdir/inc' directory.
|
||||
#
|
||||
# -b tool run "before tool" during HTML phase number 20 (def: do not output before pandoc tool)
|
||||
# -b tool run 'before tool' during HTML phase number 20 (def: do not output before pandoc tool)
|
||||
# -b . skip HTML phase number 20 (def: do nothing during HTML phase number 20)
|
||||
# -B optstr run "before tool" with options found in "optstr" (def: do not add any options to "before tool")
|
||||
# -B optstr run 'before tool' with options found in 'optstr' (def: do not add any options to 'before tool')
|
||||
#
|
||||
# -p tool path to "pandoc tool" wrapper used in HTML phase number 21 is "tool" (def: use inc/pandoc.sh)
|
||||
# -p tool path to 'pandoc tool' wrapper used in HTML phase number 21 is 'tool' (def: use inc/pandoc.sh)
|
||||
# -p . skip HTML phase number 21 (def: do nothing during HTML phase number 21)
|
||||
# NOTE: The "tool" is a "pandoc tool" wrapper tool, NOT the path to the actual pandoc application.
|
||||
# -P optstr run "pandoc tool" with options found in "optstr" (def: use only the "pandoc tool" default options)
|
||||
# NOTE: The 'tool' is a 'pandoc tool' wrapper tool, NOT the path to the actual pandoc application.
|
||||
# -P optstr run 'pandoc tool' with options found in 'optstr' (def: use only the 'pandoc tool' default options)
|
||||
#
|
||||
# -a tool run "after tool" during HTML phase number 20 (def: do not output after pandoc tool)
|
||||
# -a tool run 'after tool' during HTML phase number 20 (def: do not output after pandoc tool)
|
||||
# -a . skip HTML phase number 22 (def: do nothing during HTML phase number 22)
|
||||
# -A optstr run "after tool" with options found in "optstr" (def: do not add any options to "after tool")
|
||||
# -A optstr run 'after tool' with options found in 'optstr' (def: do not add any options to 'after tool')
|
||||
#
|
||||
# -s token=value substitute %%token%% with value except in HTML phase numbers 20-29 (def: do not substitute any tokens)
|
||||
# NOTE: The "token" string may not contain ; (semicolon), nor = (equal), nor % (percent).
|
||||
# NOTE: The "value" string may not contain ; (semicolon).
|
||||
# NOTE: The 'token' string may not contain ; (semicolon), nor = (equal), nor % (percent).
|
||||
# NOTE: The 'value' string may not contain ; (semicolon).
|
||||
# -S failure to replace a %%token%% is not an error (def: exit non-zero for non-substituted tokens)
|
||||
#
|
||||
# -o tool Use output tool, "tool", to generate option lines (def: do not)
|
||||
# -o . disable use of "output tool" (def: do not use an "output tool")
|
||||
# -O tool=optstr run the "token replace" named "tool" with options found in "optstr" (def: do not add any options)
|
||||
# NOTE: The "tool" string may not contain = (equal), nor double-quote, nor single-quote.
|
||||
# -o tool Use output tool, 'tool', to generate option lines (def: do not)
|
||||
# -o . disable use of 'output tool' (def: do not use an 'output tool')
|
||||
# -O tool=optstr run the 'token replace' named 'tool' with options found in 'optstr' (def: do not add any options)
|
||||
# NOTE: The 'tool' string may not contain = (equal), nor double-quote, nor single-quote.
|
||||
#
|
||||
# -e exitcode force exit with exitcode (def: exit based on success or failure of the action)
|
||||
# -E string output string, followed by newline, to stderr (def: do not)
|
||||
#
|
||||
# The output from "before tool" (unless -b .) will be used in HTML phase number 20 (before pandoc processing).
|
||||
# The output from "pandoc tool" (unless -p .) will be used HTML phase number 21 (pandoc processing).
|
||||
# The output from "after tool" (unless -a .) will be used in HTML phase number 22 (after pandoc processing).
|
||||
# The output from 'before tool' (unless -b .) will be used in HTML phase number 20 (before pandoc processing).
|
||||
# The output from 'pandoc tool' (unless -p .) will be used HTML phase number 21 (pandoc processing).
|
||||
# The output from 'after tool' (unless -a .) will be used in HTML phase number 22 (after pandoc processing).
|
||||
#
|
||||
# When the "before tool" (i.e., -b tool) is executed, it is given options found in the most recent
|
||||
# "optstr" (i.e., -B optstr), followed by "--", and ending in the path from the topdir
|
||||
# to the file that matched the "file_glob".
|
||||
# When the 'before tool' (i.e., -b tool) is executed, it is given options found in the most recent
|
||||
# 'optstr' (i.e., -B optstr), followed by '--', and ending in the path from the topdir
|
||||
# to the file that matched the 'file_glob'.
|
||||
#
|
||||
# When the "pandoc tool" (i.e., -p tool) is executed, it is given options found in the most recent
|
||||
# "optstr" (i.e., -P optstr), followed by "--", and ending in the path from the topdir
|
||||
# to the file that matched the "file_glob".
|
||||
# When the 'pandoc tool' (i.e., -p tool) is executed, it is given options found in the most recent
|
||||
# 'optstr' (i.e., -P optstr), followed by '--', and ending in the path from the topdir
|
||||
# to the file that matched the 'file_glob'.
|
||||
#
|
||||
# When the "after tool" (i.e., -a tool) is executed, it is given options found in the most recent
|
||||
# "optstr" (i.e., -A optstr), followed by "--", and ending in the path from the topdir
|
||||
# to the file that matched the "file_glob".
|
||||
# When the 'after tool' (i.e., -a tool) is executed, it is given options found in the most recent
|
||||
# 'optstr' (i.e., -A optstr), followed by '--', and ending in the path from the topdir
|
||||
# to the file that matched the 'file_glob'.
|
||||
#
|
||||
# When the "options tool" (i.e., -o tool) is executed, it is given any options found in the most recent
|
||||
# "optstr" associated with "tool" (i.e., -O tool=option), followed by "--", and ending in the path from the topdir
|
||||
# to the file that matched the "file_glob".
|
||||
# When the 'options tool' (i.e., -o tool) is executed, it is given any options found in the most recent
|
||||
# 'optstr' associated with 'tool' (i.e., -O tool=option), followed by '--', and ending in the path from the topdir
|
||||
# to the file that matched the 'file_glob'.
|
||||
#
|
||||
# If the "tool" path (for -b tool, -p tool, -a tool, -o tool) is not an absolute path, then it is assumed to be under topdir.
|
||||
# If the "tool" path is "." (dot), then the use of the given tool is ignored.
|
||||
# If the 'tool' path (for -b tool, -p tool, -a tool, -o tool) is not an absolute path, then it is assumed to be under topdir.
|
||||
# If the 'tool' path is '.' (dot), then the use of the given tool is ignored.
|
||||
#
|
||||
# The "optstr" is a quoted string of command line options to used with the respective tool.
|
||||
# The 'optstr' is a quoted string of command line options to used with the respective tool.
|
||||
# The command line options for the tool specific to the given tool and are not necessarily
|
||||
# the command line options listed above.
|
||||
#
|
||||
# The command options are evaluated in the following getopt phases:
|
||||
#
|
||||
# 0. collect command line options, up to but not including any "--" or up to the command line filename argument(s)
|
||||
# 0. collect command line options, up to but not including any '--' or up to the command line filename argument(s)
|
||||
# 0a. ((evaluate all getopt phase 0 options))
|
||||
#
|
||||
# 1. collect "cfg_options" from the first md2html.cfg line where "file_glob" matched the filename argument
|
||||
# 1. collect 'cfg_options' from the first md2html.cfg line where 'file_glob' matched the filename argument
|
||||
# 1a. ((evaluate all getopt phase 1 options))
|
||||
#
|
||||
# 2. collect output of "-o tool" from getopt phase 0a and then from getopt phase 1a, in the order collected
|
||||
# 2a. ((evaluate all getopt phase 2 options, except that any new "-o tool" are ignored))
|
||||
# 2. collect output of '-o tool' from getopt phase 0a and then from getopt phase 1a, in the order collected
|
||||
# 2a. ((evaluate all getopt phase 2 options, except that any new '-o tool' are ignored))
|
||||
#
|
||||
# Command line options are evaluated in order, during each getopt phase (i.e., getopt phase 0a, then 1a, phase 2a).
|
||||
#
|
||||
# The "-o tool" should NOT output any "-o tool" options as "-o tool" is NOT RECURSIVE.
|
||||
# Command line options output from a "-o tool" are accumulated for getopt phase 2,
|
||||
# and then evaluated in getopt phase 2a. However, any "-o tool" found during getopt phase 2a WILL BE IGNORED.
|
||||
# The '-o tool' should NOT output any '-o tool' options as '-o tool' is NOT RECURSIVE.
|
||||
# Command line options output from a '-o tool' are accumulated for getopt phase 2,
|
||||
# and then evaluated in getopt phase 2a. However, any '-o tool' found during getopt phase 2a WILL BE IGNORED.
|
||||
#
|
||||
# Most command line options override earlier copies of the same option. However in the case of
|
||||
# "-H phase=name", later "-H phase=name" only overrides an earlier use of "-H" for the same "phase" only.
|
||||
# Also in the case of "-s token=value", later "-s token=value" only overrides an earlier use of "-s"
|
||||
# for the same "token" only.
|
||||
# '-H phase=name', later '-H phase=name' only overrides an earlier use of '-H' for the same 'phase' only.
|
||||
# Also in the case of '-s token=value', later '-s token=value' only overrides an earlier use of '-s'
|
||||
# for the same 'token' only.
|
||||
#
|
||||
# When "-e exitcode" is evaluated, the application will exit with the "exitcode" value. If one wishes to also
|
||||
# output a message to stderr, the "-E string" must come BEFORE any "-e exitcode" in the command line.
|
||||
# When '-e exitcode' is evaluated, the application will exit with the 'exitcode' value. If one wishes to also
|
||||
# output a message to stderr, the '-E string' must come BEFORE any '-e exitcode' in the command line.
|
||||
#
|
||||
# All tokens (i.e., strings of the form "%%token%%") MUST be substituted (by some -s token=value)
|
||||
# in all HTML output, except during phase numbers 20-29 (i.e., except "before tool" output, pandoc output,
|
||||
# and except "after tool" output), or command will exit non-zero, unless -S is given. If -S is given,
|
||||
# All tokens (i.e., strings of the form '%%token%%') MUST be substituted (by some -s token=value)
|
||||
# in all HTML output, except during phase numbers 20-29 (i.e., except 'before tool' output, pandoc output,
|
||||
# and except 'after tool' output), or command will exit non-zero, unless -S is given. If -S is given,
|
||||
# only a warning about un-substituted tokens will be written to stderr.
|
||||
#
|
||||
# While above list is not a complete list of options, it does list options that are required of
|
||||
@@ -171,9 +171,9 @@
|
||||
#
|
||||
# Phases 11-19 are reserved for future use.
|
||||
#
|
||||
# 20. ((insert "before tool" output))
|
||||
# 21. ((insert "pandoc tool" output))
|
||||
# 22. ((insert "after tool" output))
|
||||
# 20. ((insert 'before tool' output))
|
||||
# 21. ((insert 'pandoc tool' output))
|
||||
# 22. ((insert 'after tool' output))
|
||||
#
|
||||
# Phases 23-29 are reserved for future use.
|
||||
#
|
||||
@@ -186,7 +186,7 @@
|
||||
# Phases 35-39 are reserved for future use.
|
||||
#
|
||||
# In the above HTML phase numbers, except during HTML phase numbers 20-29, symbols of the form %%TOKEN%% are substituted.
|
||||
# Any %%TOKEN%% printed by the "before tool" (-b tool), the "pandoc tool" (-p tool), and the "after tool" (-a tool)
|
||||
# Any %%TOKEN%% printed by the 'before tool' (-b tool), the 'pandoc tool' (-p tool), and the 'after tool' (-a tool)
|
||||
# are ignored (i.e., not substituted).
|
||||
|
||||
#################
|
||||
|
||||
Reference in new issue
Block a user