diff options
| -rw-r--r-- | doc/gawk.info | 461 | ||||
| -rw-r--r-- | doc/gawk.texi | 20 |
2 files changed, 256 insertions, 225 deletions
diff --git a/doc/gawk.info b/doc/gawk.info index caa557e8..4e8b653a 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -19818,8 +19818,7 @@ output. They are as follows: you typed when you wrote it. This is because `gawk' creates the profiled version by "pretty printing" its internal representation of the program. The advantage to this is that `gawk' can produce a -standard representation. The disadvantage is that all source-code -comments are lost. Also, things such as: +standard representation. Also, things such as: /foo/ @@ -19881,6 +19880,22 @@ without any execution counts. NOTE: Once upon a time, the `--pretty-print' option would also run your program. This is is no longer the case. + 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 _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. + File: gawk.info, Node: Advanced Features Summary, Prev: Profiling, Up: Advanced Features @@ -32377,7 +32392,7 @@ Index * dump debugger command: Miscellaneous Debugger Commands. (line 9) * dupword.awk program: Dupword Program. (line 31) -* dynamic profiling: Profiling. (line 179) +* dynamic profiling: Profiling. (line 178) * dynamically loaded extensions: Dynamic Extensions. (line 6) * e debugger command (alias for enable): Breakpoint Control. (line 73) * EBCDIC: Ordinal Functions. (line 45) @@ -32748,7 +32763,7 @@ Index (line 44) * G-d: Acknowledgments. (line 94) * Garfinkle, Scott: Contributors. (line 34) -* gawk program, dynamic profiling: Profiling. (line 179) +* gawk program, dynamic profiling: Profiling. (line 178) * gawk version: Auto-set. (line 214) * gawk, ARGIND variable in: Other Arguments. (line 15) * gawk, awk and <1>: This Manual. (line 14) @@ -32939,7 +32954,7 @@ Index * history expansion, in debugger: Readline Support. (line 6) * histsort.awk program: History Sorting. (line 25) * Hughes, Phil: Acknowledgments. (line 43) -* HUP signal, for dynamic profiling: Profiling. (line 211) +* HUP signal, for dynamic profiling: Profiling. (line 210) * hyphen (-), - operator: Precedence. (line 52) * hyphen (-), -- operator <1>: Precedence. (line 46) * hyphen (-), -- operator: Increment Ops. (line 48) @@ -33019,7 +33034,7 @@ Index * installing gawk: Installation. (line 6) * instruction tracing, in debugger: Debugger Info. (line 89) * int: Numeric Functions. (line 38) -* INT signal (MS-Windows): Profiling. (line 214) +* INT signal (MS-Windows): Profiling. (line 213) * integer array indices: Numeric Array Subscripts. (line 31) * integers, arbitrary precision: Arbitrary Precision Integers. @@ -33075,7 +33090,7 @@ Index * Kernighan, Brian <9>: Acknowledgments. (line 78) * Kernighan, Brian <10>: Conventions. (line 38) * Kernighan, Brian: History. (line 17) -* kill command, dynamic profiling: Profiling. (line 188) +* kill command, dynamic profiling: Profiling. (line 187) * Knights, jedi: Undocumented. (line 6) * Kwok, Conrad: Contributors. (line 34) * l debugger command (alias for list): Miscellaneous Debugger Commands. @@ -33582,7 +33597,7 @@ Index * PROCINFO, values of sorted_in: Controlling Scanning. (line 26) * profiling awk programs: Profiling. (line 6) -* profiling awk programs, dynamically: Profiling. (line 179) +* profiling awk programs, dynamically: Profiling. (line 178) * program identifiers: Auto-set. (line 155) * program, definition of: Getting Started. (line 21) * programming conventions, --non-decimal-data option: Nondecimal Data. @@ -33618,7 +33633,7 @@ Index * QuikTrim Awk: Other Versions. (line 135) * quit debugger command: Miscellaneous Debugger Commands. (line 99) -* QUIT signal (MS-Windows): Profiling. (line 214) +* QUIT signal (MS-Windows): Profiling. (line 213) * quoting in gawk command lines: Long. (line 26) * quoting in gawk command lines, tricks for: Quoting. (line 91) * quoting, for small awk programs: Comments. (line 27) @@ -33899,15 +33914,15 @@ Index (line 57) * sidebar, Using close()'s Return Value: Close Files And Pipes. (line 130) -* SIGHUP signal, for dynamic profiling: Profiling. (line 211) -* SIGINT signal (MS-Windows): Profiling. (line 214) -* signals, HUP/SIGHUP, for profiling: Profiling. (line 211) -* signals, INT/SIGINT (MS-Windows): Profiling. (line 214) -* signals, QUIT/SIGQUIT (MS-Windows): Profiling. (line 214) -* signals, USR1/SIGUSR1, for profiling: Profiling. (line 188) +* SIGHUP signal, for dynamic profiling: Profiling. (line 210) +* SIGINT signal (MS-Windows): Profiling. (line 213) +* signals, HUP/SIGHUP, for profiling: Profiling. (line 210) +* signals, INT/SIGINT (MS-Windows): Profiling. (line 213) +* signals, QUIT/SIGQUIT (MS-Windows): Profiling. (line 213) +* signals, USR1/SIGUSR1, for profiling: Profiling. (line 187) * signature program: Signature Program. (line 6) -* SIGQUIT signal (MS-Windows): Profiling. (line 214) -* SIGUSR1 signal, for dynamic profiling: Profiling. (line 188) +* SIGQUIT signal (MS-Windows): Profiling. (line 213) +* SIGUSR1 signal, for dynamic profiling: Profiling. (line 187) * silent debugger command: Debugger Execution Control. (line 10) * sin: Numeric Functions. (line 91) @@ -34181,7 +34196,7 @@ Index * user-modifiable variables: User-modified. (line 6) * users, information about, printing: Id Program. (line 6) * users, information about, retrieving: Passwd Functions. (line 16) -* USR1 signal, for dynamic profiling: Profiling. (line 188) +* USR1 signal, for dynamic profiling: Profiling. (line 187) * values, numeric: Basic Data Typing. (line 13) * values, string: Basic Data Typing. (line 13) * variable assignments and input files: Other Arguments. (line 26) @@ -34655,210 +34670,210 @@ Ref: Two-way I/O-Footnote-1792709 Ref: Two-way I/O-Footnote-2792895 Node: TCP/IP Networking792977 Node: Profiling795849 -Node: Advanced Features Summary803402 -Node: Internationalization805335 -Node: I18N and L10N806815 -Node: Explaining gettext807501 -Ref: Explaining gettext-Footnote-1812530 -Ref: Explaining gettext-Footnote-2812714 -Node: Programmer i18n812879 -Ref: Programmer i18n-Footnote-1817745 -Node: Translator i18n817794 -Node: String Extraction818588 -Ref: String Extraction-Footnote-1819719 -Node: Printf Ordering819805 -Ref: Printf Ordering-Footnote-1822591 -Node: I18N Portability822655 -Ref: I18N Portability-Footnote-1825104 -Node: I18N Example825167 -Ref: I18N Example-Footnote-1827967 -Node: Gawk I18N828039 -Node: I18N Summary828677 -Node: Debugger830016 -Node: Debugging831038 -Node: Debugging Concepts831479 -Node: Debugging Terms833336 -Node: Awk Debugging835911 -Node: Sample Debugging Session836803 -Node: Debugger Invocation837323 -Node: Finding The Bug838707 -Node: List of Debugger Commands845182 -Node: Breakpoint Control846514 -Node: Debugger Execution Control850206 -Node: Viewing And Changing Data853570 -Node: Execution Stack856935 -Node: Debugger Info858573 -Node: Miscellaneous Debugger Commands862590 -Node: Readline Support867782 -Node: Limitations868674 -Node: Debugging Summary870771 -Node: Arbitrary Precision Arithmetic871939 -Node: Computer Arithmetic873355 -Ref: table-numeric-ranges876956 -Ref: Computer Arithmetic-Footnote-1877815 -Node: Math Definitions877872 -Ref: table-ieee-formats881159 -Ref: Math Definitions-Footnote-1881763 -Node: MPFR features881868 -Node: FP Math Caution883539 -Ref: FP Math Caution-Footnote-1884589 -Node: Inexactness of computations884958 -Node: Inexact representation885906 -Node: Comparing FP Values887261 -Node: Errors accumulate888334 -Node: Getting Accuracy889767 -Node: Try To Round892426 -Node: Setting precision893325 -Ref: table-predefined-precision-strings894009 -Node: Setting the rounding mode895803 -Ref: table-gawk-rounding-modes896167 -Ref: Setting the rounding mode-Footnote-1899621 -Node: Arbitrary Precision Integers899800 -Ref: Arbitrary Precision Integers-Footnote-1904704 -Node: POSIX Floating Point Problems904853 -Ref: POSIX Floating Point Problems-Footnote-1908729 -Node: Floating point summary908767 -Node: Dynamic Extensions910959 -Node: Extension Intro912511 -Node: Plugin License913777 -Node: Extension Mechanism Outline914574 -Ref: figure-load-extension915002 -Ref: figure-register-new-function916482 -Ref: figure-call-new-function917486 -Node: Extension API Description919472 -Node: Extension API Functions Introduction920922 -Node: General Data Types925758 -Ref: General Data Types-Footnote-1931445 -Node: Memory Allocation Functions931744 -Ref: Memory Allocation Functions-Footnote-1934574 -Node: Constructor Functions934670 -Node: Registration Functions936404 -Node: Extension Functions937089 -Node: Exit Callback Functions939385 -Node: Extension Version String940633 -Node: Input Parsers941283 -Node: Output Wrappers951098 -Node: Two-way processors955614 -Node: Printing Messages957818 -Ref: Printing Messages-Footnote-1958895 -Node: Updating `ERRNO'959047 -Node: Requesting Values959787 -Ref: table-value-types-returned960515 -Node: Accessing Parameters961473 -Node: Symbol Table Access962704 -Node: Symbol table by name963218 -Node: Symbol table by cookie965198 -Ref: Symbol table by cookie-Footnote-1969337 -Node: Cached values969400 -Ref: Cached values-Footnote-1972904 -Node: Array Manipulation972995 -Ref: Array Manipulation-Footnote-1974093 -Node: Array Data Types974132 -Ref: Array Data Types-Footnote-1976789 -Node: Array Functions976881 -Node: Flattening Arrays980735 -Node: Creating Arrays987622 -Node: Extension API Variables992389 -Node: Extension Versioning993025 -Node: Extension API Informational Variables994926 -Node: Extension API Boilerplate996014 -Node: Finding Extensions999830 -Node: Extension Example1000390 -Node: Internal File Description1001162 -Node: Internal File Ops1005229 -Ref: Internal File Ops-Footnote-11016887 -Node: Using Internal File Ops1017027 -Ref: Using Internal File Ops-Footnote-11019410 -Node: Extension Samples1019683 -Node: Extension Sample File Functions1021207 -Node: Extension Sample Fnmatch1028809 -Node: Extension Sample Fork1030291 -Node: Extension Sample Inplace1031504 -Node: Extension Sample Ord1033179 -Node: Extension Sample Readdir1034015 -Ref: table-readdir-file-types1034871 -Node: Extension Sample Revout1035682 -Node: Extension Sample Rev2way1036273 -Node: Extension Sample Read write array1037014 -Node: Extension Sample Readfile1038953 -Node: Extension Sample Time1040048 -Node: Extension Sample API Tests1041397 -Node: gawkextlib1041888 -Node: Extension summary1044538 -Node: Extension Exercises1048220 -Node: Language History1048942 -Node: V7/SVR3.11050599 -Node: SVR41052780 -Node: POSIX1054225 -Node: BTL1055614 -Node: POSIX/GNU1056348 -Node: Feature History1061977 -Node: Common Extensions1075068 -Node: Ranges and Locales1076392 -Ref: Ranges and Locales-Footnote-11081031 -Ref: Ranges and Locales-Footnote-21081058 -Ref: Ranges and Locales-Footnote-31081292 -Node: Contributors1081513 -Node: History summary1087053 -Node: Installation1088422 -Node: Gawk Distribution1089378 -Node: Getting1089862 -Node: Extracting1090686 -Node: Distribution contents1092328 -Node: Unix Installation1098098 -Node: Quick Installation1098715 -Node: Additional Configuration Options1101146 -Node: Configuration Philosophy1102886 -Node: Non-Unix Installation1105237 -Node: PC Installation1105695 -Node: PC Binary Installation1107021 -Node: PC Compiling1108869 -Ref: PC Compiling-Footnote-11111890 -Node: PC Testing1111995 -Node: PC Using1113171 -Node: Cygwin1117286 -Node: MSYS1118109 -Node: VMS Installation1118607 -Node: VMS Compilation1119399 -Ref: VMS Compilation-Footnote-11120621 -Node: VMS Dynamic Extensions1120679 -Node: VMS Installation Details1122363 -Node: VMS Running1124615 -Node: VMS GNV1127456 -Node: VMS Old Gawk1128190 -Node: Bugs1128660 -Node: Other Versions1132564 -Node: Installation summary1138777 -Node: Notes1139833 -Node: Compatibility Mode1140698 -Node: Additions1141480 -Node: Accessing The Source1142405 -Node: Adding Code1143841 -Node: New Ports1150013 -Node: Derived Files1154495 -Ref: Derived Files-Footnote-11159970 -Ref: Derived Files-Footnote-21160004 -Ref: Derived Files-Footnote-31160600 -Node: Future Extensions1160714 -Node: Implementation Limitations1161320 -Node: Extension Design1162568 -Node: Old Extension Problems1163722 -Ref: Old Extension Problems-Footnote-11165239 -Node: Extension New Mechanism Goals1165296 -Ref: Extension New Mechanism Goals-Footnote-11168656 -Node: Extension Other Design Decisions1168845 -Node: Extension Future Growth1170953 -Node: Old Extension Mechanism1171789 -Node: Notes summary1173551 -Node: Basic Concepts1174737 -Node: Basic High Level1175418 -Ref: figure-general-flow1175690 -Ref: figure-process-flow1176289 -Ref: Basic High Level-Footnote-11179518 -Node: Basic Data Typing1179703 -Node: Glossary1183031 -Node: Copying1208189 -Node: GNU Free Documentation License1245745 -Node: Index1270881 +Node: Advanced Features Summary804123 +Node: Internationalization806056 +Node: I18N and L10N807536 +Node: Explaining gettext808222 +Ref: Explaining gettext-Footnote-1813251 +Ref: Explaining gettext-Footnote-2813435 +Node: Programmer i18n813600 +Ref: Programmer i18n-Footnote-1818466 +Node: Translator i18n818515 +Node: String Extraction819309 +Ref: String Extraction-Footnote-1820440 +Node: Printf Ordering820526 +Ref: Printf Ordering-Footnote-1823312 +Node: I18N Portability823376 +Ref: I18N Portability-Footnote-1825825 +Node: I18N Example825888 +Ref: I18N Example-Footnote-1828688 +Node: Gawk I18N828760 +Node: I18N Summary829398 +Node: Debugger830737 +Node: Debugging831759 +Node: Debugging Concepts832200 +Node: Debugging Terms834057 +Node: Awk Debugging836632 +Node: Sample Debugging Session837524 +Node: Debugger Invocation838044 +Node: Finding The Bug839428 +Node: List of Debugger Commands845903 +Node: Breakpoint Control847235 +Node: Debugger Execution Control850927 +Node: Viewing And Changing Data854291 +Node: Execution Stack857656 +Node: Debugger Info859294 +Node: Miscellaneous Debugger Commands863311 +Node: Readline Support868503 +Node: Limitations869395 +Node: Debugging Summary871492 +Node: Arbitrary Precision Arithmetic872660 +Node: Computer Arithmetic874076 +Ref: table-numeric-ranges877677 +Ref: Computer Arithmetic-Footnote-1878536 +Node: Math Definitions878593 +Ref: table-ieee-formats881880 +Ref: Math Definitions-Footnote-1882484 +Node: MPFR features882589 +Node: FP Math Caution884260 +Ref: FP Math Caution-Footnote-1885310 +Node: Inexactness of computations885679 +Node: Inexact representation886627 +Node: Comparing FP Values887982 +Node: Errors accumulate889055 +Node: Getting Accuracy890488 +Node: Try To Round893147 +Node: Setting precision894046 +Ref: table-predefined-precision-strings894730 +Node: Setting the rounding mode896524 +Ref: table-gawk-rounding-modes896888 +Ref: Setting the rounding mode-Footnote-1900342 +Node: Arbitrary Precision Integers900521 +Ref: Arbitrary Precision Integers-Footnote-1905425 +Node: POSIX Floating Point Problems905574 +Ref: POSIX Floating Point Problems-Footnote-1909450 +Node: Floating point summary909488 +Node: Dynamic Extensions911680 +Node: Extension Intro913232 +Node: Plugin License914498 +Node: Extension Mechanism Outline915295 +Ref: figure-load-extension915723 +Ref: figure-register-new-function917203 +Ref: figure-call-new-function918207 +Node: Extension API Description920193 +Node: Extension API Functions Introduction921643 +Node: General Data Types926479 +Ref: General Data Types-Footnote-1932166 +Node: Memory Allocation Functions932465 +Ref: Memory Allocation Functions-Footnote-1935295 +Node: Constructor Functions935391 +Node: Registration Functions937125 +Node: Extension Functions937810 +Node: Exit Callback Functions940106 +Node: Extension Version String941354 +Node: Input Parsers942004 +Node: Output Wrappers951819 +Node: Two-way processors956335 +Node: Printing Messages958539 +Ref: Printing Messages-Footnote-1959616 +Node: Updating `ERRNO'959768 +Node: Requesting Values960508 +Ref: table-value-types-returned961236 +Node: Accessing Parameters962194 +Node: Symbol Table Access963425 +Node: Symbol table by name963939 +Node: Symbol table by cookie965919 +Ref: Symbol table by cookie-Footnote-1970058 +Node: Cached values970121 +Ref: Cached values-Footnote-1973625 +Node: Array Manipulation973716 +Ref: Array Manipulation-Footnote-1974814 +Node: Array Data Types974853 +Ref: Array Data Types-Footnote-1977510 +Node: Array Functions977602 +Node: Flattening Arrays981456 +Node: Creating Arrays988343 +Node: Extension API Variables993110 +Node: Extension Versioning993746 +Node: Extension API Informational Variables995647 +Node: Extension API Boilerplate996735 +Node: Finding Extensions1000551 +Node: Extension Example1001111 +Node: Internal File Description1001883 +Node: Internal File Ops1005950 +Ref: Internal File Ops-Footnote-11017608 +Node: Using Internal File Ops1017748 +Ref: Using Internal File Ops-Footnote-11020131 +Node: Extension Samples1020404 +Node: Extension Sample File Functions1021928 +Node: Extension Sample Fnmatch1029530 +Node: Extension Sample Fork1031012 +Node: Extension Sample Inplace1032225 +Node: Extension Sample Ord1033900 +Node: Extension Sample Readdir1034736 +Ref: table-readdir-file-types1035592 +Node: Extension Sample Revout1036403 +Node: Extension Sample Rev2way1036994 +Node: Extension Sample Read write array1037735 +Node: Extension Sample Readfile1039674 +Node: Extension Sample Time1040769 +Node: Extension Sample API Tests1042118 +Node: gawkextlib1042609 +Node: Extension summary1045259 +Node: Extension Exercises1048941 +Node: Language History1049663 +Node: V7/SVR3.11051320 +Node: SVR41053501 +Node: POSIX1054946 +Node: BTL1056335 +Node: POSIX/GNU1057069 +Node: Feature History1062698 +Node: Common Extensions1075789 +Node: Ranges and Locales1077113 +Ref: Ranges and Locales-Footnote-11081752 +Ref: Ranges and Locales-Footnote-21081779 +Ref: Ranges and Locales-Footnote-31082013 +Node: Contributors1082234 +Node: History summary1087774 +Node: Installation1089143 +Node: Gawk Distribution1090099 +Node: Getting1090583 +Node: Extracting1091407 +Node: Distribution contents1093049 +Node: Unix Installation1098819 +Node: Quick Installation1099436 +Node: Additional Configuration Options1101867 +Node: Configuration Philosophy1103607 +Node: Non-Unix Installation1105958 +Node: PC Installation1106416 +Node: PC Binary Installation1107742 +Node: PC Compiling1109590 +Ref: PC Compiling-Footnote-11112611 +Node: PC Testing1112716 +Node: PC Using1113892 +Node: Cygwin1118007 +Node: MSYS1118830 +Node: VMS Installation1119328 +Node: VMS Compilation1120120 +Ref: VMS Compilation-Footnote-11121342 +Node: VMS Dynamic Extensions1121400 +Node: VMS Installation Details1123084 +Node: VMS Running1125336 +Node: VMS GNV1128177 +Node: VMS Old Gawk1128911 +Node: Bugs1129381 +Node: Other Versions1133285 +Node: Installation summary1139498 +Node: Notes1140554 +Node: Compatibility Mode1141419 +Node: Additions1142201 +Node: Accessing The Source1143126 +Node: Adding Code1144562 +Node: New Ports1150734 +Node: Derived Files1155216 +Ref: Derived Files-Footnote-11160691 +Ref: Derived Files-Footnote-21160725 +Ref: Derived Files-Footnote-31161321 +Node: Future Extensions1161435 +Node: Implementation Limitations1162041 +Node: Extension Design1163289 +Node: Old Extension Problems1164443 +Ref: Old Extension Problems-Footnote-11165960 +Node: Extension New Mechanism Goals1166017 +Ref: Extension New Mechanism Goals-Footnote-11169377 +Node: Extension Other Design Decisions1169566 +Node: Extension Future Growth1171674 +Node: Old Extension Mechanism1172510 +Node: Notes summary1174272 +Node: Basic Concepts1175458 +Node: Basic High Level1176139 +Ref: figure-general-flow1176411 +Ref: figure-process-flow1177010 +Ref: Basic High Level-Footnote-11180239 +Node: Basic Data Typing1180424 +Node: Glossary1183752 +Node: Copying1208910 +Node: GNU Free Documentation License1246466 +Node: Index1271602 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 20087fa7..0f2b2985 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -27812,8 +27812,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 @@ -27910,6 +27909,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 |