doc/formatting

git-svn-id: svn://tug.org/texlive/trunk@51849 c570f23f-e606-0410-a88d-b1316a301751

7 files changed, 47 insertions, 38 deletions

diff --git a/Build/source/texk/kpathsea/ChangeLog b/Build/source/texk/kpathsea/ChangeLog
index baa1b724fef..364bb21abc6 100644
--- a/Build/source/texk/kpathsea/ChangeLog
+++ b/Build/source/texk/kpathsea/ChangeLog
@@ -1,3 +1,10 @@
+2019-08-09  Karl Berry  <karl@freefriends.org>
+
+	* cnf.c,
+	* progname.h,
+	* tex-file.c,
+	* types.h: doc/formatting fixes.
+
 2019-08-06  Karl Berry  <karl@freefriends.org>
 
 	* kpsewhich.c (USAGE, read_command_line): new option --cnf-line.
diff --git a/Build/source/texk/kpathsea/cnf.c b/Build/source/texk/kpathsea/cnf.c
index 9d3baeac84f..def8f97c77e 100644
--- a/Build/source/texk/kpathsea/cnf.c
+++ b/Build/source/texk/kpathsea/cnf.c
@@ -336,6 +336,6 @@ kpathsea_cnf_get (kpathsea kpse, const_string name)
 const_string
 kpse_cnf_get (const_string name)
 {
-    return kpathsea_cnf_get(kpse_def, name);
+  return kpathsea_cnf_get(kpse_def, name);
 }
 #endif
diff --git a/Build/source/texk/kpathsea/progname.h b/Build/source/texk/kpathsea/progname.h
index 596424b466d..b5c1c43afbd 100644
--- a/Build/source/texk/kpathsea/progname.h
+++ b/Build/source/texk/kpathsea/progname.h
@@ -1,6 +1,6 @@
 /* progname.h: Declarations for argv[0] equivalents.
 
-   Copyright 1994, 1996, 2008, 2010-2013 Karl Berry.
+   Copyright 1994, 1996, 2008, 2010-2019 Karl Berry.
    Copyright 1999, 2005 Olaf Weber.
 
    This library is free software; you can redistribute it and/or
@@ -33,20 +33,20 @@ extern "C" {
 extern KPSEDLL string kpathsea_selfdir (kpathsea kpse, const_string argv0);
 #endif
 
-/* Set the first two variables above (if they're not predefined) to a copy
-   of ARGV0 and everything in ARGV0 after the last directory separator,
-   respectively.  Set kpse_program_name to a copy of PROGNAME or the
-   value of kpse_invocation_short_name if PROGNAME is NULL.
-   This function also determines the AUTO* variables. */
+/* Set the two members `invocation_name' and `invocation_short_name'
+   in the KPSE instance to a copy of ARGV0 and everything in ARGV0 after
+   the last directory separator, respectively. Set `program_name' (also in
+   the KPSE instance) to a copy of PROGNAME or the value of
+   kpse_invocation_short_name if PROGNAME is NULL. This function also
+   sets the SELFAUTO* environment variables.  */
 
 extern KPSEDLL void kpathsea_set_program_name (kpathsea kpse,
                             const_string argv0, const_string progname);
 
-/* See also `kpathsea_reset_program_name' which is defined in tex-file.c
-
+/* See also `kpathsea_reset_program_name', which is defined in tex-file.c.
    That function is to be used to set kpse->program_name to a different
    value.  It clears the path searching information, to ensure that
-   the search paths are appropriate to the new name. */
+   the search paths are appropriate to the new name.  */
 
 
 #if defined (KPSE_COMPAT_API)
diff --git a/Build/source/texk/kpathsea/tex-file.c b/Build/source/texk/kpathsea/tex-file.c
index 626e240b82d..335f13b45f4 100644
--- a/Build/source/texk/kpathsea/tex-file.c
+++ b/Build/source/texk/kpathsea/tex-file.c
@@ -1,7 +1,7 @@
 /* tex-file.c: high-level file searching by format.
 
    Copyright 1993, 1994, 1995, 1996, 1997, 2007, 2008, 2009, 2010, 2011
-             2012, 2014, 2016, 2017 Karl Berry.
+             2012, 2014, 2016, 2017, 2019 Karl Berry.
    Copyright 1998-2005 Olaf Weber.
 
    This library is free software; you can redistribute it and/or
@@ -1429,7 +1429,7 @@ kpse_open_file (const_string name,  kpse_file_format_type type)
    the paths for kpse_cnf_format and kpse_db_format are not cleared.
 
    This function is defined here, and not in progname.c, because it
-   need format_info, and would cause all of tex-file to be pulled
+   needs format_info, and would cause all of tex-file to be pulled
    in by programs that do not need it. */
 
 void
