|
HeaderStandard
eggdrop tcl script headers proposal
Phase-QA eggdrop tcl script headers proposalProblemThere 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) ProposalThe proposed headers are based on a combination of: Tcl Style Guide: File headers http://www.tcl.tk/cgi-bin/tct/tip/352.htmlTcl Style Guide: Package structure (SECTION 3.4) http://wiki.tcl.tk/708Tcl Style Guide: Procedure headers (SECTION 4.3) http://wiki.tcl.tk/708Tcl Style Guide: Changes files (SECTION 9.2) http://wiki.tcl.tk/708PHP PEAR Proposal for "Header Comment Blocks" http://pear.php.net/pepr/pepr-proposal-show.php?id=128As 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) ... Notesall linesAll lines require a # (for comment) followed by whitespace (max width: 80chrs) all datesThe date format that is probably the easiest to read both by humans and machine is the following format:%d-%b-%Yfor example:03-May-2010This format should be used for all dates. all linksLinks are as MediaWiki external link with different label, see:http://www.mediawiki.org/wiki/Help:Links#External_linksNote: 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 hashbangThe first line should be the filename and version separated by two dashes. descriptionThe description should be tabbed in to distinguish it from the rest of the abstract. copyrightShould appear after the description, formatted as:Copyright (c) <year|year-range>for example: tagsBased 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 tagThe name of the script author tagThis 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 tagA set of no more than 10 comma separated labels that will help categorise the script. updated tagThis tag allows you to set the date of when it was last updated. sectionsSimilar 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 sectionHere you should display a example of usage and/or arguments revision sectionThe 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 forNote: The "author" part is only required if there are multiple authorsstippled text. (RJ) todo sectionA 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. |