TIP:            43
Title:          How to be a TIP Editor
Version:        $Revision: 1.4 $
Author:         Donal K. Fellows <fellowsd@cs.man.ac.uk>
State:          Draft
Type:           Informative
Vote:           Pending
Created:        07-Jul-2001
Post-History:   

~ Abstract

This TIP describes some of the rules and guidelines that the TIP
Editor uses when accepting TIPs for the first time.

~ Rules

There are some things that are hard rules, which should be obeyed even
if it means having to postpone acceptance of the TIP or rewrite it
yourself.

 * ''Every TIP ''must'' be relevant to Tcl and/or Tk.''

 > It's probably better to suggest that changes that affect just a
   single extension should be dealt with through the processes for
   feature requests for that extension, but where they are about
   providing some kind common interface across a whole group of
   extensions, it is fair to think of using a TIP as well.  I'd reckon
   that's up to the discretion of the editor, but no TIP should be
   rejected by the editor out of hand, and never without a proper
   written explanation.

 > Of course, ultimately whether a TIP is relevant to Tcl and/or Tk is
   up to the whole Tcl Core Team (as described in [0]) so you should
   try to ensure that their policy on TIP-suitability is what you are
   enforcing.

 * ''Every TIP ''must'' be in the TIP format (see [3] for details.)''

 > This is important because it allows the TIP rendering engine to
   handle all the formatting and indexing automatically for you.  Note
   that it is very picky about the format of the header, and not that
   choosy about the format of the content (though it is not a good
   idea to have a sub-item of a list without a previous main item.)
   Get it wrong, and the TIP archive engine will fail in all sorts of
   "interesting" ways.  Take particular note of the format of the
   ''Created:'' line, as it surprises many people in just how exact it
   must be.

 * ''Every author ''must'' be associated with a real email address.''

 > You should fill this in yourself if it is not already supplied and
   spam-protected addresses are not acceptable, since they tend to
   frustrate the main purpose of TIPs which is to foster collaboration
   on things to improve Tcl and Tk.  Proper email addresses help this
   by always allowing people to contact the author of the TIP to give
   suggestions to improve the TIP or to resolve issues they have with
   it.

 * ''Every TIP ''must'' have an Abstract.''

 > Not everyone has the desire, or the time, to read each TIP.
   Providing an abstract allows people to determine whether the TIP is
   relevant to what they are looking for at the moment.  Searches on
   the TIP archive also always search the abstract.

 > Abstracts should be formed of the section title whose text is
   precisely "Abstract" and then a single normal paragraph of no more
   than around 200 words; if it is longer than that then it is no
   longer a summary or abstract but a genuine major part of the
   document body.  While authors should write their own abstracts, it
   is reasonable for the editor to add one, particularly if the
   author's native language is not English.

 * ''Every TIP ''must'' have a Copyright declaration.''

 > World-wide copyright laws are funny things, and I'm not sure that
   it is safe to assume that the submission of the TIP constitutes
   permission for all the things that might be done with it in the
   future.  Work around this by getting every author to clarify the
   copyright position at time of submission by explicitly saying that
   the document is placed in the public domain.  (The way that TIPs
   are kept under CVS should assuage most concerns relating to
   misrepresentation through inappropriate modifications, and it is a
   definite aim that TIPs should be distributed as widely as possible
   to encourage a wide dissemination of the ideas contained.)

~ Guidelines

 * TIPs should be written in English (unless there are very good
   reasons otherwise) since that is the language most widely
   understood in the Tcl/Tk community.

 * TIP should be written so as to be readable!  This requirement is
   not strict, but it will make it much easier for the TCT to
   evaluate...

 * The Abstract should be written in a third-person voice, and
   ''definitely'' in English.  It isn't so important for the rest of
   the TIP, but the abstract will be seen quite a bit more widely and
   without as much context.  It also fits in with the style of the
   existing abstracts.

 * The section headings and title should be capitalised according to
   the rules for such things in English.  It looks neater that way.

 * Spell check before checking in.  No sense in having glaring errors
   in the initial version!  (I do not enforce the use of either US or
   UK spellings; that is rightfully the domain of the TIP author who
   might be based anywhere in the world.)  Be especially careful with
   the checking of the spellings of the names of file names, C
   identifiers or Tcl commands/variables/etc.

 * C identifiers and Tcl commands/variables/etc. should normally be
   ''emphasized'', as should file names.  This should be moderated by
   good sense though; the aim of such emphasis is to indicate that it
   is a reference to an entity in the code domain as opposed to the
   domain of the English language.

 * TIP numbers should be allocated by the TIP editor in sequence of
   the order they are checked into the CVS archive.  Make sure that
   the filename (''num.tip'') matches up with the ''TIP: num'' header
   or bizarre things may happen.

 * Where someone submits a TIP proposing a new Tk widget, invite them
   to supply an image (or two) of how the widget will look in
   operation.  These images will need to be checked in by hand, and
   will not be editable.  Images should be checked in in both a raster
   form (GIF, JPEG or PNG) and as Encapsulated PostScript (EPS) - make
   sure that you set the binary flag on the file when you do this.
   Where someone produces a diagram with a tool that can produce FIG
   files, it is nice if you can check that into CVS as well so that
   the diagram itself can be maintained if necessary.

 > As a convention, name the images with the TIP number as the first
   part of the name.  This makes it much easier to determine what TIP
   a particular image is associated with (and certainly beats grepping
   the whole set of TIPs!)

 * Once a TIP is checked in, it should normally be published to
   news:comp.lang.tcl, news:comp.lang.tcl.annouce and the tcl-core
   mailing list (though with some TIPs it is obvious that wider
   dissemination is less useful.)  It is a good idea to send a copy to
   the TIP author as well, as this lets them know not only that the
   TIP has been accepted but also what it looks like and that it has
   been distributed to the wider community.  The ''postnews.tcl''
   script that comes with the TIP renderer distribution is designed to
   do all this with a minimum of fuss.  A quick "Thank You" note is
   also courteous.

 * When a TIP has been accepted by the TCT in a TYANNOTT vote, put a
   note into the log to record what the vote was.  It is best to do
   this as part of the log message for when you change the Vote: and
   Status: headers...

 * If a TIP does not state whether it is an alteration to Tcl or Tk in
   either its title or its abstract, it is a good idea to add a
   Keywords: header (or a keyword in an existing such header) which
   includes that information.

 * Don't forget to use both '''bold''' and ''italic'' text when
   formatting strings that represent command syntaxes.  It makes them
   much clearer!

''I need to write something here about the production of PS and PDF
versions of the whole TIP archive, but that side of the code is not
yet finished and released.''

~ Notes

TIPs do not need to be tightly focussed.  Making them so does make
them easier to evaluate, but it might also remove the real rationale
behind the changes.  Instead, it is best that they form a coherent
logical entity, since I believe that it is that which makes for a good
TIP.

The title, section headings and list item headings must be plain text.
This is because there are output formats which are very picky about
what is allowed in those sorts of places (PDF bookmarks have
especially strict restrictions) and plain text has the virtue of being
accepted pretty much everywhere.

~ Copyright

This document is placed in the public domain.
