Author: dylan
Date: 2004-12-16 00:39:02 -0500 (Thu, 16 Dec 2004)
New Revision: 415
Added:
trunk/docs/spec/
Modified:
trunk/docs/guidelines.txt
trunk/docs/manual/Makefile
trunk/docs/manual/chap/events/connection.texi
trunk/docs/manual/haver.texi
trunk/docs/perl-boilerplate
Log:
Updated boilerplate slightly, added a lot to the guidelines
file, changed several of them...
spec: Future home of Haver::Spec,
which will be the bare-bones RFC-like description of haver.
docs/manual/ will be a nicer version of that, written in a more how-to
style.
Also, for the manual, "make xml" causes makeinfo to generate XML, in case
someone
wants that.
I added some stupid comment to docs/manual/chap/events/connection.texi,
it's not really important.
Modified: trunk/docs/guidelines.txt
===================================================================
--- trunk/docs/guidelines.txt 2004-12-15 21:35:24 UTC (rev 414)
+++ trunk/docs/guidelines.txt 2004-12-16 05:39:02 UTC (rev 415)
@@ -2,16 +2,17 @@
* use strict;
* use warnings;
* use base qw( Haver::Base ); except when that doesn't make sense.
+ * Write readable, nice code.
+ * Don't optimize until you reach 1.0.
* Text
- * Use tabs to indent code.
- * Use spaces to align code.
- * Tabs should look like 4 spaces, e.g. set ts=4 sw=4 in vim.
- * Use K&R brace style. Openning braces should be on the same line as the
statement,
+ * Use four spaces to indent code.
+ * "vim: set ts=4 sw=4 expandtab si ai sta:" is ideal.
+ I'm sure Emacs has the equivalent.
+ * Use K&R brace style. Opening braces should be on the same line as the
statement,
and only a newline should follow (eg: if (3) {, while (3) {, sub insane
{, etc)
* Pad operators except commas with one or more spaces on each side
* Pad commas with one or more spaces on the right hand side (Obvious)
- * Use tags vim/emacs knows about like FIXME, TODO, and XXX.
* Variables
* Use clear names
@@ -19,15 +20,18 @@
* Lexical variables should be in all lowercase, with _ seperating words.
($like_this, not $LikeThis, please)
* Global variables or lexical variables in the scope of an entire file
should be
- have the first letter of each 'word' upper cased ($Like_This)
+ have the first letter of each 'word' upper cased ($Like_This).
* Functions
* Functions and methods should mostly use named arguments,
- except where that seems silly. Usually named arguments are lower-case
- case and start with a letter. In places where you
- want it to look like Tk, you may have them start with -...
+ except where that seems silly. Named arguments should
+ be all lower case and start with a dash.
+ Note that as of 2004-12-15 very little if any haver
+ code follows this, as previously it was not a guideline.
* Commenting
+ * Use tags vim/emacs knows about like FIXME, TODO, and XXX,
+ when appropriate.
* Comment where and when it makes sense.
If you think that in six months you might not
remember how something works, comment it.
@@ -41,3 +45,20 @@
* Please, please, try to document perl modules with POD.
At least, when a module is in a "usable" state,
it should have documentation.
+ * Documents should contain NAME, SYNOPSIS, DESCRIPTION, SEE ALSO, AUTHOR,
+ and COPYRIGHT AND LICENSE sections.
+ * Additional, optional, sections include EXPORTS (after DESCRIPTION),
INHERITANCE (after NAME),
+ FUNCTIONS and/or METHODS after DESCRIPTION, and perhaps ABSTRACT before
DESCRIPTION,
+ if DESCRIPTION is somewhat long or complicated.
+ * Each method or function should be documented in the FUNCTIONS or METHODS
section,
+ and the POD for each method or function should placed directly above
where it is defined.
+ * the INHERITENCE section might look something like this (taken from
Mail::Box)
+ Mail::Box
+ is a Mail::Reporter
+
+ Mail::Box is extended by
+ Mail::Box::Dir
+ Mail::Box::File
+ Mail::Box::Net
+ * If longer cookbook-style examples need to be given, use a
"Module/Name/Cookbook.pod" file
+ for them. Try to keep SYNOPSIS under 20 lines. This is not a hard limit.
Modified: trunk/docs/manual/Makefile
===================================================================
--- trunk/docs/manual/Makefile 2004-12-15 21:35:24 UTC (rev 414)
+++ trunk/docs/manual/Makefile 2004-12-16 05:39:02 UTC (rev 415)
@@ -8,6 +8,7 @@
pdf: haver.pdf
html: haver/index.html
txt: haver.txt
+xml: haver.xml
haver/index.html: haver.texi $(texi)
makeinfo --html $<
@@ -19,6 +20,9 @@
haver.info: haver.texi $(texi)
makeinfo $<
+haver.xml: haver.texi $(texi)
+ makeinfo --xml $< > $@
+
haver.pdf: haver.texi $(texi)
texi2pdf $<
rm haver.tp haver.ky haver.fns haver.vr \
Modified: trunk/docs/manual/chap/events/connection.texi
===================================================================
--- trunk/docs/manual/chap/events/connection.texi 2004-12-15 21:35:24 UTC
(rev 414)
+++ trunk/docs/manual/chap/events/connection.texi 2004-12-16 05:39:02 UTC
(rev 415)
@@ -1,3 +1,5 @@
[EMAIL PROTECTED] !podname Haver::Spec::Event::Connection
+
@node Connection Events
@section Connection Events
Modified: trunk/docs/manual/haver.texi
===================================================================
--- trunk/docs/manual/haver.texi 2004-12-15 21:35:24 UTC (rev 414)
+++ trunk/docs/manual/haver.texi 2004-12-16 05:39:02 UTC (rev 415)
@@ -6,6 +6,12 @@
@set version 4
[EMAIL PROTECTED]
[EMAIL PROTECTED] The Divine Secrets of Haver
[EMAIL PROTECTED] A Journey into Madness
[EMAIL PROTECTED] Version @value{version}
[EMAIL PROTECTED] Dylan William Hardison
+
@copying
This document describes the Haver protocol, version @value{version}.
@@ -17,12 +23,6 @@
@end quotation
@end copying
[EMAIL PROTECTED]
[EMAIL PROTECTED] The Divine Secrets of Haver
[EMAIL PROTECTED] A Journey into Madness
[EMAIL PROTECTED] Version @value{version}
[EMAIL PROTECTED] Dylan William Hardison
-
@c The following two commands
@c start the copyright page.
Modified: trunk/docs/perl-boilerplate
===================================================================
--- trunk/docs/perl-boilerplate 2004-12-15 21:35:24 UTC (rev 414)
+++ trunk/docs/perl-boilerplate 2004-12-16 05:39:02 UTC (rev 415)
@@ -1,5 +1,5 @@
-# vim: set ft=perl ts=4 sw=4:
-# module - use
+# vim: set ft=perl ts=4 sw=4 expandtab si ai sta:
+# Module - use
#
# Copyright (C) 2004 Bryan Donlan, Dylan William Hardison.
#
@@ -16,3 +16,11 @@
# You should have received a copy of the GNU General Public License
# along with this module; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+package Module;
+
+our $VERSION = 0.01;
+use base 'Haver::Base';
+
+
+1;
+
