From b24bba82b4a05d9bee6969747f23fb3793b3d2b3 Mon Sep 17 00:00:00 2001
From: John Kohl <jtkohl@mit.edu>
Date: Thu, 31 May 1990 21:50:43 +0000
Subject: [PATCH] comment why it's fixed the way it is now

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@974 dc483132-0cff-0310-8789-dd5450dbe970
---
 doc/api/fixunder.sty       | 35 ++++++++++++++++++++++++++++++++++-
 doc/implement/fixunder.sty | 35 ++++++++++++++++++++++++++++++++++-
 2 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/doc/api/fixunder.sty b/doc/api/fixunder.sty
index fa5b3d747..b7ae58dbf 100644
--- a/doc/api/fixunder.sty
+++ b/doc/api/fixunder.sty
@@ -1,5 +1,13 @@
+% fixunder.sty,  31 May 1990, John T. Kohl
 %
-% re-define _ to be normal, and to provide a reasonable underscore.
+% The contents of this file are in the public domain.
+%
+%
+% play games with _ to make it active and to provide a reasonable _
+% character (from \tt in most cases), and a discretionary word-break point.
+
+%
+% Some \makeunder... macros for convenience in setting catcodes.
 %
 \def\makeunderactive{\catcode`\_=\active\relax}
 \def\makeunderother{\catcode`\_=12\relax}
@@ -8,6 +16,31 @@
 \makeunderother
 \def\cctwlunder{_}
 
+%
+% The hair here is to allow things like \index to work reasonably with
+% the new definition of underscore when the argument to index is part of
+% a macro replacement and as such gets tokenized before \index is
+% evaluated.
+% [in the normal case at top-level, \index{foo_bar} works since \index
+% does some hair to make _ into a reasonable character code, and \index
+% does NOT use a macro expansion.  If you have something like
+% \def\foo#1#2{\index{#1} bar #2}
+% then \foo{baz_quux}{frobnitz} will result in baz_quux getting
+% tokenized BEFORE \foo is expanded, so that the catcode hair in \index
+% is to no avail.]
+%
+% \underrealfalse declares that you want to replace with the \tt _;
+% \underrealtrue declares that you want to replace with \char95 (ASCII _).
+%
+% for things like \index which write things out to files, set
+% \underrealfalse before evaluating the \index macro, and what actually
+% gets written to the file is an _, rather than something like
+% {\leavemode \kern... } (the typical definition of \_).
+%
+% the above example would then be
+% \def\foo#1#2{\underrealfalse\index{#1}\underrealtrue bar #2}
+%
+
 \newif\ifunderreal
 \underrealfalse
 \makeunderactive
diff --git a/doc/implement/fixunder.sty b/doc/implement/fixunder.sty
index fa5b3d747..b7ae58dbf 100644
--- a/doc/implement/fixunder.sty
+++ b/doc/implement/fixunder.sty
@@ -1,5 +1,13 @@
+% fixunder.sty,  31 May 1990, John T. Kohl
 %
-% re-define _ to be normal, and to provide a reasonable underscore.
+% The contents of this file are in the public domain.
+%
+%
+% play games with _ to make it active and to provide a reasonable _
+% character (from \tt in most cases), and a discretionary word-break point.
+
+%
+% Some \makeunder... macros for convenience in setting catcodes.
 %
 \def\makeunderactive{\catcode`\_=\active\relax}
 \def\makeunderother{\catcode`\_=12\relax}
@@ -8,6 +16,31 @@
 \makeunderother
 \def\cctwlunder{_}
 
+%
+% The hair here is to allow things like \index to work reasonably with
+% the new definition of underscore when the argument to index is part of
+% a macro replacement and as such gets tokenized before \index is
+% evaluated.
+% [in the normal case at top-level, \index{foo_bar} works since \index
+% does some hair to make _ into a reasonable character code, and \index
+% does NOT use a macro expansion.  If you have something like
+% \def\foo#1#2{\index{#1} bar #2}
+% then \foo{baz_quux}{frobnitz} will result in baz_quux getting
+% tokenized BEFORE \foo is expanded, so that the catcode hair in \index
+% is to no avail.]
+%
+% \underrealfalse declares that you want to replace with the \tt _;
+% \underrealtrue declares that you want to replace with \char95 (ASCII _).
+%
+% for things like \index which write things out to files, set
+% \underrealfalse before evaluating the \index macro, and what actually
+% gets written to the file is an _, rather than something like
+% {\leavemode \kern... } (the typical definition of \_).
+%
+% the above example would then be
+% \def\foo#1#2{\underrealfalse\index{#1}\underrealtrue bar #2}
+%
+
 \newif\ifunderreal
 \underrealfalse
 \makeunderactive
-- 
2.26.2