-%{
-#include "EXTERN.h"
-#define PERL_IN_PERLY_C
-#include "perl.h"
-#ifdef EBCDIC
-#undef YYDEBUG
-#endif
-#define dep() deprecate("\"do\" to call subroutines")
-
-/* stuff included here to make perly_c.diff apply better */
-
-#define yydebug PL_yydebug
-#define yynerrs PL_yynerrs
-#define yyerrflag PL_yyerrflag
-#define yychar PL_yychar
-#define yyval PL_yyval
-#define yylval PL_yylval
+/*
+ * 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.
+ *
+ * Note that these derived files are included and compiled twice; once
+ * from perly.c, and once from madly.c. The second time, a number of MAD
+ * macros are defined, which compile in extra code that allows the parse
+ * tree to be accurately dumped. In particular:
+ *
+ * MAD defined if compiling madly.c
+ * DO_MAD(A) expands to A under madly.c, to null otherwise
+ * IF_MAD(a,b) expands to A under madly.c, to B otherwise
+ * TOKEN_GETMAD() expands to token_getmad() under madly.c, to null otherwise
+ * TOKEN_FREE() similarly
+ * OP_GETMAD() similarly
+ * IVAL(i) expands to (i)->tk_lval.ival or (i)
+ * PVAL(p) expands to (p)->tk_lval.pval or (p)
+ *
+ * The main job of of this grammar is to call the various newFOO()
+ * functions in op.c to build a syntax tree of OP structs.
+ * It relies on the lexer in toke.c to do the tokenizing.
+ *
+ * Note: due to the way that the cleanup code works WRT to freeing ops on
+ * the parse stack, it is dangerous to assign to the $n variables within
+ * an action.
+ */