Updated documentation to reflect the rc files Tidy will use on Unix systems,

and added a new -help-env service that intelligently displays information about
$HTML_TIDY, rc files, and application order.

console/tidy.c

@@ -1011,7 +1011,45 @@ static void optionhelp( TidyDoc tdoc )
 }
 
 
-/** @} end service_lang_help group */
+/** @} end service_help_config group */
+/* MARK: - Provide the -help-env Service */
+/***************************************************************************//**
+ ** @defgroup service_help_env Provide the -help-env Service
+ *******************************************************************************
+ ** @{
+ */
+
+
+/** Handles the -help-env service.
+ ** @param tdoc The Tidy document.
+ */
+static void helpEnv( TidyDoc tdoc )
+{
+    tmbstr subst = "";
+    Bool uses_env = getenv("HTML_TIDY") != NULL;
+    ctmbstr env_var = uses_env ? getenv("HTML_TIDY"): tidyLocalizedString( TC_TXT_HELP_ENV_1B );
+
+#if defined( TIDY_CONFIG_FILE ) && defined( TIDY_USER_CONFIG_FILE )
+    subst = stringWithFormat( tidyLocalizedString(TC_TXT_HELP_ENV_1A), TIDY_CONFIG_FILE, TIDY_USER_CONFIG_FILE );
+#endif
+
+    env_var = env_var != NULL ? env_var : tidyLocalizedString( TC_TXT_HELP_ENV_1B );
+
+    printf( "\n" );
+    printf( tidyLocalizedString( TC_TXT_HELP_ENV_1), subst, env_var );
+
+#if defined( TIDY_CONFIG_FILE ) && defined( TIDY_USER_CONFIG_FILE )
+    if ( uses_env )
+        printf( tidyLocalizedString( TC_TXT_HELP_ENV_1C ), TIDY_USER_CONFIG_FILE );
+    free( subst );
+#endif
+
+    printf( "\n" );
+}
+
+
+
+/** @} end service_help_env group */
 /* MARK: - Provide the -help-option Service */
 /***************************************************************************//**
  ** @defgroup service_help_option Provide the -help-option Service
@@ -2124,6 +2162,12 @@ int main( int argc, char** argv )
                 tidyRelease( tdoc );
                 return 0; /* success */
             }
