diff options
| -rw-r--r-- | doc/ChangeLog | 1 | ||||
| -rw-r--r-- | doc/gawk.info | 1039 | ||||
| -rw-r--r-- | doc/gawk.texi | 227 |
3 files changed, 820 insertions, 447 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 32ef1a1c..869ead26 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -2,6 +2,7 @@ * awkcard.in, gawk.1, gawk.texi: Updated. Mostly for new API stuff but also some other things. + * gawk.texi (Derived Files): New node. 2012-08-01 Arnold D. Robbins <arnold@skeeve.com> diff --git a/doc/gawk.info b/doc/gawk.info index 65bf903c..bcbdb04c 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -513,6 +513,8 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) `gawk'. * New Ports:: Porting `gawk' to a new operating system. +* Derived Files:: Why derived files are kept in the + `git' repository. * Future Extensions:: New features that may be implemented one day. * Basic High Level:: The high level view. @@ -21438,14 +21440,18 @@ the current version of `gawk'. - The `AWKLIBPATH' environment variable for specifying a path search for the `-l' command-line option (*note Options::). - - The ability to use GNU-style long-named options that start - with `--' and the `--bignum', `--characters-as-bytes', - `--copyright', `--debug', `--dump-variables', `--exec', - `--gen-pot', `--include', `--lint', `--lint-old', `--load', + - The `-b', `-c', `-C', `-d', `-D', `-e', `-E', `-g', `-h', + `-i', `-l', `-L', `-M', `-n', `-N', `-o', `-O', `-p', `-P', + `-r', `-S', `-t', and `-V' short options. Also, the ability + to use GNU-style long-named options that start with `--' and + the `--assign', `--bignum', `--characters-as-bytes', + `--copyright', `--debug', `--dump-variables', `--execle', + `--field-separator', `--file', `--gen-pot', `--help', + `--include', `--lint', `--lint-old', `--load', `--non-decimal-data', `--optimize', `--posix', `--pretty-print', `--profile', `--re-interval', `--sandbox', - `--source', `--traditional', and `--use-lc-numeric' options - (*note Options::). + `--source', `--traditional', `--use-lc-numeric', and + `--version' long options (*note Options::). * Support for the following obsolete systems was removed from the code and the documentation for `gawk' version 4.0: @@ -22836,6 +22842,8 @@ as well as any considerations you should bear in mind. `gawk'. * New Ports:: Porting `gawk' to a new operating system. +* Derived Files:: Why derived files are kept in the + `git' repository. File: gawk.info, Node: Accessing The Source, Next: Adding Code, Up: Additions @@ -23005,7 +23013,7 @@ isn't possible for me to do that with a minimum of extra work, then I probably will not. -File: gawk.info, Node: New Ports, Prev: Adding Code, Up: Additions +File: gawk.info, Node: New Ports, Next: Derived Files, Prev: Adding Code, Up: Additions C.2.3 Porting `gawk' to a New Operating System ---------------------------------------------- @@ -23087,6 +23095,149 @@ code that is already there. style and brace layout that suits your taste. +File: gawk.info, Node: Derived Files, Prev: New Ports, Up: Additions + +C.2.4 Why Generated Files Are Kept In `git' +------------------------------------------- + +If you look at the `gawk' source in the `git' repository, you will +notice that it includes files that are automatically generated by GNU +infrastructure tools, such as `Makefile.in' from `automake' and even +`configure' from `autoconf'. + + This is different from many Free Software projects that do not store +the derived files, because that keeps the repository less cluttered, +and it is easier to see the substantive changes when comparing versions +and trying to understand what changed between commits. + + However, there are two reasons why the `gawk' maintainer likes to +have everything in the repository. + + First, because it is then easy to reproduce any given version +completely, without relying upon the availability of (older, likely +obsolete, and maybe even impossible to find) other tools. + + As an extreme example, if you ever even think about trying to +compile, oh, say, the V7 `awk', you will discover that not only do you +have to bootstrap the V7 `yacc' to do so, but you also need the V7 +`lex'. And the latter is pretty much impossible to bring up on a +modern GNU/Linux system.(1) + + (Or, let's say `gawk' 1.2 required `bison' whatever-it-was in 1989 +and that there was no `awkgram.c' file in the repository. Is there a +guarantee that we could find that `bison' version? Or that _it_ would +build?) + + If the repository has all the generated files, then it's easy to +just check them out and build. (Or _easier_, depending upon how far +back we go. `:-)') + + And that brings us to the second (and stronger) reason why all the +files really need to be in `git'. It boils down to who do you cater +to--the `gawk' developer(s), or the user who just wants to check out a +version and try it out? + + The `gawk' maintainer wants it to be possible for any interested +`awk' user in the world to just clone the repository, check out the +branch of interest and build it. Without their having to have the +correct version(s) of the autotools.(2) That is the point of the +`bootstrap.sh' file. It touches the various other files in the right +order such that + + # The canonical incantation for building GNU software: + ./bootstrap.sh && ./configure && make + +will _just work_. + + This is extremely important for the `master' and `gawk-X.Y-stable' +branches. + + Further, the `gawk' maintainer would argue that it's also important +for the `gawk' developers. When he tried to check out the `xgawk' +branch(3) to build it, he couldn't. (No `ltmain.sh' file, and he had no +idea how to create it, and that was not the only problem.) + + He felt _extremely_ frustrated. With respect to that branch, the +maintainer is no different than Jane User who wants to try to build +`gawk-4.0-stable' or `master' from the repository. + + Thus, the maintainer thinks that it's not just important, but +critical, that for any given branch, the above incantation _just works_. + + What are some of the consequences and/or actions to take? + + 1. We don't mind that there are differing files in the different + branches as a result of different versions of the autotools. + + A. It's the maintainer's job to merge them and he will deal with + it. + + B. He is really good at `git diff x y > /tmp/diff1 ; gvim + /tmp/diff1' to remove the diffs that aren't of interest in + order to review code. `:-)' + + 2. It would certainly help if everyone used the same versions of the + GNU tools as he does, which in general are the latest released + versions of `automake', `autoconf', `bison', and `gettext'. + + A. Installing from source is quite easy. It's how the maintainer + worked for years under Fedora. He had `/usr/local/bin' at + the front of hs `PATH' and just did: + + wget http://ftp.gnu.org/gnu/PACKAGE/PACKAGE-X.Y.Z.tar.gz + tar -xpzvf PACKAGE-X.Y.Z.tar.gz + cd PACKAGE-X.Y.Z + ./configure && make && make check + make install # as root + + B. These days the maintainer uses Ubuntu 10.11 which is medium + current, but he is already doing the above for `autoconf' and + `bison'. + + + + Most of the above was originally written by the maintainer to other +`gawk' developers. It raised the objection from one of the devlopers +"... that anybody pulling down the source from `git' is not an end +user." + + However, this is not true. There are "power `awk' users" who can +build `gawk' (using the magic incantation shown previously) but who +can't program in C. Thus, the major branches should be kept buildable +all the time. + + It was then suggested that there be a `cron' job to create nightly +tarballs of "the source." Here, the problem is that there are source +trees, corresponding to the various branches! So, nightly tar balls +aren't the answer, especially as the repository can go for weeks +without significant change being introduced. + + Fortunately, the `git' server can meet this need. For any given +branch named BRANCHNAME, use: + + wget http://git.savannah.gnu.org/cgit/gawk.git/snapshot/gawk-BRANCHNAME.tar.gz + +to retrieve a snapshot of the given branch. + + ---------- Footnotes ---------- + + (1) We tried. It was painful. + + (2) There is one GNU program that is (in our opinion) severely +difficult to bootstrap from the `git' repository. For example, on the +author's old (but still working) PowerPC macintosh with Mac OS X 10.5, +it was necessary to bootstrap a ton of software, starting with `git' +itself, in order to try to work with the latest code. It's not +pleasant, and especially on older systems, it's a big waste of time. + + Starting with the latest tarball was no picnic either. The +maintainers had dropped `.gz' and `.bz2' files and only distribute +`.tar.xz' files. It was necessary to bootstrap `xz' first! + + (3) A branch created by one of the other developers that did not +include the generated files. + + File: gawk.info, Node: Future Extensions, Prev: Additions, Up: Notes C.3 Probable Future Extensions @@ -28140,440 +28291,444 @@ Index Tag Table: Node: Top1352 -Node: Foreword31579 -Node: Preface35924 -Ref: Preface-Footnote-138977 -Ref: Preface-Footnote-239083 -Node: History39315 -Node: Names41706 -Ref: Names-Footnote-143183 -Node: This Manual43255 -Ref: This Manual-Footnote-148159 -Node: Conventions48259 -Node: Manual History50393 -Ref: Manual History-Footnote-153663 -Ref: Manual History-Footnote-253704 -Node: How To Contribute53778 -Node: Acknowledgments54922 -Node: Getting Started59418 -Node: Running gawk61797 -Node: One-shot62983 -Node: Read Terminal64208 -Ref: Read Terminal-Footnote-165858 -Ref: Read Terminal-Footnote-266134 -Node: Long66305 -Node: Executable Scripts67681 -Ref: Executable Scripts-Footnote-169550 -Ref: Executable Scripts-Footnote-269652 -Node: Comments70199 -Node: Quoting72666 -Node: DOS Quoting77289 -Node: Sample Data Files77964 -Node: Very Simple80996 -Node: Two Rules85595 -Node: More Complex87742 -Ref: More Complex-Footnote-190672 -Node: Statements/Lines90757 -Ref: Statements/Lines-Footnote-195219 -Node: Other Features95484 -Node: When96412 -Node: Invoking Gawk98559 -Node: Command Line100020 -Node: Options100803 -Ref: Options-Footnote-1116201 -Node: Other Arguments116226 -Node: Naming Standard Input118884 -Node: Environment Variables119978 -Node: AWKPATH Variable120536 -Ref: AWKPATH Variable-Footnote-1123294 -Node: AWKLIBPATH Variable123554 -Node: Other Environment Variables124151 -Node: Exit Status126646 -Node: Include Files127321 -Node: Loading Shared Libraries130890 -Node: Obsolete132115 -Node: Undocumented132812 -Node: Regexp133055 -Node: Regexp Usage134444 -Node: Escape Sequences136470 -Node: Regexp Operators142233 -Ref: Regexp Operators-Footnote-1149613 -Ref: Regexp Operators-Footnote-2149760 -Node: Bracket Expressions149858 -Ref: table-char-classes151748 -Node: GNU Regexp Operators154271 -Node: Case-sensitivity157994 -Ref: Case-sensitivity-Footnote-1160962 -Ref: Case-sensitivity-Footnote-2161197 -Node: Leftmost Longest161305 -Node: Computed Regexps162506 -Node: Reading Files165916 -Node: Records167919 -Ref: Records-Footnote-1176593 -Node: Fields176630 -Ref: Fields-Footnote-1179663 -Node: Nonconstant Fields179749 -Node: Changing Fields181951 -Node: Field Separators187932 -Node: Default Field Splitting190561 -Node: Regexp Field Splitting191678 -Node: Single Character Fields195020 -Node: Command Line Field Separator196079 -Node: Field Splitting Summary199520 -Ref: Field Splitting Summary-Footnote-1202712 -Node: Constant Size202813 -Node: Splitting By Content207397 -Ref: Splitting By Content-Footnote-1211123 -Node: Multiple Line211163 -Ref: Multiple Line-Footnote-1217010 -Node: Getline217189 -Node: Plain Getline219405 -Node: Getline/Variable221494 -Node: Getline/File222635 -Node: Getline/Variable/File223957 -Ref: Getline/Variable/File-Footnote-1225556 -Node: Getline/Pipe225643 -Node: Getline/Variable/Pipe228203 -Node: Getline/Coprocess229310 -Node: Getline/Variable/Coprocess230553 -Node: Getline Notes231267 -Node: Getline Summary233209 -Ref: table-getline-variants233617 -Node: Read Timeout234473 -Ref: Read Timeout-Footnote-1238218 -Node: Command line directories238275 -Node: Printing238905 -Node: Print240536 -Node: Print Examples241873 -Node: Output Separators244657 -Node: OFMT246417 -Node: Printf247775 -Node: Basic Printf248681 -Node: Control Letters250220 -Node: Format Modifiers254032 -Node: Printf Examples260041 -Node: Redirection262756 -Node: Special Files269740 -Node: Special FD270273 -Ref: Special FD-Footnote-1273898 -Node: Special Network273972 -Node: Special Caveats274822 -Node: Close Files And Pipes275618 -Ref: Close Files And Pipes-Footnote-1282641 -Ref: Close Files And Pipes-Footnote-2282789 -Node: Expressions282939 -Node: Values284071 -Node: Constants284747 -Node: Scalar Constants285427 -Ref: Scalar Constants-Footnote-1286286 -Node: Nondecimal-numbers286468 -Node: Regexp Constants289527 -Node: Using Constant Regexps290002 -Node: Variables293057 -Node: Using Variables293712 -Node: Assignment Options295436 -Node: Conversion297308 -Ref: table-locale-affects302684 -Ref: Conversion-Footnote-1303308 -Node: All Operators303417 -Node: Arithmetic Ops304047 -Node: Concatenation306552 -Ref: Concatenation-Footnote-1309345 -Node: Assignment Ops309465 -Ref: table-assign-ops314453 -Node: Increment Ops315861 -Node: Truth Values and Conditions319331 -Node: Truth Values320414 -Node: Typing and Comparison321463 -Node: Variable Typing322252 -Ref: Variable Typing-Footnote-1326149 -Node: Comparison Operators326271 -Ref: table-relational-ops326681 -Node: POSIX String Comparison330230 -Ref: POSIX String Comparison-Footnote-1331186 -Node: Boolean Ops331324 -Ref: Boolean Ops-Footnote-1335402 -Node: Conditional Exp335493 -Node: Function Calls337225 -Node: Precedence340819 -Node: Locales344488 -Node: Patterns and Actions345577 -Node: Pattern Overview346631 -Node: Regexp Patterns348300 -Node: Expression Patterns348843 -Node: Ranges352528 -Node: BEGIN/END355494 -Node: Using BEGIN/END356256 -Ref: Using BEGIN/END-Footnote-1358987 -Node: I/O And BEGIN/END359093 -Node: BEGINFILE/ENDFILE361375 -Node: Empty364279 -Node: Using Shell Variables364595 -Node: Action Overview366880 -Node: Statements369237 -Node: If Statement371091 -Node: While Statement372590 -Node: Do Statement374634 -Node: For Statement375790 -Node: Switch Statement378942 -Node: Break Statement381039 -Node: Continue Statement383029 -Node: Next Statement384822 -Node: Nextfile Statement387212 -Node: Exit Statement389757 -Node: Built-in Variables392173 -Node: User-modified393268 -Ref: User-modified-Footnote-1401623 -Node: Auto-set401685 -Ref: Auto-set-Footnote-1411593 -Node: ARGC and ARGV411798 -Node: Arrays415649 -Node: Array Basics417154 -Node: Array Intro417980 -Node: Reference to Elements422298 -Node: Assigning Elements424568 -Node: Array Example425059 -Node: Scanning an Array426791 -Node: Controlling Scanning429105 -Ref: Controlling Scanning-Footnote-1434038 -Node: Delete434354 -Ref: Delete-Footnote-1436789 -Node: Numeric Array Subscripts436846 -Node: Uninitialized Subscripts439029 -Node: Multi-dimensional440657 -Node: Multi-scanning443751 -Node: Arrays of Arrays445342 -Node: Functions449987 -Node: Built-in450809 -Node: Calling Built-in451887 -Node: Numeric Functions453875 -Ref: Numeric Functions-Footnote-1457707 -Ref: Numeric Functions-Footnote-2458064 -Ref: Numeric Functions-Footnote-3458112 -Node: String Functions458381 -Ref: String Functions-Footnote-1481878 -Ref: String Functions-Footnote-2482007 -Ref: String Functions-Footnote-3482255 -Node: Gory Details482342 -Ref: table-sub-escapes484021 -Ref: table-sub-posix-92485375 -Ref: table-sub-proposed486718 -Ref: table-posix-sub488068 -Ref: table-gensub-escapes489614 -Ref: Gory Details-Footnote-1490821 -Ref: Gory Details-Footnote-2490872 -Node: I/O Functions491023 -Ref: I/O Functions-Footnote-1497678 -Node: Time Functions497825 -Ref: Time Functions-Footnote-1508717 -Ref: Time Functions-Footnote-2508785 -Ref: Time Functions-Footnote-3508943 -Ref: Time Functions-Footnote-4509054 -Ref: Time Functions-Footnote-5509166 -Ref: Time Functions-Footnote-6509393 -Node: Bitwise Functions509659 -Ref: table-bitwise-ops510217 -Ref: Bitwise Functions-Footnote-1514438 -Node: Type Functions514622 -Node: I18N Functions515092 -Node: User-defined516719 -Node: Definition Syntax517523 -Ref: Definition Syntax-Footnote-1522433 -Node: Function Example522502 -Node: Function Caveats525096 -Node: Calling A Function525517 -Node: Variable Scope526632 -Node: Pass By Value/Reference528607 -Node: Return Statement532047 -Node: Dynamic Typing535028 -Node: Indirect Calls535763 -Node: Internationalization545448 -Node: I18N and L10N546887 -Node: Explaining gettext547573 -Ref: Explaining gettext-Footnote-1552639 -Ref: Explaining gettext-Footnote-2552823 -Node: Programmer i18n552988 -Node: Translator i18n557188 -Node: String Extraction557981 -Ref: String Extraction-Footnote-1558942 -Node: Printf Ordering559028 -Ref: Printf Ordering-Footnote-1561812 -Node: I18N Portability561876 -Ref: I18N Portability-Footnote-1564325 -Node: I18N Example564388 -Ref: I18N Example-Footnote-1567023 -Node: Gawk I18N567095 -Node: Arbitrary Precision Arithmetic567712 -Ref: Arbitrary Precision Arithmetic-Footnote-1570464 -Node: Floating-point Programming570612 -Node: Floating-point Representation575882 -Node: Floating-point Context576986 -Ref: table-ieee-formats577821 -Node: Rounding Mode579191 -Ref: table-rounding-modes579818 -Ref: Rounding Mode-Footnote-1582941 -Node: Arbitrary Precision Floats583122 -Ref: Arbitrary Precision Floats-Footnote-1585163 -Node: Setting Precision585474 -Node: Setting Rounding Mode588232 -Node: Floating-point Constants589149 -Node: Changing Precision590568 -Ref: Changing Precision-Footnote-1591968 -Node: Exact Arithmetic592141 -Node: Integer Programming595154 -Node: Arbitrary Precision Integers596934 -Ref: Arbitrary Precision Integers-Footnote-1599958 -Node: MPFR and GMP Libraries600104 -Node: Advanced Features600489 -Node: Nondecimal Data602012 -Node: Array Sorting603595 -Node: Controlling Array Traversal604292 -Node: Array Sorting Functions612529 -Ref: Array Sorting Functions-Footnote-1616203 -Ref: Array Sorting Functions-Footnote-2616296 -Node: Two-way I/O616490 -Ref: Two-way I/O-Footnote-1621922 -Node: TCP/IP Networking621992 -Node: Profiling624836 -Node: Library Functions632290 -Ref: Library Functions-Footnote-1635297 -Node: Library Names635468 -Ref: Library Names-Footnote-1638939 -Ref: Library Names-Footnote-2639159 -Node: General Functions639245 -Node: Strtonum Function640198 -Node: Assert Function643128 -Node: Round Function646454 -Node: Cliff Random Function647997 -Node: Ordinal Functions649013 -Ref: Ordinal Functions-Footnote-1652083 -Ref: Ordinal Functions-Footnote-2652335 -Node: Join Function652544 -Ref: Join Function-Footnote-1654315 -Node: Getlocaltime Function654515 -Node: Data File Management658230 -Node: Filetrans Function658862 -Node: Rewind Function663001 -Node: File Checking664388 -Node: Empty Files665482 -Node: Ignoring Assigns667712 -Node: Getopt Function669265 -Ref: Getopt Function-Footnote-1680569 -Node: Passwd Functions680772 -Ref: Passwd Functions-Footnote-1689747 -Node: Group Functions689835 -Node: Walking Arrays697919 -Node: Sample Programs699488 -Node: Running Examples700153 -Node: Clones700881 -Node: Cut Program702105 -Node: Egrep Program711950 -Ref: Egrep Program-Footnote-1719723 -Node: Id Program719833 -Node: Split Program723449 -Ref: Split Program-Footnote-1726968 -Node: Tee Program727096 -Node: Uniq Program729899 -Node: Wc Program737328 -Ref: Wc Program-Footnote-1741594 -Ref: Wc Program-Footnote-2741794 -Node: Miscellaneous Programs741886 -Node: Dupword Program743074 -Node: Alarm Program745105 -Node: Translate Program749854 -Ref: Translate Program-Footnote-1754241 -Ref: Translate Program-Footnote-2754469 -Node: Labels Program754603 -Ref: Labels Program-Footnote-1757974 -Node: Word Sorting758058 -Node: History Sorting761942 -Node: Extract Program763781 -Ref: Extract Program-Footnote-1771264 -Node: Simple Sed771392 -Node: Igawk Program774454 -Ref: Igawk Program-Footnote-1789611 -Ref: Igawk Program-Footnote-2789812 -Node: Anagram Program789950 -Node: Signature Program793018 -Node: Debugger794118 -Node: Debugging795072 -Node: Debugging Concepts795505 -Node: Debugging Terms797361 -Node: Awk Debugging799958 -Node: Sample Debugging Session800850 -Node: Debugger Invocation801370 -Node: Finding The Bug802699 -Node: List of Debugger Commands809187 -Node: Breakpoint Control810521 -Node: Debugger Execution Control814185 -Node: Viewing And Changing Data817545 -Node: Execution Stack820901 -Node: Debugger Info822368 -Node: Miscellaneous Debugger Commands826349 -Node: Readline Support831794 -Node: Limitations832625 -Node: Dynamic Extensions834877 -Node: Plugin License835773 -Node: Sample Library836387 -Node: Internal File Description837071 -Node: Internal File Ops840784 -Ref: Internal File Ops-Footnote-1845347 -Node: Using Internal File Ops845487 -Node: Language History847863 -Node: V7/SVR3.1849385 -Node: SVR4851706 -Node: POSIX853148 -Node: BTL854156 -Node: POSIX/GNU854890 -Node: Common Extensions860146 -Node: Ranges and Locales861253 -Ref: Ranges and Locales-Footnote-1865857 -Node: Contributors866078 -Node: Installation870374 -Node: Gawk Distribution871268 -Node: Getting871752 -Node: Extracting872578 -Node: Distribution contents874270 -Node: Unix Installation879492 -Node: Quick Installation880109 -Node: Additional Configuration Options882071 -Node: Configuration Philosophy883548 -Node: Non-Unix Installation885890 -Node: PC Installation886348 -Node: PC Binary Installation887647 -Node: PC Compiling889495 -Node: PC Testing892439 -Node: PC Using893615 -Node: Cygwin897800 -Node: MSYS898800 -Node: VMS Installation899314 -Node: VMS Compilation899917 -Ref: VMS Compilation-Footnote-1900924 -Node: VMS Installation Details900982 -Node: VMS Running902617 -Node: VMS Old Gawk904224 -Node: Bugs904698 -Node: Other Versions908550 -Node: Notes913865 -Node: Compatibility Mode914452 -Node: Additions915235 -Node: Accessing The Source916046 -Node: Adding Code917471 -Node: New Ports923479 -Node: Future Extensions927592 -Node: Basic Concepts929079 -Node: Basic High Level929836 -Ref: Basic High Level-Footnote-1933871 -Node: Basic Data Typing934056 -Node: Floating Point Issues938581 -Node: String Conversion Precision939664 -Ref: String Conversion Precision-Footnote-1941364 -Node: Unexpected Results941473 -Node: POSIX Floating Point Problems943299 -Ref: POSIX Floating Point Problems-Footnote-1947004 -Node: Glossary947042 -Node: Copying972018 -Node: GNU Free Documentation License1009575 -Node: Index1034712 +Node: Foreword31701 +Node: Preface36046 +Ref: Preface-Footnote-139099 +Ref: Preface-Footnote-239205 +Node: History39437 +Node: Names41828 +Ref: Names-Footnote-143305 +Node: This Manual43377 +Ref: This Manual-Footnote-148281 +Node: Conventions48381 +Node: Manual History50515 +Ref: Manual History-Footnote-153785 +Ref: Manual History-Footnote-253826 +Node: How To Contribute53900 +Node: Acknowledgments55044 +Node: Getting Started59540 +Node: Running gawk61919 +Node: One-shot63105 +Node: Read Terminal64330 +Ref: Read Terminal-Footnote-165980 +Ref: Read Terminal-Footnote-266256 +Node: Long66427 +Node: Executable Scripts67803 +Ref: Executable Scripts-Footnote-169672 +Ref: Executable Scripts-Footnote-269774 +Node: Comments70321 +Node: Quoting72788 +Node: DOS Quoting77411 +Node: Sample Data Files78086 +Node: Very Simple81118 +Node: Two Rules85717 +Node: More Complex87864 +Ref: More Complex-Footnote-190794 +Node: Statements/Lines90879 +Ref: Statements/Lines-Footnote-195341 +Node: Other Features95606 +Node: When96534 +Node: Invoking Gawk98681 +Node: Command Line100142 +Node: Options100925 +Ref: Options-Footnote-1116323 +Node: Other Arguments116348 +Node: Naming Standard Input119006 +Node: Environment Variables120100 +Node: AWKPATH Variable120658 +Ref: AWKPATH Variable-Footnote-1123416 +Node: AWKLIBPATH Variable123676 +Node: Other Environment Variables124273 +Node: Exit Status126768 +Node: Include Files127443 +Node: Loading Shared Libraries131012 +Node: Obsolete132237 +Node: Undocumented132934 +Node: Regexp133177 +Node: Regexp Usage134566 +Node: Escape Sequences136592 +Node: Regexp Operators142355 +Ref: Regexp Operators-Footnote-1149735 +Ref: Regexp Operators-Footnote-2149882 +Node: Bracket Expressions149980 +Ref: table-char-classes151870 +Node: GNU Regexp Operators154393 +Node: Case-sensitivity158116 +Ref: Case-sensitivity-Footnote-1161084 +Ref: Case-sensitivity-Footnote-2161319 +Node: Leftmost Longest161427 +Node: Computed Regexps162628 +Node: Reading Files166038 +Node: Records168041 +Ref: Records-Footnote-1176715 +Node: Fields176752 +Ref: Fields-Footnote-1179785 +Node: Nonconstant Fields179871 +Node: Changing Fields182073 +Node: Field Separators188054 +Node: Default Field Splitting190683 +Node: Regexp Field Splitting191800 +Node: Single Character Fields195142 +Node: Command Line Field Separator196201 +Node: Field Splitting Summary199642 +Ref: Field Splitting Summary-Footnote-1202834 +Node: Constant Size202935 +Node: Splitting By Content207519 +Ref: Splitting By Content-Footnote-1211245 +Node: Multiple Line211285 +Ref: Multiple Line-Footnote-1217132 +Node: Getline217311 +Node: Plain Getline219527 +Node: Getline/Variable221616 +Node: Getline/File222757 +Node: Getline/Variable/File224079 +Ref: Getline/Variable/File-Footnote-1225678 +Node: Getline/Pipe225765 +Node: Getline/Variable/Pipe228325 +Node: Getline/Coprocess229432 +Node: Getline/Variable/Coprocess230675 +Node: Getline Notes231389 +Node: Getline Summary233331 +Ref: table-getline-variants233739 +Node: Read Timeout234595 +Ref: Read Timeout-Footnote-1238340 +Node: Command line directories238397 +Node: Printing239027 +Node: Print240658 +Node: Print Examples241995 +Node: Output Separators244779 +Node: OFMT246539 +Node: Printf247897 +Node: Basic Printf248803 +Node: Control Letters250342 +Node: Format Modifiers254154 +Node: Printf Examples260163 +Node: Redirection262878 +Node: Special Files269862 +Node: Special FD270395 +Ref: Special FD-Footnote-1274020 +Node: Special Network274094 +Node: Special Caveats274944 +Node: Close Files And Pipes275740 +Ref: Close Files And Pipes-Footnote-1282763 +Ref: Close Files And Pipes-Footnote-2282911 +Node: Expressions283061 +Node: Values284193 +Node: Constants284869 +Node: Scalar Constants285549 +Ref: Scalar Constants-Footnote-1286408 +Node: Nondecimal-numbers286590 +Node: Regexp Constants289649 +Node: Using Constant Regexps290124 +Node: Variables293179 +Node: Using Variables293834 +Node: Assignment Options295558 +Node: Conversion297430 +Ref: table-locale-affects302806 +Ref: Conversion-Footnote-1303430 +Node: All Operators303539 +Node: Arithmetic Ops304169 +Node: Concatenation306674 +Ref: Concatenation-Footnote-1309467 +Node: Assignment Ops309587 +Ref: table-assign-ops314575 +Node: Increment Ops315983 +Node: Truth Values and Conditions319453 +Node: Truth Values320536 +Node: Typing and Comparison321585 +Node: Variable Typing322374 +Ref: Variable Typing-Footnote-1326271 +Node: Comparison Operators326393 +Ref: table-relational-ops326803 +Node: POSIX String Comparison330352 +Ref: POSIX String Comparison-Footnote-1331308 +Node: Boolean Ops331446 +Ref: Boolean Ops-Footnote-1335524 +Node: Conditional Exp335615 +Node: Function Calls337347 +Node: Precedence340941 +Node: Locales344610 +Node: Patterns and Actions345699 +Node: Pattern Overview346753 +Node: Regexp Patterns348422 +Node: Expression Patterns348965 +Node: Ranges352650 +Node: BEGIN/END355616 +Node: Using BEGIN/END356378 +Ref: Using BEGIN/END-Footnote-1359109 +Node: I/O And BEGIN/END359215 +Node: BEGINFILE/ENDFILE361497 +Node: Empty364401 +Node: Using Shell Variables364717 +Node: Action Overview367002 +Node: Statements369359 +Node: If Statement371213 +Node: While Statement372712 +Node: Do Statement374756 +Node: For Statement375912 +Node: Switch Statement379064 +Node: Break Statement381161 +Node: Continue Statement383151 +Node: Next Statement384944 +Node: Nextfile Statement387334 +Node: Exit Statement389879 +Node: Built-in Variables392295 +Node: User-modified393390 +Ref: User-modified-Footnote-1401745 +Node: Auto-set401807 +Ref: Auto-set-Footnote-1411715 +Node: ARGC and ARGV411920 +Node: Arrays415771 +Node: Array Basics417276 +Node: Array Intro418102 +Node: Reference to Elements422420 +Node: Assigning Elements424690 +Node: Array Example425181 +Node: Scanning an Array426913 +Node: Controlling Scanning429227 +Ref: Controlling Scanning-Footnote-1434160 +Node: Delete434476 +Ref: Delete-Footnote-1436911 +Node: Numeric Array Subscripts436968 +Node: Uninitialized Subscripts439151 +Node: Multi-dimensional440779 +Node: Multi-scanning443873 +Node: Arrays of Arrays445464 +Node: Functions450109 +Node: Built-in450931 +Node: Calling Built-in452009 +Node: Numeric Functions453997 +Ref: Numeric Functions-Footnote-1457829 +Ref: Numeric Functions-Footnote-2458186 +Ref: Numeric Functions-Footnote-3458234 +Node: String Functions458503 +Ref: String Functions-Footnote-1482000 +Ref: String Functions-Footnote-2482129 +Ref: String Functions-Footnote-3482377 +Node: Gory Details482464 +Ref: table-sub-escapes484143 +Ref: table-sub-posix-92485497 +Ref: table-sub-proposed486840 +Ref: table-posix-sub488190 +Ref: table-gensub-escapes489736 +Ref: Gory Details-Footnote-1490943 +Ref: Gory Details-Footnote-2490994 +Node: I/O Functions491145 +Ref: I/O Functions-Footnote-1497800 +Node: Time Functions497947 +Ref: Time Functions-Footnote-1508839 +Ref: Time Functions-Footnote-2508907 +Ref: Time Functions-Footnote-3509065 +Ref: Time Functions-Footnote-4509176 +Ref: Time Functions-Footnote-5509288 +Ref: Time Functions-Footnote-6509515 +Node: Bitwise Functions509781 +Ref: table-bitwise-ops510339 +Ref: Bitwise Functions-Footnote-1514560 +Node: Type Functions514744 +Node: I18N Functions515214 +Node: User-defined516841 +Node: Definition Syntax517645 +Ref: Definition Syntax-Footnote-1522555 +Node: Function Example522624 +Node: Function Caveats525218 +Node: Calling A Function525639 +Node: Variable Scope526754 +Node: Pass By Value/Reference528729 +Node: Return Statement532169 +Node: Dynamic Typing535150 +Node: Indirect Calls535885 +Node: Internationalization545570 +Node: I18N and L10N547009 +Node: Explaining gettext547695 +Ref: Explaining gettext-Footnote-1552761 +Ref: Explaining gettext-Footnote-2552945 +Node: Programmer i18n553110 +Node: Translator i18n557310 +Node: String Extraction558103 +Ref: String Extraction-Footnote-1559064 +Node: Printf Ordering559150 +Ref: Printf Ordering-Footnote-1561934 +Node: I18N Portability561998 +Ref: I18N Portability-Footnote-1564447 +Node: I18N Example564510 +Ref: I18N Example-Footnote-1567145 +Node: Gawk I18N567217 +Node: Arbitrary Precision Arithmetic567834 +Ref: Arbitrary Precision Arithmetic-Footnote-1570586 +Node: Floating-point Programming570734 +Node: Floating-point Representation576004 +Node: Floating-point Context577108 +Ref: table-ieee-formats577943 +Node: Rounding Mode579313 +Ref: table-rounding-modes579940 +Ref: Rounding Mode-Footnote-1583063 +Node: Arbitrary Precision Floats583244 +Ref: Arbitrary Precision Floats-Footnote-1585285 +Node: Setting Precision585596 +Node: Setting Rounding Mode588354 +Node: Floating-point Constants589271 +Node: Changing Precision590690 +Ref: Changing Precision-Footnote-1592090 +Node: Exact Arithmetic592263 +Node: Integer Programming595276 +Node: Arbitrary Precision Integers597056 +Ref: Arbitrary Precision Integers-Footnote-1600080 +Node: MPFR and GMP Libraries600226 +Node: Advanced Features600611 +Node: Nondecimal Data602134 +Node: Array Sorting603717 +Node: Controlling Array Traversal604414 +Node: Array Sorting Functions612651 +Ref: Array Sorting Functions-Footnote-1616325 +Ref: Array Sorting Functions-Footnote-2616418 +Node: Two-way I/O616612 +Ref: Two-way I/O-Footnote-1622044 +Node: TCP/IP Networking622114 +Node: Profiling624958 +Node: Library Functions632412 +Ref: Library Functions-Footnote-1635419 +Node: Library Names635590 +Ref: Library Names-Footnote-1639061 +Ref: Library Names-Footnote-2639281 +Node: General Functions639367 +Node: Strtonum Function640320 +Node: Assert Function643250 +Node: Round Function646576 +Node: Cliff Random Function648119 +Node: Ordinal Functions649135 +Ref: Ordinal Functions-Footnote-1652205 +Ref: Ordinal Functions-Footnote-2652457 +Node: Join Function652666 +Ref: Join Function-Footnote-1654437 +Node: Getlocaltime Function654637 +Node: Data File Management658352 +Node: Filetrans Function658984 +Node: Rewind Function663123 +Node: File Checking664510 +Node: Empty Files665604 +Node: Ignoring Assigns667834 +Node: Getopt Function669387 +Ref: Getopt Function-Footnote-1680691 +Node: Passwd Functions680894 +Ref: Passwd Functions-Footnote-1689869 +Node: Group Functions689957 +Node: Walking Arrays698041 +Node: Sample Programs699610 +Node: Running Examples700275 +Node: Clones701003 +Node: Cut Program702227 +Node: Egrep Program712072 +Ref: Egrep Program-Footnote-1719845 +Node: Id Program719955 +Node: Split Program723571 +Ref: Split Program-Footnote-1727090 +Node: Tee Program727218 +Node: Uniq Program730021 +Node: Wc Program737450 +Ref: Wc Program-Footnote-1741716 +Ref: Wc Program-Footnote-2741916 +Node: Miscellaneous Programs742008 +Node: Dupword Program743196 +Node: Alarm Program745227 +Node: Translate Program749976 +Ref: Translate Program-Footnote-1754363 +Ref: Translate Program-Footnote-2754591 +Node: Labels Program754725 +Ref: Labels Program-Footnote-1758096 +Node: Word Sorting758180 +Node: History Sorting762064 +Node: Extract Program763903 +Ref: Extract Program-Footnote-1771386 +Node: Simple Sed771514 +Node: Igawk Program774576 +Ref: Igawk Program-Footnote-1789733 +Ref: Igawk Program-Footnote-2789934 +Node: Anagram Program790072 +Node: Signature Program793140 +Node: Debugger794240 +Node: Debugging795194 +Node: Debugging Concepts795627 +Node: Debugging Terms797483 +Node: Awk Debugging800080 +Node: Sample Debugging Session800972 +Node: Debugger Invocation801492 +Node: Finding The Bug802821 +Node: List of Debugger Commands809309 +Node: Breakpoint Control810643 +Node: Debugger Execution Control814307 +Node: Viewing And Changing Data817667 +Node: Execution Stack821023 +Node: Debugger Info822490 +Node: Miscellaneous Debugger Commands826471 +Node: Readline Support831916 +Node: Limitations832747 +Node: Dynamic Extensions834999 +Node: Plugin License835895 +Node: Sample Library836509 +Node: Internal File Description837193 +Node: Internal File Ops840906 +Ref: Internal File Ops-Footnote-1845469 +Node: Using Internal File Ops845609 +Node: Language History847985 +Node: V7/SVR3.1849507 +Node: SVR4851828 +Node: POSIX853270 +Node: BTL854278 +Node: POSIX/GNU855012 +Node: Common Extensions860547 +Node: Ranges and Locales861654 +Ref: Ranges and Locales-Footnote-1866258 +Node: Contributors866479 +Node: Installation870775 +Node: Gawk Distribution871669 +Node: Getting872153 +Node: Extracting872979 +Node: Distribution contents874671 +Node: Unix Installation879893 +Node: Quick Installation880510 +Node: Additional Configuration Options882472 +Node: Configuration Philosophy883949 +Node: Non-Unix Installation886291 +Node: PC Installation886749 +Node: PC Binary Installation888048 +Node: PC Compiling889896 +Node: PC Testing892840 +Node: PC Using894016 +Node: Cygwin898201 +Node: MSYS899201 +Node: VMS Installation899715 +Node: VMS Compilation900318 +Ref: VMS Compilation-Footnote-1901325 +Node: VMS Installation Details901383 +Node: VMS Running903018 +Node: VMS Old Gawk904625 +Node: Bugs905099 +Node: Other Versions908951 +Node: Notes914266 +Node: Compatibility Mode914853 +Node: Additions915636 +Node: Accessing The Source916563 +Node: Adding Code917988 +Node: New Ports923996 +Node: Derived Files928131 +Ref: Derived Files-Footnote-1933435 +Ref: Derived Files-Footnote-2933469 +Ref: Derived Files-Footnote-3934069 +Node: Future Extensions934167 +Node: Basic Concepts935654 +Node: Basic High Level936411 +Ref: Basic High Level-Footnote-1940446 +Node: Basic Data Typing940631 +Node: Floating Point Issues945156 +Node: String Conversion Precision946239 +Ref: String Conversion Precision-Footnote-1947939 +Node: Unexpected Results948048 +Node: POSIX Floating Point Problems949874 +Ref: POSIX Floating Point Problems-Footnote-1953579 +Node: Glossary953617 +Node: Copying978593 +Node: GNU Free Documentation License1016150 +Node: Index1041287 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index ceea9a92..4bab87e7 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -712,6 +712,8 @@ particular records in a file and perform operations upon them. @command{gawk}. * New Ports:: Porting @command{gawk} to a new operating system. +* Derived Files:: Why derived files are kept in the + @command{git} repository. * Future Extensions:: New features that may be implemented one day. * Basic High Level:: The high level view. @@ -28503,15 +28505,45 @@ the @option{-l} command-line option (@pxref{Options}). @item -The ability to use GNU-style long-named options that start with @option{--} +The +@option{-b}, +@option{-c}, +@option{-C}, +@option{-d}, +@option{-D}, +@option{-e}, +@option{-E}, +@option{-g}, +@option{-h}, +@option{-i}, +@option{-l}, +@option{-L}, +@option{-M}, +@option{-n}, +@option{-N}, +@option{-o}, +@option{-O}, +@option{-p}, +@option{-P}, +@option{-r}, +@option{-S}, +@option{-t}, +and +@option{-V} +short options. Also, the +ability to use GNU-style long-named options that start with @option{--} and the +@option{--assign}, @option{--bignum}, @option{--characters-as-bytes}, @option{--copyright}, @option{--debug}, @option{--dump-variables}, -@option{--exec}, +@option{--execle}, +@option{--field-separator}, +@option{--file}, @option{--gen-pot}, +@option{--help}, @option{--include}, @option{--lint}, @option{--lint-old}, @@ -28525,13 +28557,13 @@ and the @option{--sandbox}, @option{--source}, @option{--traditional}, +@option{--use-lc-numeric}, and -@option{--use-lc-numeric} -options +@option{--version} +long options (@pxref{Options}). @end itemize - @c new ports @item @@ -30311,6 +30343,8 @@ as well as any considerations you should bear in mind. @command{gawk}. * New Ports:: Porting @command{gawk} to a new operating system. +* Derived Files:: Why derived files are kept in the + @command{git} repository. @end menu @node Accessing The Source @@ -30629,6 +30663,189 @@ operating systems' code that is already there. In the code that you supply and maintain, feel free to use a coding style and brace layout that suits your taste. +@node Derived Files +@appendixsubsec Why Generated Files Are Kept In @command{git} + +@c From emails written March 22, 2012, to the gawk developers list. + +If you look at the @command{gawk} source in the @command{git} +repository, you will notice that it includes files that are automatically +generated by GNU infrastructure tools, such as @file{Makefile.in} from +@command{automake} and even @file{configure} from @command{autoconf}. + +This is different from many Free Software projects that do not store +the derived files, because that keeps the repository less cluttered, +and it is easier to see the substantive changes when comparing versions +and trying to understand what changed between commits. + +However, there are two reasons why the @command{gawk} maintainer +likes to have everything in the repository. + +First, because it is then easy to reproduce any given version completely, +without relying upon the availability of (older, likely obsolete, and +maybe even impossible to find) other tools. + +As an extreme example, if you ever even think about trying to compile, +oh, say, the V7 @command{awk}, you will discover that not only do you +have to bootstrap the V7 @command{yacc} to do so, but you also need the +V7 @command{lex}. And the latter is pretty much impossible to bring up +on a modern GNU/Linux system.@footnote{We tried. It was painful.} + +(Or, let's say @command{gawk} 1.2 required @command{bison} whatever-it-was +in 1989 and that there was no @file{awkgram.c} file in the repository. Is +there a guarantee that we could find that @command{bison} version? Or that +@emph{it} would build?) + +If the repository has all the generated files, then it's easy to just check +them out and build. (Or @emph{easier}, depending upon how far back we go. +@code{:-)}) + +And that brings us to the second (and stronger) reason why all the files +really need to be in @command{git}. It boils down to who do you cater +to---the @command{gawk} developer(s), or the user who just wants to check +out a version and try it out? + +The @command{gawk} maintainer +wants it to be possible for any interested @command{awk} user in the +world to just clone the repository, check out the branch of interest and +build it. Without their having to have the correct version(s) of the +autotools.@footnote{There is one GNU program that is (in our opinion) +severely difficult to bootstrap from the @command{git} repository. For +example, on the author's old (but still working) PowerPC macintosh with +Mac OS X 10.5, it was necessary to bootstrap a ton of software, starting +with @command{git} itself, in order to try to work with the latest code. +It's not pleasant, and especially on older systems, it's a big waste +of time. + +Starting with the latest tarball was no picnic either. The maintainers +had dropped @file{.gz} and @file{.bz2} files and only distribute +@file{.tar.xz} files. It was necessary to bootstrap @command{xz} first!} +That is the point of the @file{bootstrap.sh} file. It touches the +various other files in the right order such that + +@example +# The canonical incantation for building GNU software: +./bootstrap.sh && ./configure && make +@end example + +@noindent +will @emph{just work}. + +This is extremely important for the @code{master} and +@code{gawk-@var{X}.@var{Y}-stable} branches. + +Further, the @command{gawk} maintainer would argue that it's also +important for the @command{gawk} developers. When he tried to check out +the @code{xgawk} branch@footnote{A branch created by one of the other +developers that did not include the generated files.} to build it, he +couldn't. (No @file{ltmain.sh} file, and he had no idea how to create it, +and that was not the only problem.) + +He felt @emph{extremely} frustrated. With respect to that branch, +the maintainer is no different than Jane User who wants to try to build +@code{gawk-4.0-stable} or @code{master} from the repository. + +Thus, the maintainer thinks that it's not just important, but critical, +that for any given branch, the above incantation @emph{just works}. + +@c So - that's my reasoning and philosophy. + +What are some of the consequences and/or actions to take? + +@enumerate 1 +@item +We don't mind that there are differing files in the different branches +as a result of different versions of the autotools. + +@enumerate A +@item +It's the maintainer's job to merge them and he will deal with it. + +@item +He is really good at @samp{git diff x y > /tmp/diff1 ; gvim /tmp/diff1} to +remove the diffs that aren't of interest in order to review code. @code{:-)} +@end enumerate + +@item +It would certainly help if everyone used the same versions of the GNU tools +as he does, which in general are the latest released versions of +@command{automake}, +@command{autoconf}, +@command{bison}, +and +@command{gettext}. + +@ignore +If it would help if I sent out an "I just upgraded to version x.y +of tool Z" kind of message to this list, I can do that. Up until +now it hasn't been a real issue since I'm the only one who's been +dorking with the configuration machinery. +@end ignore + +@enumerate A +@item +Installing from source is quite easy. It's how the maintainer worked for years +under Fedora. +He had @file{/usr/local/bin} at the front of hs @env{PATH} and just did: + +@example +wget http://ftp.gnu.org/gnu/@var{package}/@var{package}-@var{x}.@var{y}.@var{z}.tar.gz +tar -xpzvf @var{package}-@var{x}.@var{y}.@var{z}.tar.gz +cd @var{package}-@var{x}.@var{y}.@var{z} +./configure && make && make check +make install # as root +@end example + +@item +These days the maintainer uses Ubuntu 10.11 which is medium current, but +he is already doing the above for @command{autoconf} and @command{bison}. + +@ignore +(C. Rant: Recent Linux versions with GNOME 3 really suck. What + are all those people thinking? Fedora 15 was such a bust it drove + me to Ubuntu, but Ubuntu 11.04 and 11.10 are totally unusable from + a UI perspective. Bleah.) +@end ignore +@end enumerate + +@ignore +@item +If someone still feels really strongly about all this, then perhaps they +can have two branches, one for their development with just the clean +changes, and one that is buildable (xgawk and xgawk-buildable, maybe). +Or, as I suggested in another mail, make commits in pairs, the first with +the "real" changes and the second with "everything else needed for + building". +@end ignore +@end enumerate + +Most of the above was originally written by the maintainer to other +@command{gawk} developers. It raised the objection from one of +the devlopers ``@dots{} that anybody pulling down the source from +@command{git} is not an end user.'' + +However, this is not true. There are ``power @command{awk} users'' +who can build @command{gawk} (using the magic incantation shown previously) +but who can't program in C. Thus, the major branches should be +kept buildable all the time. + +It was then suggested that there be a @command{cron} job to create +nightly tarballs of ``the source.'' Here, the problem is that there +are source trees, corresponding to the various branches! So, +nightly tar balls aren't the answer, especially as the repository can go +for weeks without significant change being introduced. + +Fortunately, the @command{git} server can meet this need. For any given +branch named @var{branchname}, use: + +@example +wget http://git.savannah.gnu.org/cgit/gawk.git/snapshot/gawk-@var{branchname}.tar.gz +@end example + +@noindent +to retrieve a snapshot of the given branch. + + @node Future Extensions @appendixsec Probable Future Extensions @ignore |