@@ -1445,14 +1445,14 @@ kpathsea_reset_program_name (kpathsea kpse, const_string progname)
 
   free (kpse->program_name);
   kpse->program_name = xstrdup (progname);
-  kpathsea_xputenv(kpse, "progname", kpse->program_name);
+  kpathsea_xputenv (kpse, "progname", kpse->program_name);
 
-  /* Clear paths -- do we want the db path to be cleared? */
+  /* Go through all paths ...  */
   for (i = 0; i != kpse_last_format; ++i) {
-    /* Do not erase the cnf of db paths.  This means that the filename
+    /* Do not erase the cnf or db paths.  This means that the filename
        database is not rebuilt, nor are different configuration files
        searched.  The alternative is to tolerate a memory leak of up
-       to 100k if this function is called. */
+       to 100k if this function is called.  */
     if (i == kpse_cnf_format || i == kpse_db_format)
       continue;
     /* Wipe the path (it is tested) and the cnf_path because their
@@ -1461,14 +1461,13 @@ kpathsea_reset_program_name (kpathsea kpse, const_string progname)
       free (kpse->format_info[i].path);
       kpse->format_info[i].path = NULL;
     }
-    /* We cannot free the cnf_path: it points into the cnf hash, which
-       means all hell will break loose if we did. */
+    /* We cannot free cnf_path: it points into the cnf hash.  */
     if (kpse->format_info[i].cnf_path != NULL) {
       kpse->format_info[i].cnf_path = NULL;
     }
     /* We do not wipe the override_path at this point, though arguably
        we should provide new values.  It is not likely to matter for
-       the programs that call this function. */
+       the programs that call this function.  */
   }
 }
 
diff --git a/Build/source/texk/kpathsea/types.h b/Build/source/texk/kpathsea/types.h
index b2c15a1fdd1..f62906dec0b 100644
--- a/Build/source/texk/kpathsea/types.h
+++ b/Build/source/texk/kpathsea/types.h
@@ -1,6 +1,6 @@
 /* types.h: general types for kpathsea.
 
-   Copyright 1993, 1995, 1996, 2005, 2008-2014, 2016 Karl Berry.
+   Copyright 1993, 1995, 1996, 2005, 2008-2014, 2016, 2019 Karl Berry.
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
@@ -21,7 +21,10 @@
 /* Our string, boolean, etc.  */
 #include <kpathsea/simpletypes.h>
 
-/* Required until all programs use the new API, if ever.  */
+/* Required forever for any normal build, since we will never want to
+   remove the original interface.  But to check that a program
+   only uses the new-style declarations, that is, is thread-safe,
+   could be useful to undefine.  */
 #define KPSE_COMPAT_API 1
 
 #include <stdio.h> /* for FILE* */
diff --git a/Build/source/texk/web2c/lib/ChangeLog b/Build/source/texk/web2c/lib/ChangeLog
index 9d2753ea432..521081517f6 100644
--- a/Build/source/texk/web2c/lib/ChangeLog
+++ b/Build/source/texk/web2c/lib/ChangeLog
@@ -1,3 +1,8 @@
+2019-08-09  Karl Berry  <karl@freefriends.org>
+
+	* texmfmp.c: doc fixes; most "fixme"s were nothing that we ever
+	need to fix at this late date.
+
 2019-08-08  Akira Kakuto  <kakuto@w32tex.org>
 
 	* texmfmp.c: This file is not used in lua[jit]tex.
diff --git a/Build/source/texk/web2c/lib/texmfmp.c b/Build/source/texk/web2c/lib/texmfmp.c
index 697fa89a907..7a281d24760 100644
--- a/Build/source/texk/web2c/lib/texmfmp.c
+++ b/Build/source/texk/web2c/lib/texmfmp.c
@@ -5,7 +5,7 @@
    
    This file is public domain.  */
 