+            else if ( strcasecmp(arg, "help-env") == 0 )
+            {
+                helpEnv( tdoc );
+                tidyRelease( tdoc );
+                return 0; /* success */
+            }
             else if ( strcasecmp(arg, "help-option") == 0 )
             {
                 if ( argc >= 3)

include/tidyenum.h

@@ -491,6 +491,10 @@ extern "C" {
         FN(TC_TXT_HELP_CONFIG_NAME)         \
         FN(TC_TXT_HELP_CONFIG_TYPE)         \
         FN(TC_TXT_HELP_CONFIG_ALLW)         \
+        FN(TC_TXT_HELP_ENV_1)               \
+        FN(TC_TXT_HELP_ENV_1A)              \
+        FN(TC_TXT_HELP_ENV_1B)              \
+        FN(TC_TXT_HELP_ENV_1C)              \
         FN(TC_TXT_HELP_LANG_1)              \
         FN(TC_TXT_HELP_LANG_2)              \
         FN(TC_TXT_HELP_LANG_3)

localize/translations/tidy.pot

@@ -5,7 +5,7 @@ msgstr ""
 "Plural-Forms: nplurals=2; plural=n != 1;\n"
 "X-Generator: HTML Tidy poconvert.rb\n"
 "Project-Id-Version: \n"
-"POT-Creation-Date: 2017-09-28 13:24:51\n"
+"POT-Creation-Date: 2017-10-01 18:57:47\n"
 "Last-Translator: jderry\n"
 "Language-Team: \n"
 
@@ -3388,36 +3388,44 @@ msgstr ""
 
 #. This console output should be limited to 78 characters per line.
 #. - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated.
+#. - %s represents either a blank line, or TC_TXT_HELP_3A explaining environment options.
+#, c-format
 msgctxt "TC_TXT_HELP_3"
 msgid ""
 "\n"
 "Tidy Configuration Options\n"
 "==========================\n"
-"Use Tidy's configuration options as command line arguments in the form\n"
+" Use Tidy's configuration options as command line arguments in the form\n"
-"of \"--some-option <value>\", for example, \"--indent-with-tabs yes\".\n"
+" of \"--some-option <value>\", for example, \"--indent-with-tabs yes\".\n"
 "\n"
-"For a list of all configuration options, use \"-help-config\" or refer\n"
+" You can also specify a file containing configuration options with the \n"
-"to the man page (if your OS has one).\n"
+" -options <file> directive, or in one or more files specific to your \n"
+" environment (see next section). \n"
 "\n"
-"If your environment has an $HTML_TIDY variable set point to a Tidy \n"
+" For a list of all configuration options, use \"-help-config\" or refer\n"
-"configuration file then Tidy will attempt to use it.\n"
+" to the man page (if your OS has one).\n"
 "\n"
-"On some platforms Tidy will also attempt to use a configuration specified \n"
+"Configuration Files\n"
-"in /etc/tidy.conf or ~/.tidy.conf.\n"
+"===================\n"
+" If your environment has an $HTML_TIDY variable set to point to a Tidy \n"
+" configuration file, then Tidy will attempt to use it. \n"
+"%s"
+" Use \"-help-env\" for more information about how you can use the environment. \n"
+" to specify Tidy options. \n"
 "\n"
 "Other\n"
 "=====\n"
-"Input/Output default to stdin/stdout respectively.\n"
+" Input/Output default to stdin/stdout respectively.\n"
 "\n"
-"Single letter options apart from -f may be combined\n"
+" Single letter options apart from -f may be combined\n"
-"as in:  tidy -f errs.txt -imu foo.html\n"
+" as in:  tidy -f errs.txt -imu foo.html\n"
 "\n"
 "Information\n"
 "===========\n"
-"For more information about HTML Tidy, see\n"
+" For more information about HTML Tidy, see\n"
 "  http://www.html-tidy.org/\n"
 "\n"
-"For more information on HTML, see the following:\n"
+" For more information on HTML, see the following:\n"
 "\n"
 "   HTML: Edition for Web Authors (the latest HTML specification)\n"
 "   http://dev.w3.org/html5/spec-author-view\n"
@@ -3425,14 +3433,29 @@ msgid ""
 "   HTML: The Markup Language (an HTML language reference)\n"
 "   http://dev.w3.org/html5/markup/\n"
 "\n"
-"File bug reports at https://github.com/htacg/tidy-html5/issues/\n"
+" File bug reports at https://github.com/htacg/tidy-html5/issues/\n"
-"or send questions and comments to public-htacg@w3.org.\n"
+" or send questions and comments to public-htacg@w3.org.\n"
 "\n"
-"Validate your HTML documents using the W3C Nu Markup Validator:\n"
+" Validate your HTML documents using the W3C Nu Markup Validator:\n"
 "   http://validator.w3.org/nu/\n"
 "\n"
 msgstr ""
 
+#. This console output should be limited to 78 characters per line.
+#. - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated.
+#. - Both parameters %s reflect file paths and names.
+#, c-format
+msgctxt "TC_TXT_HELP_3A"
+msgid ""
+"\n"
+" Additionally, Tidy will automatically attempt to use configuration specified \n"
+" in these files, if present: \n"
+"\n"
+"  %s \n"
+"  %s \n"
+"\n"
+msgstr ""
+
 #. This console output should be limited to 78 characters per line.
 #. - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated.
 msgctxt "TC_TXT_HELP_CONFIG"
@@ -3463,6 +3486,54 @@ msgctxt "TC_TXT_HELP_CONFIG_ALLW"
 msgid "Allowable values"
 msgstr ""
 
+#. This console output should be limited to 78 characters per line.
+#. - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated.
+#. - The first %s indicates two more list items, or an empty string.
+#. - The second %s indicates a file name, or a message indicating no file name.
+#, c-format
+msgctxt "TC_TXT_HELP_ENV_1"
+msgid ""
+"\n"
+"Tidy can configure its option values from multiple sources, in the \n"
+"order below. Subsequent use of the same option overrides previous \n"
+"option settings. \n"
+"\n"
+" - Tidy's built-in default values. \n"
+"%s" /* rc files */
+" - The file specified in the $HTML_TIDY environment variable: \n"
+"     %s \n"
+" - Options in a file specified on the command line. \n"
+" - Options set directly on the command line. \n"
+msgstr ""
+
+#. This console output should be limited to 78 characters per line.
+#. - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated.
+#, c-format
+msgctxt "TC_TXT_HELP_ENV_1A"
+msgid ""
+" - The system runtime configuration file: \n"
+"     %s \n"
+" - The user runtime configuration file: \n"
+"     %s \n"
+msgstr ""
+
+#. This console output should be limited to 78 characters per line.
+#. - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated.
+#. - This message indicates that a file name is not currently set.
+msgctxt "TC_TXT_HELP_ENV_1B"
+msgid "(not currently set)"
+msgstr ""
+
+#. This console output should be limited to 78 characters per line.
+#. - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated.
+#, c-format
+msgctxt "TC_TXT_HELP_ENV_1C"
+msgid ""
+"\n"
+"Note that because $HTML_TIDY is set, the user runtime configuration file \n"
+"%s will not be used. \n"
+msgstr ""
+
 #. This console output should be limited to 78 characters per line.
 #. - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated.
 msgctxt "TC_TXT_HELP_LANG_1"

src/language_en.h

@@ -2304,6 +2304,44 @@ static languageDefinition language_en = { whichPluralForm_en, {
     { TC_TXT_HELP_CONFIG_NAME,      0,   "Name"                                                                    },
     { TC_TXT_HELP_CONFIG_TYPE,      0,   "Type"                                                                    },
     { TC_TXT_HELP_CONFIG_ALLW,      0,   "Allowable values"                                                        },
+    {/* This console output should be limited to 78 characters per line.
+        - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated.
+        - The first %s indicates two more list items, or an empty string.
+        - The second %s indicates a file name, or a message indicating no file name. */
+      TC_TXT_HELP_ENV_1,           0,
+        "\n"
+        "Tidy can configure its option values from multiple sources, in the \n"
+        "order below. Subsequent use of the same option overrides previous \n"
+        "option settings. \n"
+        "\n"
+        " - Tidy's built-in default values. \n"
+        "%s" /* rc files */
+        " - The file specified in the $HTML_TIDY environment variable: \n"
+        "     %s \n"
+        " - Options in a file specified on the command line. \n"
+        " - Options set directly on the command line. \n"
+    },
+    {/* This console output should be limited to 78 characters per line.
+        - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated. */
+      TC_TXT_HELP_ENV_1A,          0,
+        " - The system runtime configuration file: \n"
+        "     %s \n"
+        " - The user runtime configuration file: \n"
+        "     %s \n"
+    },
+    {/* This console output should be limited to 78 characters per line.
+        - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated.
+        - This message indicates that a file name is not currently set. */
+      TC_TXT_HELP_ENV_1B,          0,
+        "(not currently set)"
+    },
+    {/* This console output should be limited to 78 characters per line.
+        - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated. */
+      TC_TXT_HELP_ENV_1C,          0,
+        "\n"
+        "Note that because $HTML_TIDY is set, the user runtime configuration file \n"
+        "%s will not be used. \n"
+    },
     {/* This console output should be limited to 78 characters per line.
         - The strings "Tidy" and "HTML Tidy" are the program name and must not be translated. */
       TC_TXT_HELP_LANG_1,           0,