TIP #13: WEB SERVICE FOR DRAFTING AND ARCHIVING TIPS 
======================================================
 Version:      $Revision: 1.26 $
 Author:       Don Porter <dgp_at_users.sourceforge.net>
               Donal K. Fellows <fellowsd_at_cs.man.ac.uk>
 State:        Accepted
 Type:         Process
 Vote:         Done
 Created:      Tuesday, 21 November 2000
 URL:          https://tip.tcl-lang.org13.html
 Post-History: 

-------------------------------------------------------------------------

 ABSTRACT 
==========

 This document proposes the TCT provide a service on the World Wide Web 
 for drafting and archiving TIPs and for providing TIPs in a variety of 
 formats. A reference implementation is provided, and its server 
 requirements are outlined. 

 BACKGROUND 
============

 It has been proposed (see [TIP #2]) that the TCT manage its projects 
 and procedures through a set of public documents known as Tcl 
 Improvement Proposals, or TIPs. A format for TIPs has been approved 
 (see [TIP #3]), and although final approval of [TIP #2] is still 
 pending, several TIPs have been submitted, discussed, and revised, and 
 a few have been approved, so acceptance of TIPs in some form seems 
 likely. 

 A prototype system has been provided by Donal Fellows 
 <fellowsd@cs.man.ac.uk> 
 [<URL:http://www.cs.man.ac.uk/fellowsd-bin/TIP/>] that delivers TIPs to 
 visitors in a variety of formats. However, that system lacks archiving 
 of each revision of each TIP, and offers no interface (through the web 
 or otherwise) for making revisions to TIPs.  

 The TIP format was inspired by the format used by the Tcl'ers Wiki 
 [<URL:http://www.purl.org/thecliff/tcl/wiki/>]. The true power of the 
 Tcl'ers Wiki, though, is not in the particular format it uses, but in 
 the fact that it empowers the whole Tcl community to contribute to a 
 common set of resources. The Tcl'ers Wiki shows that valuable resources 
 can arise out of the unrestricted efforts of volunteers from the 
 community. 

 PROBLEMS WITH CURRENT TIP INFRASTRUCTURE. 
===========================================

 The Fellows web interface to the TIP Document Collection 
 [<URL:http://www.cs.man.ac.uk/fellowsd-bin/TIP/>] offers valuable 
 browsing access to TIPs in a variety of formats. It accomplishes the 
 important goal of making TIPs public. However, it suffers from two 
 significant shortcomings: 

     * Revisions are only possible through the TIP Editor: 

       Currently the only way to revise a TIP is to e-mail a new 
       revision to the TIP Editor and wait for it to replace the old 
       revision. As more TIPs are submitted, and as each TIP is more 
       frequently revised, this bottleneck will not be tolerable. 

       Discussion about TIPs currently takes place in Usenet newsgroups 
       and on mailing lists, but because there is no easy access to 
       revising the TIPs themselves, the new information and viewpoints 
       arising in these discussions are not being folded back into the 
       TIPs. This means the TIPs are failing in their intended role to 
       present a full history of an issue to later readers. It also 
       means newcomers to a TIP cannot receive a full briefing in one 
       place, but must chase down discussions in mailing list and Usenet 
       archives. Few people do that, but instead repeat points already 
       made. The discussions about [TIP #6] reflect this problem. 

     * An archive of each revision of each TIP is not maintained: 

       Although [TIP #2] refers to TIPs as being stored in a revision 
       control system, probably a CVS repository, the Fellows TIP 
       collection is not maintained in such a system. Since a TIP is an 
       archive of a public discussion of an issue, it is important to be 
       able to access the history of changes to each TIP. 

       The ability to retrieve and restore earlier revisions of a TIP 
       will be especially important if public revision is permitted, so 
       that any TIP contents that are incorrectly removed, whether by 
       accident or malice, can be restored. 

 PROPOSAL 
==========

 An improved system for archiving and revising TIPs is proposed: 

    1. TIPs will be archived in a CVS repository. 

    2. Anyone with the power to call a TYANNOTT vote will have commit 
       access to this repository through either :pserver: or ssh access. 
       With this access, they will be able to revise any part (header or 
       body) of any TIP (whether in /State: Draft/ or not). Everyone 
       having this access will be trusted to modify TIPs only in 
       conformance with the TIP format and the TCT procedures. 

    3. An enhanced version of the Fellows TIP rendering engine will 
       display an [Edit] link at the bottom of each TIP eligible for 
       web-editing when that TIP is rendered in HTML. 

    4. For any TIP in state Draft, and for which a vote is still 
       pending, the [Edit] link will lead to an HTML form for submitting 
       a revised TIP. For other TIPs, no [Edit] link will appear, and an 
       attempt to directly access web-editing of such a TIP will lead to 
       a message stating that the TIP may not be edited through the web 
       interface. 

    5. The HTML editing form will display the TIP header, but will not 
       make it available for editing. The HTML form will require that an 
       e-mail address be entered, and will allow a name to be entered as 
       well. A <TEXTAREA> will be initialized to hold the current TIP 
       abstract. A second <TEXTAREA> will be initialized to hold the 
       current TIP body. Users of the form will revise the abstract and 
       the body, then submit the form. 

    6. The TIP rendering engine will receive the revisions, and will use 
       CVS client commands to merge the revisions with other revisions 
       and commit the revised TIP to the TIP CVS repository. If a 
       conflict occurs during a merge, the TIP body including the 
       conflicts will be returned to the user in another HTML form to 
       resolve the conflict. 

       Note that the CVS commit function of the TIP rendering engine 
       implies that the CGI process in which the TIP rendering engine 
       runs must have a user ID with commit access to the TIP CVS 
       repository. 

    7. In the revised TIP checked in to CVS the submitter of the 
       revision will be added as an Author in the header of that TIP. 

 REFERENCE IMPLEMENTATION 
==========================

 The modifications to the Fellows TIP rendering engine that add the 
 capabilities proposed above are now merged in. The TIP rendering engine 
 is maintained and publically available 
 [<URL:http://sourceforge.net/projects/tiprender/>]. To enable the 
 web-editing features, set the Tcl variable FEATURE(EDIT) to 1 in the 
 file config.tcl. A working version of the proposed web service is 
 available at <URL:http://purl.org/tcl/tip/> 

 For what it's worth, this TIP was created primarily within a web 
 browser, making revisions through the web interface provided by the 
 reference implementation. 

 One remaining shortcoming of the reference implementation is that it 
 provides no mechanism for uploading images to the TIP repository. 
 Images still need to be submitted through the TIP Editor, or someone 
 else with commit access to the TIP CVS repository. 

 SERVER REQUIREMENTS 
=====================

 The reference implementation imposes the following requirements on a 
 server: 

    1. The server provides an HTTP server that serves the public 
       Internet, and supports the CGI interface. 

    2. CVS client software must be installed on the server. 

    3. The CVS repository containing TIPs must be on the server itself. 
       This is due to a CVS limitation that /loginfo/ scripts run on the 
       machine housing the CVS repository, and the reference 
       implementation uses a /loginfo/ script to keep the TIPs presented 
       through the web up to date with the commits to the repository. 

    4. The CVS repository must offer commit access over the Internet 
       using either :pserver: or ssh to everyone with authority to call 
       a TYANNOTT vote. 

    5. The user under which the HTTP server runs its CGI processes must 
       have commit access to the TIP CVS repository. This may have 
       security implications. 

 FUTURE IMPROVEMENTS 
=====================

 Once the TIPs are housed in a CVS repository, other services should be 
 easier to implement. Another browsing interface could be provided using 
 cvsweb [<URL:http://stud.fh-heilbronn.de/~zeller/cgi/cvsweb.cgi/>] to 
 allow anyone in the community to browse TIP history. Another /loginfo/ 
 script could provide e-mail notices when a TIP is revised to users who 
 registered their interest in that TIP. 

 ACKNOWLEDGMENTS 
=================

 Thanks to Donal Fellows for the original TIP rendering engine and his 
 assistance merging in the changes. Thanks to Brent Welch for providing 
 the server and his assistance getting it configured for use. Thanks to 
 Mark Harrison for his assistance with managing browser caching issues. 

-------------------------------------------------------------------------

 COMMENTS FROM THE TCT 
=======================

       It might be a good idea to make the Abstract into a seperate 
       <textarea> and treat that specially; I've been applying the rule 
       that a TIP's abstract should be a single paragraph (it is 
       implicit in the way I generate XML for instance) and that would 
       be much easier to enforce through this route. It would also have 
       the advantage of discouraging people from placing their whole 
       rationale in the abstract - which I've seen in several first 
       drafts by people who shall remain nameless - and prompting the 
       creation of TIPs more in keeping with the general concept of 
       publishable documents. 

       It would also be nice if each page had a way of viewing the TIP's 
       revision history (by a link to a suitably setup CVSweb URL?) The 
       way that SourceForge does its CVS-over-the-web is very nice 
       indeed... 

       /Donal K. Fellows <fellowsd@cs.man.ac.uk>/ 

 AUTHOR REPLIES TO COMMENTS 
============================

 Some comments I see above, or received in e-mail: 

     * /Add a link to [TIP #3] on the edit page. Display [TIP #3] in a 
       new window./ 

       Link added. I don't believe in deciding to open new browser 
       windows for the user. If the user wants to open the link in a new 
       window, she knows how to do that. 

     * /Add an interface to create a new TIP/ 

       For now, I'm trying to stick with the TIP procedures proposed in 
       [TIP #2], where only the TIP Editor gets to create a new TIP, so 
       all TIPs should still be originally submitted to him. If the TCT 
       rejects this proposal and adopts a different policy, we can 
       revisit this question. 

     * /Browser caching makes it look like the edits were not made/ 

       Based on advice from Mark Harrison and others, I've added HTTP 
       headers that should prevent caching. Please try it again. 

     * /I had the server time out on me/ 

       That's troubling. Can anyone seeing this problem provide any more 
       information. What were the circumstances, in detail? 

     * /Add links to an interface showing revision history/ 

       Check out the [History] links at the bottom of the HTML rendered 
       pages. Thanks to Donal Fellows for coding that up. (OK, so we 
       *did* reinvent CVSWeb.) 

     * /A separate <TEXTAREA> for the Abstract/ 

       This is now implemented. Please give it a try. 

 COPYRIGHT 
===========

 This document has been placed in the public domain. 

-------------------------------------------------------------------------

 TIP AutoGenerator - written by Donal K. Fellows