Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!sdd.hp.com!zaphod.mps.ohio-state.edu!ub!uhura.cc.rochester.edu!steve@bat.lle.rochester.edu
From: steve@bat.lle.rochester.edu (Steve Swales)
Newsgroups: comp.lang.idl-pvwave
Subject: Re: Call for volunteer anomyous FTP site
Message-ID: <8906@ur-cc.UUCP>
Date: 10 Aug 90 18:25:16 GMT
References: <6184@aplcen.apl.jhu.edu> <221@locke.water.ca.gov> <24608@boulder.Colorado.EDU>
Sender: news@uhura.cc.rochester.edu
Organization: UofR Laboratory for Laser Energetics
Lines: 50

In article <24608@boulder.Colorado.EDU> jones@crash.Colorado.EDU (Mike Jones) writes:
>That's right. We should make the documentation compatable with
>the doc_library routine. The best way to do that is to fill out the library
>template. On my (Wave on DS3100) Ultrix system that is in
>/usr/local/lib/wave/lib/template.  On a VMS machine use 
>lib/extr/out=template.pro wave$library
>
>I've used this template for 5 years in IDL and Wave and find it quite 
>useful, even for my own projects when I don't expect anyone else to 
>read the code.

I agree that using the 'standard' template is a good idea.
I've actually been using a somewhat modified version of this template, 
so that i can run a filter on the code to make a UNIX-style manual page,
This entails adding a few fields before the ;+ that a man page usually
has, and which are useful to the programmer, but not really to the user.
My template is:

;
; FILE:         $proto.pro
; AUTHOR:       $author
; DATE:         $date   (Created: $date)
; PURPOSE:      $purpose
;+
; SYNOPSIS:     $proto
; DESCRIPTION:  $purpose
;-

The $ fields are filled in by my application templating code. My manual
page generator looks for these keywords, but anthing between the ;+
and the ;- is basically copied verbatum to the manual page, so actually
the 'standard' stuff would do just as well. Being a UNIX type, I'm used
to just SYNOPSIS & DESCRIPTION, so I've found these sufficient, and
more to the point than the many fields of the standard template. Much
of what appears inside the standard template is of generally no interest
to the user, IMHO.

In any event, the fields BEFORE the ;+ can be included in addition to the
stanard ones, to augment the file documentation, without interefering with
the standard recognized by doc_library, so I would suggest that this
extension (or something similar) be adopted. just my $.02.

-steve
--
-------------------------------------------------------+"Come, Watson, come!"
 Steve Swales                (716) 275-0265,-3857,-5101| he cried. "The game is
 steve@bat.lle.rochester.edu           (128.151.32.111)| afoot. Not a word!
 {decvax,harvard,ames,rutgers}!rochester!ur-laser!steve| Into your clothes and
 University of Rochester            250 East River Road| come!"		S.H.
 Laboratory for Laser Energetics    Rochester, NY 14623|     'The Abbey Grange'