Additional doc fix.

1 files changed, 23 insertions, 3 deletions

diff --git a/doc/gawk.texi b/doc/gawk.texi
index e43415dc..328c1782 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -5091,6 +5091,7 @@ of hexadecimal digits (@samp{0}--@samp{9}, and either @samp{A}--@samp{F}
 or @samp{a}--@samp{f}).  A maximum of two digts are allowed after
 the @samp{\x}. Any further hexadecimal digits are treated as simple
 letters or numbers.  @value{COMMONEXT}
+(The @samp{\x} escape sequence is not allowed in POSIX awk.)
 
 @quotation CAUTION
 In ISO C, the escape sequence continues until the first nonhexadecimal
@@ -5099,7 +5100,10 @@ digit is seen.
 For many years, @command{gawk} would continue incorporating
 hexadecimal digits into the value until a non-hexadecimal digit
 or the end of the string was encountered.
-However, using more than two hexadecimal digits produces
+However, using more than two hexadecimal digits produced
+undefined results.
+As of @value{PVERSION} @strong{FIXME:} 4.3.0, only two digits
+are processed.
 @end quotation
 
 @cindex @code{\} (backslash), @code{\/} escape sequence
@@ -27882,8 +27886,7 @@ The profiled version of your program may not look exactly like what you
 typed when you wrote it.  This is because @command{gawk} creates the
 profiled version by ``pretty printing'' its internal representation of
 the program.  The advantage to this is that @command{gawk} can produce
-a standard representation.  The disadvantage is that all source-code
-comments are lost.
+a standard representation.
 Also, things such as:
 
 @example
@@ -27980,6 +27983,23 @@ When called this way, @command{gawk} ``pretty prints'' the program into
 Once upon a time, the @option{--pretty-print} option would also run
 your program.  This is is no longer the case.
 @end quotation
+
+There is a significant difference between the output created when
+profiling, and that created when pretty-printing.  Pretty-printed output
+preserves the original comments that were in the program, although their
+placement may not correspond exactly to their original locations in the
+source code.
+
+However, as a deliberate design decision, profiling output @emph{omits}
+the original program's comments. This allows you to focus on the
+execution count data and helps you avoid the temptation to use the
+profiler for pretty-printing.
+
+Additionally, pretty-printed output does not have the leading indentation
+that the profiling output does. This makes it easy to pretty-print your
+code once development is completed, and then use the result as the final
+version of your program.
+
 @c ENDOFRANGE awkp
 @c ENDOFRANGE proawk