NAME
Cheat::Meta::Spec - How to use the Cheat:: namespace
VERSION
This document is Cheat::Meta::Spec version 0.0.5
SYNOPSIS
# lib/Cheat/Sheet/Some.perl
Some::Module # Short description
qw( various exportable symbols if any );
routine( $placeholder, @arguments );
$context = function( @arguments);
$object->method();
Some:OtherModule...
# lib/Cheat/Sheet/Some.pod
=head2 Some::Module
Some::Module # Short description
qw( various exportable symbols if any );
routine( $placeholder, @arguments );
$context = function( @arguments);
$object->method();
=head2 Some::OtherModule ...DESCRIPTION
But I caution you:
I was quite close to revealing rare and powerful cheat codes.
--The Devil (Dinosaur Comics)
This is a collection of "cheat sheets": highly compressed, abbreviated documentation for various modules. Each module within the bundle covers a top-level namespace or a set of otherwise closely-related modules.
If you want to read cheat sheets, please check out Cheat::Meta. You can just install Bundle::Cheat::Sheet.
If you want to develop cheat sheets themselves, the current file is for you.
RATIONALE
I created the Cheat:: top-level namespace and scheme after much hesitation and some encouragement. I discussed several alternatives; none satisfied.
Namespace
Cheat sheets aren't executable code, not in the aggregate. Each line is formatted as valid Perl; that's its merit. But executing a whole cheat is madness. This presents a problem when searching for a top-level namespace.
Modules under Doc:: seem to be tools for manipulating documentation. Documentation:: is no better. Cheat sheets are not manuals or templates.
Other documentation on the CPAN is usually specific to another module or tightly-related group of modules. For example, Template::Manual documents Template and other modules within Template Toolkit. It wouldn't be nice to drop, say, Template::Cheat::Sheet into that namespace. Also, not every cheat sheet falls neatly under a single namespace. Cheat::Sheet::Util covers Scalar::Util, List::Util, Hash::Util.... Where should it go?
perlcheat.pod is in core. OpenResty::CheatSheet exists and is a fair example of the cheat sheet style; but again, I don't want to pollute other namespaces.
There doesn't seem to be a workable alternative to a new namespace.
File Formats
To be useful, cheat sheets must be available as plain text files that can be opened in a user's code editor. These are not tutorials or even working demos. User is expected to copy one or more lines directly from the cheat sheet, paste into his ongoing project, and edit to suit.
Syntax highlighting or coloring is important to some users. Colors reveal the intent of various tokens. In a cheat sheet, it's important to be able to see immediately which tokens are literal and which placeholders. It could be argued that an entirely different coloring scheme (than is normal) would be even better; but I don't see that's going to happen.
When a Perl module is loaded, all use() statements are executed (at "compile-time"), as if they were enclosed in a BEGIN block. Since a cheat sheet naturally includes many such statements, formatting one as an ordinary Perl module causes each cheated module to load. This might be correct from some very formal viewpoint but is rude.
So, presenting the cheat sheet as code in a .pm file is out. Presentation as POD means that syntax coloring is lost. Also, verbatim code tends to copy out with too much, often incorrect, indentation. However, CPAN demands, and some users expect, code in POD format. So, a .pod file -- POD only file -- is given.
Cheat sheets aren't tests or scripts. The only rational extension I can see for naming the raw code-only files is .perl.
When authoring a cheat sheet, I decided to write a base or source file. A little utility script, util/cheat-build.pl, uses Template (Template::Toolkit, TT) and a pair of .tt2 template files to generate the usable cheats in .perl and .pod forms. I settled on the unusual .agi extension for these source files. They have nothing whatever to do with AGI.
DEVELOPERS
If you want to write a cheat sheet, great! Obviously, you might start by looking through the files of this distribution. I'm a great believer in consistency.
Each cheat sheet should be released in both POD and raw Perl forms. You're welcome to use existing files as models. Please name a cheat for Foo as Cheat::Sheet::Foo. Expect to install (for some lib/):
- lib/Cheat/Sheet/Foo.perl
-
Raw Perl code.
- lib/Cheat/Sheet/Foo.pod
-
Same content as POD verbatim paragraphs.
Please seriously consider contacting the maintainer of Bundle::Cheat::Sheet! I will be happy to assist you and I will include your properly-formatted cheat sheets in the Bundle. You can still package and upload them yourself and get all the credit. I would like to avoid naming conflicts and duplication of effort; please contact me before starting work.
Naturally, suggestions for cheat sheets, new or old, are always welcome.
THANKS
To about 8500 authors who have uploaded about 85,000 modules to the CPAN.
AUTHOR
Xiong Changnian <xiong@cpan.org>
LICENSE
Copyright (C) 2010 Xiong Changnian <xiong@cpan.org>
This library and its contents are released under Artistic License 2.0: