=head1 NAME

pugs::hack - How to hack on Pugs

=head1 SYNOPSYS

	# XXXX: quickstart for checkout, compile, run pugs ...

=head1 DESCRIPTION

XXXX: Overview of this document

=head2 Source tree map

The Pugs source tree includes several major sections:

	.
	|-- LICENSE      Licenses that apply to the Pugs distribution
	|-- debian       Packaging rules for dpkg-based systems
	|-- docs         Documentation relating to Pugs/Perl6/Haskell
	|-- examples     Examples of Perl6 usage; many work in Pugs today
	|-- ext          Perl6 modules that work and get built with pugs
	|-- inc          Perl5 modules needed to build/test/install pugs
	|-- lib          XXXX: overall concept?
	|-- modules      Perl6 modules not working today; -> FreePAN
	|-- script       pugscc, the Pugs Compiler Compiler
	|-- src          Haskell source for pugs itself
	|-- t            Pugs/Perl6 test library
	|-- t_disabled   Disabled tests
	`-- util         Utilities for hacking and testing Pugs

Expanding this one level deeper:

	.
	|-- LICENSE            Licenses that apply to the Pugs distribution
	|
	|-- debian             Packaging rules for dpkg-based systems
	|
	|-- docs               Documentation relating to Pugs/Perl6/Haskell
	|   |-- AES                Drafts of Perl6::Bible chapters
	|   |-- advocacy           empty (XXXX: to be deleted?)
	|   |-- class              Object system sketches (XXXX: out of date?)
	|   |-- other              Misc design and hacking notes
	|   |-- quickref           Perl6 quick reference pages
	|   |-- src                Junction implementation sketch (XXXX: ood?)
	|   |-- talks              Slides for Pugs and Perl6 talks
	|   |-- zh-cn              Simplified Chinese doc translations
	|   `-- zh-tw              Traditional Chinese doc translations
	|
	|-- examples           Examples of Perl6 usage; many work in Pugs today
	|   |-- advocacy           Pugs/Perl6-advocacy MOTD generator
	|   |-- algorithms         Basic algorithms
	|   |-- cgi                CGI scripts and applications
	|   |-- cookbook           Perl6 idiomatic Perl Cookbook
	|   |-- functional         Functional programming concepts
	|   |-- games              Playable games
	|   |-- golf               Minimal (key)stroke puzzle solutions
	|   |-- hashes             Use of Perl6 hashes
	|   |-- japh               JAPHs using various idioms
	|   |-- junctions          Fun with junctions
	|   |-- naive_bayesian     Naive Bayesian Text Classification
	|   |-- nested_loops       Many ways to do runtime nested loops
	|   |-- network            Networking clients, servers, bots, etc.
	|   |-- obfu               Obfuscated code and obfuscation techniques
	|   |-- output             Expected example outputs, for testing
	|   |-- p6explain          XXXX: what is this?
	|   |-- perl5              Programs that use Perl5 modules
	|   |-- poetry             Perl6 poetry
	|   |-- ppt                Perl6 Power Tools, ports of *nix userland
	|   |-- qotw               Perl6 solutions to plover's Quiz Of The Week
	|   |-- slurpy-list-parms  Use of Perl6 slurpy lists (XXXX: -> t/?)
	|   `-- tutorial_gen       Tutorial generator (XXXX: huh?)
	|
	|-- ext                Perl6 modules that work and get built with pugs
	|   |-- Algorithm-TokenBucket  Token bucket rate limiting
	|   |-- Benchmark          Benchmark runtime of Perl6 code
	|   |-- CGI                CGI author's helper module
	|   |-- Config-Tiny        Pre-Pugs-OO .ini file reader
	|   |-- Date               Date and time modules
	|   |-- File-Find          Traverse a directory tree
	|   |-- File-Spec          Portable File handling
	|   |-- HTML-Entities      Encode/decode HTML entities
	|   |-- Kwid-Event-Parser  Event-based API (like XML SAX) for Kwid
	|   |-- Locale-KeyedText   Refer to UI strings by key
	|   |-- Net-IRC            IRC protocol implementation
	|   |-- POE                Experimental port of Perl5 POE
	|   |-- Perl-MetaModel     Sketch of Perl6 Object Meta Model
	|   |-- Pod-Event-Parser   Event-based API (like XML SAX) for POD
	|   |-- Set                Set calculus operators
	|   |-- Test               Testing support library
	|   |-- Test-Builder       Backend for building test libraries
	|   |-- Text-Glob          Translate glob to regex
	|   |-- Tree               Basic n-ary tree data structure
	|   |-- URI                Escape/unescape URI strings
	|   |-- fp                 Functional programming operators
	|   |-- lib                Pragma to add paths to @*INC
	|   `-- libwww-perl        Port of Perl5 libwww-perl modules
	|
	|-- inc                Perl5 modules needed to build/test/install pugs
	|   |-- Module             Module::Install
	|   `-- Test               Test::Harness
	|
	|-- lib                XXXX: overall concept?
	|   |-- Inline             Inline::Pugs
	|   |-- Perl6              Perl6::MakeMaker, Perl6::Pugs
	|   `-- pugs               Docs for Pugs itself (XXXX: -> docs/?)
	|
	|-- modules            Perl6 modules not working today; -> FreePAN
	|   |-- Class-Events       XXXX: why is this still here?
	|   `-- Sample-Module      XXXX: why is this still here?
	|
	|-- script             pugscc, the Pugs Compiler Compiler
	|
	|-- src                Haskell source for pugs itself
	|   |-- Data               Syck-based YAML parser
	|   |-- IMC                Parrot IMC backend
	|   |-- Pugs               Core Pugs engine
	|   |-- RRegex             PCRE-based regular expressions support
	|   |-- pcre               Import of PCRE source
	|   |-- perl5              Perl5 bidirectional call support
	|   |-- perl6              The Perl6 prelude (definition of builtins)
	|   |-- pge                Import of PGE (Parrot Grammer Engine) source
	|   `-- syck               Import of Syck source
	|
	|-- t                  Pugs/Perl6 test library
	|   |-- Synopsis           Pointers to online AES docs and tests
	|   |-- Test-Less          Test index for test-less utility
	|   |-- builtins           Builtin function tests
	|   |-- data_types         Basic data type tests
	|   |-- examples           Make examples/ tree act as tests
	|   |-- general            Miscellaneous tests
	|   |-- junction           Junction tests
	|   |-- macros             Macro tests
	|   |-- magicals           Magical variable tests
	|   |-- oo                 Object Oriented programming tests
	|   |-- operators          Operator tests
	|   |-- pugsbugs           Tests for functionality known to be broken
	|   |-- pugsrun            Tests for pugs (as opposed to Perl6)
	|   |-- rules              Perl6 rule and Perl5 regex tests
	|   |-- statements         Statement-level construct tests
	|   |-- subroutines        Block/Code/Sub/etc. tests
	|   |-- syntax             Basic syntax tests
	|   |-- unspecced          Tests for Pugs extensions to Perl6
	|   `-- var                Variable declaration tests
	|
	|-- t_disabled         Disabled tests
	|   |-- Dialects           Perl 6 non-standard dialects
	|   `-- rules              Port of tests from CPAN module Perl6::Rules
	|
	`-- util               Utilities for hacking and testing Pugs
	    `-- livecd             Create a minimalistic Pugs Live CD
