My favorites | Sign in
Project Home
READ-ONLY: This project has been archived. For more information see this post.
Search
for
HeaderStandard  
eggdrop tcl script headers proposal
Phase-QA
Updated Jul 8, 2011 by rutg...@gmail.com

eggdrop tcl script headers proposal

Problem

There is no standardised file header for eggdrop tcl scripts.

This makes eggdrop tcl scripts difficult to parse and process.

Examples

#Script Name: WorldTime
#Script Site: http://www.hm2k.com/posts/worldtime-tcl
#Description: Sometimes you need to know the time somewhere else in the world. I find it useful to get my eggdrop to return the time of another timezone.
#Version: 2.3.1 *BETA*
#Author: HM2K
#Author Site: http://www.hm2k.com/
#License: BSD

(based on http://codex.wordpress.org/Writing_a_Plugin#Standard_Plugin_Information)

#@name        WorldTime
#@description Sometimes you need to know the time somewhere else in the world. I find it useful to get my eggdrop to return the time of another timezone.
#@author      HM2K <irc@hm2k.org>
#@copyright   2010 HM2K
#@license     BSD
#@version     2.3.1 *BETA*
#@link        http://www.hm2k.com/posts/worldtime-tcl

(based on http://pear.php.net/pepr/pepr-proposal-show.php?id=128)

#*  Script name:  worldtime.tcl
#*  Created on:   4-May-2010
#*  Author:       HM2K
#*  Purpose:      Returns the time for the specified location
#*  History:      etc

(based on http://technet.microsoft.com/en-us/library/ee198697.aspx)

Proposal

The proposed headers are based on a combination of:

Tcl Style Guide: File headers

http://www.tcl.tk/cgi-bin/tct/tip/352.html
Tcl Style Guide: Package structure (SECTION 3.4)
http://wiki.tcl.tk/708
Tcl Style Guide: Procedure headers (SECTION 4.3)
http://wiki.tcl.tk/708
Tcl Style Guide: Changes files (SECTION 9.2)
http://wiki.tcl.tk/708
PHP PEAR Proposal for "Header Comment Blocks"
http://pear.php.net/pepr/pepr-proposal-show.php?id=128
As well as my own concepts which are specifically useful for eggdrop tcl scripts

# worldtime.tcl -- 2.3.2 beta
#
#   Sometimes you need to know the time somewhere else in the world. I find it
#   useful to get my eggdrop to return the time of another timezone.
#
# Copyright (c) 2010 HM2K
#
# Name: WorldTime
# Author: HM2K <irc@hm2k.org>
# License: http://www.opensource.org/licenses/bsd-license.php BSD License
# Link: http://www.hm2k.com/posts/worldtime-tcl
# Labels: world, time
# Updated: 24-Mar-2010
#
###Usage
# > .tz london
# <Bot> HM2K, The time in Westminster, London, UK is Fri Feb 13 23:31:30 2009...
#
###Revisions
# 2.3.2 - expanded GMT offset; added curly braces for expr
# 2.3.1 - fixed memory leaks; fixed unmatched results
# 2.3   - uses Google to retreive geo and timezone information;
#         instead of the system zoneinfo database, which was unreliable.
#         more portable, works on any platform, including Windows.
# 2.2.3 - added timezone offset to output string
# 2.2.2 - added time offset, for a bizarre situation
# 2.2.1 - a few bug fixes, now finds correct zoneinfo dir
# 2.2   - replaced old TIME method with HTP method
# 2.1   - now uses the TIME protocol to get accurate unixtime
# 2.0   - new and improved, using system zoneinfo
# 1.3   - based on a script by Murf, using worldtimeserver.com
###Todo
# 2.4 (feature) Convert to new file header (hm2k)
...

Notes

all lines

All lines require a # (for comment) followed by whitespace (max width: 80chrs)

all dates

The date format that is probably the easiest to read both by humans and machine is the following format:
%d-%b-%Y
for example:
03-May-2010
This format should be used for all dates.

all links

Links are as MediaWiki external link with different label, see:
http://www.mediawiki.org/wiki/Help:Links#External_links
Note: square brakets are not required. Long URLs should not span onto two lines, instead use a URL shortener, see:
http://en.wikipedia.org/wiki/URL_shortening

hashbang

The first line should be the filename and version separated by two dashes.

description

The description should be tabbed in to distinguish it from the rest of the abstract.

copyright

Should appear after the description, formatted as:
Copyright (c) <year|year-range>
<vendor>
for example:
Copyright (c) 1994-1997 Sun Microsystems, Inc.

tags

Based on PEAR's tags, this allows you to add specific details under an appropreate tag name. Multiple values should be comma separated, alternatively a new line with a tag of the same kind may be added. For example, there may be more than one author tag line to represent each author. Tag names should be capitalised and end with a prompt.

name tag

The name of the script

author tag

This will be the author followed by an optional angle bracketed email address

license tag (optional)

This should be a link to a license agreement

link tag (optional)

This should be a link of the page for the script or the full description, but not the authors homepage

labels tag

A set of no more than 10 comma separated labels that will help categorise the script.

updated tag

This tag allows you to set the date of when it was last updated.

sections

Similar to tags, this allows you to add sections for details that will not fit on one line. To signal the start of a section you will need to add three hashes followed by the name of the section, starting with a capital letter.

usage section

Here you should display a example of usage and/or arguments

revision section

The revision history is similar to the change log format, formatted as:
<version|date> <-|(type)> <comment> (author)
for example:
5/19/94 (bug fix) Canvases didn't generate proper Postscript for
stippled text. (RJ)
Note: The "author" part is only required if there are multiple authors

todo section

A section for you to add tasks such as bug fixes or features to add, format:
<version|date> <-|(type)> <comment> (user)
For example:
2.4 (feature) Convert to new file header (hm2k)
The version or date is used for deadlines. The user is the requesting or reporting user.
Powered by Google Project Hosting