*/
/*
- * "...for the Entwives desired order, and plenty, and peace (by which they
- * meant that things should remain where they had set them)." --Treebeard
+ * '...for the Entwives desired order, and plenty, and peace (by which they
+ * meant that things should remain where they had set them).' --Treebeard
+ *
+ * [p.476 of _The Lord of the Rings_, III/iv: "Treebeard"]
*/
/*
*/
/*
- * "Didst thou think that the eyes of the White Tower were blind? Nay, I
- * have seen more than thou knowest, Gray Fool." --Denethor
+ * 'Didst thou think that the eyes of the White Tower were blind? Nay,
+ * I have seen more than thou knowest, Grey Fool.' --Denethor
+ *
+ * [p.853 of _The Lord of the Rings_, V/vii: "The Pyre of Denethor"]
*/
/*
*/
/*
- * "Far below them they saw the white waters pour into a foaming bowl, and
- * then swirl darkly about a deep oval basin in the rocks, until they found
- * their way out again through a narrow gate, and flowed away, fuming and
- * chattering, into calmer and more level reaches."
+ * Far below them they saw the white waters pour into a foaming bowl, and
+ * then swirl darkly about a deep oval basin in the rocks, until they found
+ * their way out again through a narrow gate, and flowed away, fuming and
+ * chattering, into calmer and more level reaches.
+ *
+ * [p.684 of _The Lord of the Rings_, IV/vi: "The Forbidden Pool"]
*/
/* This file contains functions that do the actual I/O on behalf of ops.
*/
/*
- * "'So that was the job I felt I had to do when I started,' thought Sam."
+ * 'So that was the job I felt I had to do when I started,' thought Sam.
+ *
+ * [p.934 of _The Lord of the Rings_, VI/iii: "Mount Doom"]
*/
/* This file contains some common functions needed to carry out certain
*/
/*
- * "'You have talked long in your sleep, Frodo,' said Gandalf gently, 'and
- * it has not been hard for me to read your mind and memory.'"
+ * 'You have talked long in your sleep, Frodo,' said Gandalf gently, 'and
+ * it has not been hard for me to read your mind and memory.'
+ *
+ * [p.220 of _The Lord of the Rings_, II/i: "Many Meetings"]
*/
/* This file contains utility routines to dump the contents of SV and OP
Up to the threshold of the door there mounted a flight of twenty-seven
broad stairs, hewn by some unknown art of the same black stone. This
-was the only entrance to the tower.
+was the only entrance to the tower; ...
+
+ [p.577 of _The Lord of the Rings_, III/x: "The Voice of Saruman"]
EOW
*/
/*
- And Gandalf said: 'Many folk like to know beforehand what is to
- be set on the table; but those who have laboured to prepare the
- feast like to keep their secret; for wonder makes the words of
- praise louder.'
-*/
+ * And Gandalf said: 'Many folk like to know beforehand what is to
+ * be set on the table; but those who have laboured to prepare the
+ * feast like to keep their secret; for wonder makes the words of
+ * praise louder.'
+ *
+ * [p.970 of _The Lord of the Rings_, VI/v: "The Steward and the King"]
+ */
/* Porting notes:
*/
/*
- And Gandalf said: 'Many folk like to know beforehand what is to
- be set on the table; but those who have laboured to prepare the
- feast like to keep their secret; for wonder makes the words of
- praise louder.'
-*/
+ * And Gandalf said: 'Many folk like to know beforehand what is to
+ * be set on the table; but those who have laboured to prepare the
+ * feast like to keep their secret; for wonder makes the words of
+ * praise louder.'
+ *
+ * [p.970 of _The Lord of the Rings_, VI/v: "The Steward and the King"]
+ */
/* Porting notes:
*/
/*
- * "For the rest, they shall represent the other Free Peoples of the World:
- * Elves, Dwarves, and Men." --Elrond
+ * 'For the rest, they shall represent the other Free Peoples of the World:
+ * Elves, Dwarves, and Men.' --Elrond
+ *
+ * [p.275 of _The Lord of the Rings_, II/iii: "The Ring Goes South"]
*/
/* This file exists to #include "perl.h" _ONCE_ with
/*
* 'Mercy!' cried Gandalf. 'If the giving of information is to be the cure
- * of your inquisitiveness, I shall spend all the rest of my days answering
+ * of your inquisitiveness, I shall spend all the rest of my days in answering
* you. What more do you want to know?'
* 'The names of all the stars, and of all living things, and the whole
* history of Middle-earth and Over-heaven and of the Sundering Seas,'
* laughed Pippin.
+ *
+ * [p.599 of _The Lord of the Rings_, III/xi: "The Palantír"]
*/
/*
*/
/*
- * "I sit beside the fire and think of all that I have seen." --Bilbo
+ * I sit beside the fire and think
+ * of all that I have seen.
+ * --Bilbo
+ *
+ * [p.278 of _The Lord of the Rings_, II/iii: "The Ring Goes South"]
*/
/*
*/
/*
- * A Elbereth Gilthoniel,
- * silivren penna míriel
- * o menel aglar elenath!
- * Na-chaered palan-díriel
- * o galadhremmin ennorath,
- * Fanuilos, le linnathon
- * nef aear, si nef aearon!
+ * A Elbereth Gilthoniel,
+ * silivren penna míriel
+ * o menel aglar elenath!
+ * Na-chaered palan-díriel
+ * o galadhremmin ennorath,
+ * Fanuilos, le linnathon
+ * nef aear, si nef aearon!
+ *
+ * [p.238 of _The Lord of the Rings_, II/i: "Many Meetings"]
*/
/* utility functions for handling locale-specific stuff like what
*/
/*
- * "'The Chamber of Records,' said Gimli. 'I guess that is where we now stand.'"
+ * 'The Chamber of Records,' said Gimli. 'I guess that is where we now stand.'
+ *
+ * [p.321 of _The Lord of the Rings_, II/v: "The Bridge of Khazad-Dûm"]
*/
/* This file contains Perl's own implementation of the malloc library.
*/
/*
- * "Anything that Hobbits had no immediate use for, but were unwilling to
- * throw away, they called a mathom. Their dwellings were apt to become
- * rather crowded with mathoms, and many of the presents that passed from
- * hand to hand were of that sort."
+ * Anything that Hobbits had no immediate use for, but were unwilling to
+ * throw away, they called a mathom. Their dwellings were apt to become
+ * rather crowded with mathoms, and many of the presents that passed from
+ * hand to hand were of that sort.
+ *
+ * [p.5 of _The Lord of the Rings_: "Prologue"]
*/
#ifndef NO_MATHOMS
*/
/*
- * "Sam sat on the ground and put his head in his hands. 'I wish I had never
- * come here, and I don't want to see no more magic,' he said, and fell silent."
+ * Sam sat on the ground and put his head in his hands. 'I wish I had never
+ * come here, and I don't want to see no more magic,' he said, and fell silent.
+ *
+ * [p.363 of _The Lord of the Rings_, II/vii: "The Mirror of Galadriel"]
*/
/*
*/
/*
- * "The Road goes ever on and on, down from the door where it began."
+ * The Road goes ever on and on
+ * Down from the door where it began.
+ *
+ * [Bilbo on p.35 of _The Lord of the Rings_, I/i: "A Long-Expected Party"]
+ * [Frodo on p.73 of _The Lord of the Rings_, I/iii: "Three Is Company"]
*/
/* This file contains the main() function for the perl interpreter.
*/
/*
- * "Which order shall we go in?" said Frodo. "Eldest first, or quickest first?
- * You'll be last either way, Master Peregrin."
+ * 'Which order shall we go in?' said Frodo. 'Eldest first, or quickest first?
+ * You'll be last either way, Master Peregrin.'
+ *
+ * [p.101 of _The Lord of the Rings_, I/iii: "A Conspiracy Unmasked"]
*/
/*
*/
/*
- * "That only makes eleven (plus one mislaid) and not fourteen, unless
- * wizards count differently to other people."
+ * "That only makes eleven (plus one mislaid) and not fourteen,
+ * unless wizards count differently to other people." --Beorn
+ *
+ * [p.115 of _The Hobbit_: "Queer Lodgings"]
*/
/*
*/
/*
- * "You see: Mr. Drogo, he married poor Miss Primula Brandybuck. She was
- * our Mr. Bilbo's first cousin on the mother's side (her mother being the
- * youngest of the Old Took's daughters); and Mr. Drogo was his second
- * cousin. So Mr. Frodo is his first *and* second cousin, once removed
- * either way, as the saying is, if you follow me." --the Gaffer
+ * 'You see: Mr. Drogo, he married poor Miss Primula Brandybuck. She was
+ * our Mr. Bilbo's first cousin on the mother's side (her mother being the
+ * youngest of the Old Took's daughters); and Mr. Drogo was his second
+ * cousin. So Mr. Frodo is his first *and* second cousin, once removed
+ * either way, as the saying is, if you follow me.' --the Gaffer
+ *
+ * [p.23 of _The Lord of the Rings_, I/i: "A Long-Expected Party"]
*/
/* This file contains the functions that create, manipulate and optimize
#include <os2.h>
/*
- * "The Road goes ever on and on, down from the door where it began."
+ * The Road goes ever on and on
+ * Down from the door where it began.
+ *
+ * [Bilbo on p.35 of _The Lord of the Rings_, I/i: "A Long-Expected Party"]
+ * [Frodo on p.73 of _The Lord of the Rings_, I/iii: "Three Is Company"]
*/
#ifdef OEMVS
*
* You may distribute under the terms of either the GNU General Public
* License or the Artistic License, as specified in the README file.
+ */
+
+/*
+ * 'Anyway: there was this Mr. Frodo left an orphan and stranded, as you
+ * might say, among those queer Bucklanders, being brought up anyhow in
+ * Brandy Hall. A regular warren, by all accounts. Old Master Gorbadoc
+ * never had fewer than a couple of hundred relations in the place.
+ * Mr. Bilbo never did a kinder deed than when he brought the lad back
+ * to live among decent folk.' --the Gaffer
*
- * "Anyway: there was this Mr Frodo left an orphan and stranded, as you
- * might say, among those queer Bucklanders, being brought up anyhow in
- * Brandy Hall. A regular warren, by all accounts. Old Master Gorbadoc
- * never had fewer than a couple of hundred relations in the place. Mr
- * Bilbo never did a kinder deed than when he brought the lad back to
- * live among decent folk." --the Gaffer
+ * [p.23 of _The Lord of the Rings_, I/i: "A Long-Expected Party"]
*/
/* XXX DAPM
*/
/*
- * "A ship then new they built for him/of mithril and of elven glass" --Bilbo
+ * A ship then new they built for him
+ * of mithril and of elven-glass
+ * --from Bilbo's song of Eärendil
+ *
+ * [p.236 of _The Lord of the Rings_, II/i: "Many Meetings"]
*/
/* This file contains the top-level functions that are used to create, use
/*
* Hour after hour for nearly three weary days he had jogged up and down,
* over passes, and through long dales, and across many streams.
+ *
+ * [pp.791-792 of _The Lord of the Rings_, V/iii: "The Muster of Rohan"]
*/
/* This file contains the functions needed to implement PerlIO, which
/*
* 'I see,' laughed Strider. 'I look foul and feel fair. Is that it?
- * All that is gold does not glitter, not all those who wander are lost.'
+ * All that is gold does not glitter, not all those who wander are lost.'
*
+ * [p.171 of _The Lord of the Rings_, I/x: "Strider"]
+ */
+
+/*
* This file holds the grammar for the Perl language. If edited, you need
* to run regen_perly.pl, which re-creates the files perly.h, perly.tab
* and perly.act which are derived from this.
If you can do these things, you've started on the long road to Perl porting.
Thanks for wanting to help make Perl better - and happy hacking!
+=head2 Metaphoric Quotations
+
+If you recognized the quote about the Road above, you're in luck.
+
+Most software projects begin each file with a literal description of each
+file's purpose. Perl instead begins each with a literary allusion to that
+file's purpose.
+
+Like chapters in many books, all top-level Perl source files (along with a
+few others here and there) begin with an epigramic inscription that alludes,
+indirectly and metaphorically, to the material you're about to read.
+
+Quotations are taken from writings of J.R.R Tolkien pertaining to his
+Legendarium, almost always from I<The Lord of the Rings>. Chapters and
+page numbers are given using the following editions:
+
+=over 4
+
+=item *
+
+I<The Hobbit>, by J.R.R. Tolkien. The hardcover, 70th-anniversary
+edition of 2007 was used, published in the UK by Harper Collins Publishers
+and in the US by the Houghton Mifflin Company.
+
+=item *
+
+I<The Lord of the Rings>, by J.R.R. Tolkien. The hardcover,
+50th-anniversary edition of 2004 was used, published in the UK by Harper
+Collins Publishers and in the US by the Houghton Mifflin Company.
+
+=item *
+
+I<The Lays of Beleriand>, by J.R.R. Tolkien and published posthumously by his
+son and literary executor, C.J.R. Tolkien, being the 3rd of the 12 volumes
+in Christopher's mammoth I<History of Middle Earth>. Page numbers derive
+from the hardcover edition, first published in 1983 by George Allen &
+Unwin; no page numbers changed for the special 3-volume omnibus edition of
+2002 or the various trade-paper editions, all again now by Harper Collins
+or Houghton Mifflin.
+
+=back
+
+Other JRRT books fair game for quotes would thus include I<The Adventures of
+Tom Bombadil>, I<The Silmarillion>, I<Unfinished Tales>, and I<The Tale of
+the Children of Hurin>, all but the first posthumously assembled by CJRT.
+But I<The Lord of the Rings> itself is perfectly fine and probably best to
+quote from, provided you can find a suitable quote there.
+
+So if you were to supply a new, complete, top-level source file to add to
+Perl, you should conform to this peculiar practice by yourself selecting an
+appropriate quotation from Tolkien, retaining the original spelling and
+punctuation and using the same format the rest of the quotes are in.
+Indirect and oblique is just fine; remember, it's a metaphor, so being meta
+is, after all, what it's for.
+
=head1 AUTHOR
This document was written by Nathan Torkington, and is maintained by
the perl5-porters mailing list.
+
*/
/*
- * "It's a big house this, and very peculiar. Always a bit more to discover,
- * and no knowing what you'll find around a corner. And Elves, sir!" --Samwise
+ * 'It's a big house this, and very peculiar. Always a bit more
+ * to discover, and no knowing what you'll find round a corner.
+ * And Elves, sir!' --Samwise Gamgee
+ *
+ * [p.225 of _The Lord of the Rings_, II/i: "Many Meetings"]
*/
/* This file contains general pp ("push/pop") functions that execute the
*/
/*
- * Now far ahead the Road has gone,
- * And I must follow, if I can,
- * Pursuing it with eager feet,
- * Until it joins some larger way
- * Where many paths and errands meet.
- * And whither then? I cannot say.
+ * Now far ahead the Road has gone,
+ * And I must follow, if I can,
+ * Pursuing it with eager feet,
+ * Until it joins some larger way
+ * Where many paths and errands meet.
+ * And whither then? I cannot say.
+ *
+ * [Bilbo on p.35 of _The Lord of the Rings_, I/i: "A Long-Expected Party"]
*/
/* This file contains control-oriented pp ("push/pop") functions that
* Then he heard Merry change the note, and up went the Horn-cry of Buckland,
* shaking the air.
*
- * Awake! Awake! Fear, Fire, Foes! Awake!
- * Fire, Foes! Awake!
+ * Awake! Awake! Fear, Fire, Foes! Awake!
+ * Fire, Foes! Awake!
+ *
+ * [p.1007 of _The Lord of the Rings_, VI/viii: "The Scouring of the Shire"]
*/
/* This file contains 'hot' pp ("push/pop") functions that
* wooden spoon, a short two-pronged fork and some skewers were stowed; and
* hidden at the bottom of the pack in a flat wooden box a dwindling treasure,
* some salt.
+ *
+ * [p.653 of _The Lord of the Rings_, IV/iv: "Of Herbs and Stewed Rabbit"]
*/
/* This file contains pp ("push/pop") functions that
*/
/*
- * ...they shuffled back towards the rear of the line. 'No, not at the
- * rear!' the slave-driver shouted. 'Three files up. And stay there...
+ * ...they shuffled back towards the rear of the line. 'No, not at the
+ * rear!' the slave-driver shouted. 'Three files up. And stay there...
+ *
+ * [p.931 of _The Lord of the Rings_, VI/ii: "The Land of Shadow"]
*/
/* This file contains pp ("push/pop") functions that
* cloven by a great fissure, out of which the red glare came, now leaping
* up, now dying down into darkness; and all the while far below there was
* a rumour and a trouble as of great engines throbbing and labouring.
+ *
+ * [p.945 of _The Lord of the Rings_, VI/iii: "Mount Doom"]
*/
/* This file contains system pp ("push/pop") functions that
*/
/*
- * "A fair jaw-cracker dwarf-language must be." --Samwise Gamgee
+ * 'A fair jaw-cracker dwarf-language must be.' --Samwise Gamgee
+ *
+ * [p.285 of _The Lord of the Rings_, II/iii: "The Ring Goes South"]
*/
/* This file contains functions for compiling a regular expression. See
*/
/*
- * "One Ring to rule them all, One Ring to find them..."
+ * One Ring to rule them all, One Ring to find them
+ &
+ * [p.v of _The Lord of the Rings_, opening poem]
+ * [p.50 of _The Lord of the Rings_, I/iii: "The Shadow of the Past"]
+ * [p.254 of _The Lord of the Rings_, II/ii: "The Council of Elrond"]
*/
/* This file contains functions for executing a regular expression. See
#include "perl.h"
/*
- * "Away now, Shadowfax! Run, greatheart, run as you have never run before!
- * Now we are come to the lands where you were foaled, and every stone you
- * know. Run now! Hope is in speed!" --Gandalf
+ * 'Away now, Shadowfax! Run, greatheart, run as you have never run before!
+ * Now we are come to the lands where you were foaled, and every stone you
+ * know. Run now! Hope is in speed!' --Gandalf
+ *
+ * [p.600 of _The Lord of the Rings_, III/xi: "The Palantír"]
*/
int
*/
/*
- * "For the fashion of Minas Tirith was such that it was built on seven
- * levels..."
+ * For the fashion of Minas Tirith was such that it was built on seven
+ * levels...
+ *
+ * [p.751 of _The Lord of the Rings_, V/i: "Minas Tirith"]
*/
/* This file contains functions to manipulate several of Perl's stacks;
* You may distribute under the terms of either the GNU General Public
* License or the Artistic License, as specified in the README file.
*
- * "I wonder what the Entish is for 'yes' and 'no'," he thought.
+ */
+
+/*
+ * 'I wonder what the Entish is for "yes" and "no",' he thought.
+ * --Pippin
+ *
+ * [p.480 of _The Lord of the Rings_, III/iv: "Treebeard"]
+ */
+
+/*
*
*
* This file contains the code that creates, manipulates and destroys
*/
/*
- * "...we will have peace, when you and all your works have perished--and
- * the works of your dark master to whom you would deliver us. You are a
- * liar, Saruman, and a corrupter of men's hearts." --Theoden
+ * '...we will have peace, when you and all your works have perished--and
+ * the works of your dark master to whom you would deliver us. You are a
+ * liar, Saruman, and a corrupter of men's hearts.' --Théoden
+ *
+ * [p.580 of _The Lord of the Rings_, III/x: "The Voice of Saruman"]
*/
/* This file contains a few functions for handling data tainting in Perl
*/
/*
- * "It all comes from here, the stench and the peril." --Frodo
+ * 'It all comes from here, the stench and the peril.' --Frodo
+ *
+ * [p.719 of _The Lord of the Rings_, IV/ix: "Shelob's Lair"]
*/
/*
*/
/*
- * "The roots of those mountains must be roots indeed; there must be
- * great secrets buried there which have not been discovered since the
- * beginning." --Gandalf, relating Gollum's story
+ * '"The roots of those mountains must be roots indeed; there must be
+ * great secrets buried there which have not been discovered since the
+ * beginning."' --Gandalf, relating Gollum's history
+ *
+ * [p.54 of _The Lord of the Rings_, I/ii: "The Shadow of the Past"]
*/
/* This file contains the code that implements the functions in Perl's
*/
/*
- * 'What a fix!' said Sam. 'That's the one place in all the lands we've ever
- * heard of that we don't want to see any closer; and that's the one place
- * we're trying to get to! And that's just where we can't get, nohow.'
+ * 'What a fix!' said Sam. 'That's the one place in all the lands we've ever
+ * heard of that we don't want to see any closer; and that's the one place
+ * we're trying to get to! And that's just where we can't get, nohow.'
+ *
+ * [p.603 of _The Lord of the Rings_, IV/I: "The Taming of Sméagol"]
*
* 'Well do I understand your speech,' he answered in the same language;
* 'yet few strangers do so. Why then do you not speak in the Common Tongue,
- * as is the custom in the West, if you wish to be answered?'
+ * as is the custom in the West, if you wish to be answered?'
+ * --Gandalf, addressing Théoden's door wardens
+ *
+ * [p.508 of _The Lord of the Rings_, III/vi: "The King of the Golden Hall"]
*
* ...the travellers perceived that the floor was paved with stones of many
* hues; branching runes and strange devices intertwined beneath their feet.
+ *
+ * [p.512 of _The Lord of the Rings_, III/vi: "The King of the Golden Hall"]
*/
#include "EXTERN.h"
*/
/*
- * "Very useful, no doubt, that was to Saruman; yet it seems that he was
- * not content." --Gandalf
+ * 'Very useful, no doubt, that was to Saruman; yet it seems that he was
+ * not content.' --Gandalf to Pippin
+ *
+ * [p.598 of _The Lord of the Rings_, III/xi: "The Palantír"]
*/
/* This file contains assorted utility routines.
*/
/*
- * Yet small as was their hunted band
- * still fell and fearless was each hand,
- * and strong deeds they wrought yet oft,
- * and loved the woods, whose ways more soft
- * them seemed than thralls of that black throne
- * to live and languish in halls of stone.
+ * Yet small as was their hunted band
+ * still fell and fearless was each hand,
+ * and strong deeds they wrought yet oft,
+ * and loved the woods, whose ways more soft
+ * them seemed than thralls of that black throne
+ * to live and languish in halls of stone.
+ * "The Lay of Leithian", Canto II, lines 135-40
*
- * The Lay of Leithian, 135-40
+ * [p.162 of _The Lays of Beleriand_]
*/
#include <acedef.h>
/*
- * "The Road goes ever on and on, down from the door where it began."
+ * The Road goes ever on and on
+ * Down from the door where it began.
+ *
+ * [Bilbo on p.35 of _The Lord of the Rings_, I/i: "A Long-Expected Party"]
+ * [Frodo on p.73 of _The Lord of the Rings_, I/iii: "Three Is Company"]
*/
#define PERLIO_NOT_STDIO 0
#include "EXTERN.h"
*/
/*
- * "Perilous to us all are the devices of an art deeper than we possess
- * ourselves." --Gandalf
+ * 'Perilous to us all are the devices of an art deeper than we possess
+ * ourselves.' --Gandalf
+ *
+ * [p.597 of _The Lord of the Rings_, III/xi: "The Palantír"]
*/
projects / p5sagit/p5-mst-13.2.git / commitdiff