-/* This file is included from, e.g., texextra,c after
+/* This file is included from, e.g., texextra.c after
       #define EXTERN
       #include <texd.h>
    to instantiate data from texd.h here.  The ?d.h file is what
@@ -727,8 +727,10 @@ static string
 normalize_quotes (const_string name, const_string mesg);
 #endif /* WIN32 */
 
-/* The entry point: set up for reading the command line, which will
-   happen in `topenin', then call the main body.  */
+/* maininit, called from main() - this is most of the main routine,
+   including our C-level option handling and concomitant kpse setup.
+   The original TeX/MF code for handling first lines is still live, and
+   we set up for that in `topenin' (which is called from the .web).  */
 
 void
 maininit (int ac, string *av)
@@ -842,21 +844,19 @@ maininit (int ac, string *av)
 
 #if defined(MF)
 #if defined(MFLua)
-  /* If the program name is "mflua-nowin", then reset the name as "mflua". */
+  /* Reset mf*-nowin program names.  */
   if (strncasecmp (kpse_invocation_name, "mflua-nowin", 11) == 0)
     kpse_reset_program_name ("mflua");
 #elif defined(MFLuaJIT)
-  /* If the program name is "mfluajit-nowin", then reset the name as "mfluajit". */
   if (strncasecmp (kpse_invocation_name, "mfluajit-nowin", 14) == 0)
     kpse_reset_program_name ("mfluajit");
 #else
-  /* If the program name is "mf-nowin", then reset the name as "mf". */
   if (strncasecmp (kpse_invocation_name, "mf-nowin", 8) == 0)
     kpse_reset_program_name ("mf");
 #endif
 #endif
 
-  /* FIXME: gather engine names in a single spot. */
+  /* Make the given engine name available in the variable `engine'.  */
   xputenv ("engine", TEXMFENGINENAME);
   
   if (user_cnf_lines) {
@@ -934,7 +934,6 @@ maininit (int ac, string *av)
   }
   /* Check whether there still is no translate_filename known.  If so,
      use the default_translate_filename. */
-  /* FIXME: deprecated. */
   if (!translate_filename) {
     translate_filename = default_translate_filename;
   }
@@ -1050,9 +1049,9 @@ maininit (int ac, string *av)
 #endif /* TeX */
 }
 
-/* The entry point: set up for reading the command line, which will
-   happen in `topenin', then call the main body.  */
-
+/* main: Set up for reading the command line, which will happen in
+   `maininit' and `topenin', then call the main body, plus
+   special Windows/Kanji initializations.  */
  
 int
 #if defined(DLLPROC)
@@ -1488,8 +1487,6 @@ tcx_get_num (int upb,
    tex.pool.  If no suffix in FNAME, use .tcx (don't bother trying to
    support extension-less names for these files).  */
 
-/* FIXME: A new format ought to be introduced for these files. */
-
 void
 readtcxfile (void)
 {
@@ -1778,7 +1775,6 @@ parse_options (int argc, string *argv)
       break;
 
     if (g == '?') { /* Unknown option.  */
-      /* FIXME: usage (argv[0]); replaced by continue. */
       continue;
     }
 
@@ -1820,7 +1816,7 @@ parse_options (int argc, string *argv)
       dumpoption = true;
 
 #ifdef TeX
-    /* FIXME: Obsolete -- for backward compatibility only. */
+    /* For backward compatibility only. */
     } else if (ARGUMENT_IS ("efmt")) {
       dump_name = optarg;
       dumpoption = true;
@@ -2076,7 +2072,6 @@ parse_first_line (const_string filename)
           s = *parse+16;
         }
         /* Just set the name, no sanity checks here. */
-        /* FIXME: remove trailing spaces. */
         if (s && *s) {
           translate_filename = xstrdup(s);
         }
@@ -2840,7 +2835,7 @@ do_undump (char *p, int item_size, int nitems, FILE *in_file)
 #endif
 }
 
-/* FIXME -- some (most?) of this can/should be moved to the Pascal/WEB side. */
+/* Some (most?) of this could be moved to the WEB side, but oh well.  */
 #if defined(TeX) || defined(MF)
 #if !defined(pdfTeX)
 static void