REXX - Top header comments Suggestion

[Martin Iturbide]

Hi

I know this is a thing of personal taste, but can you please recommend a good "comment header" for REXX scripts.

For example I liked this one:

Code: [Select]

/* REXX */
/* Title : Meteor                                           */
/* Desc  : A simple action game                             */
/* Author: Jeff Byrd, jeff.byrd@xxxxxx.vanderbilt.xxx       */
/* Date  : 12/22/95                                         */
/*                                                          */
/* Notes : If you run this program from a mapped network    */
/*         drive, the high score list and demos will be     */
/*         shared among all the players.                    */
/*         Make sure to note all the hints on how to play.  */
/*         To clear the high score/demo list, delete all    */
/*         *.MSV files.                                     */

Any other layout that you like or recommend for the REXX scripts?

Regards

[Andreas Schnellbacher]

I use the headers Christian has created for several filetypes.

The REXX header prototype is header.cmd_rex. An example is icons.cmd. (SVN would have expanded the $Id$ line. Trac as well, but it refuses to display .cmd files.)

An example for another header I've used for another project is:

Code: [Select]

/****************************************************************************
* pmcall.cmd
*
* Version: 2019-08-11
*
* Syntax: pmcall.exe  [-m] [-b] [-l <log_file>] <cmd_name> [<cmd_args>]
*
*    -m  Messages enabled (STDOUT and STDERR/PM)
*    -b  Error beeps enabled
*    -l  Logging enabled
*    -h, -?  Show help message
*
* Provide a PM environment for .cmd files.
*
* o  It opens a queue, whose name is provided as env var 'ERRORQUEUE'.
* o  It executes the submitted cmd_name and its args.
* o  After execution of cmd_name, It reads the contents of ErrorQueue and
*    presents it in a PM message box. This is useful in cases where messages
*    would be lost otherwise.
* o  This is compiled to a PM executable to make the submitted cmd_name run
*    in a PM env: REXX2EXE /P [/K] pmcall.cmd pmcall.exe
*
* Part of the DOSBox installation. May also be used for other cases.
*
* By Andreas Schnellbacher <mailto:###>
* Contains REXX code from the NEPMD project.
****************************************************************************/


[Dariusz Piatkowski]

Here is what I use:

Code: [Select]

/*------------------------- New Concepts Consulting --------------------------
- Application Module Name : WPS
- File Name               : folder_refresh.cmd
- Date                    : April 12, 2020
- Author                  : Dariusz Piatkowski
-                                                                             
- Description:                                                                 
- There occasionally arises a need to force a refresh of a folder. This is
- intended to make sure that WPS is aware of any changes that have occured at
- a filesystem level, such as: adding or deleting an object (file or folder).
-
- There are a couple of alternative approaches to use here:                 
- 1) follow the approach implemented here, call this REXX script 
-    as follows: 'refresh_folder.cmd fully_qualified_folder_path'                 
- 2) utilize an existing utility such as OO.EXE and issue a call 
-    to list the contents of a folder but do not create output, as follows:
-    'oo.exe /L folder_name > nul'
-                                                                 
- Both will force the WPS to refresh the folder contents.
-
- Parameters:
- INPUT => fully qualified folder path
-
- Modification History
-
-    REVISON        DATE/TIME         AUTHOR
-
-   Rev 1.0.0  APR 12, 2020 17:05:00   Dariusz Piatkowski
- First version of the code.
-
-   Rev 1.0.1  APR 18, 2020 18:35:00   Dariusz Piatkowski
- Added the check for a valid INPUT parameter, if not found RETURN error.
-
------------------------------------------------------------------------------*/


[Martin Iturbide]

Thanks for sharing the samples. Both look better than the one I found.

Regards

[Wendy Krieger]

Most of my REXX scripts come out of weave.  This means I write a commentry on the program, and run that through weave to produce the rexx script (etc).

Code: [Select]

/* REXX Woven from zrxc.cmd by Wendy Krieger on 20210630 at 20:52:58 */
/*~ Rexx Maths calculator v0.203 */; numeric digits 60; numeric fuzz 1;
setpi = 2; econst=0; ln2p=0 ; nd = digits()


The first line tells me when and where the source is, the second is picked up by the description program.

Code: [Select]

extproc weave.rex
regina woven.rex zrxc.cmd
::~ source for rxc v 0.202

goto :eof
!topic About

This is a rebuild of the rexx calculator

   see   http://www.lightlink.com/hessling/
   or    http://regina-rexx.sourceforge.net/

Album of algorithms at  http://www.geocities.com/zabrodskyvlada/aat/
  (also available in Czech [cesky]

The calculator is not strictly related to one field, but just acquires
functions as i need them.  Most of them are however, either hyperbolic
geometry or higher dimensional stuff.


!topic Settings

!src
!set [rxc version                  ] yvers 0.203
!exe mainrexx #..\rxc.rex##Rexx Maths calculator v##
!lbl settings - *******************************************
!set [  $#disp#high#low#           ] yexp120 $#20#16#-4#
!set [    decimal in base 1000     ] yexp010 $#126E36#9#-3#
!set [disp 1+1/ydspadd             ] ydspadd 1e50
!lbl rexxsets - *******************************************
numeric digits 60; numeric fuzz 1;
setpi = 2; econst=0; ln2p=0 ; nd = digits()
!inc units  We handle some conversion factors now.
!end

  In non-twelfty bases, we look to see the size of 126E38 is in
  the base in question, and use that many places.  The reason for
  this is to keep the same level of precision throughout.


Most of the stuff in the second bit is simply intro, it isn't the first part of the code, just some random insert to it. 

It's actually an extproc command I run under 4nt.  The program that accepts this is weave.rex, which is also written in a similar style on a simple print on/off tangle.rex.  So tangle.rex is used to compile weave.rex, which is used to write all sorts of other things.

The bits of code that are 'commented out' or not included in the compile can still be in the source, but simply bypassed in the compile.

The program is handy enough that you can write a number of matching code pieces to different files, like write a matching 4DOS.INI and 4OS2.INI at once.

rxc.cmd is the command-line calculator, it's 22.170 bytes, the source code is 37.249 bytes.  The !topic is the 4dos help topic header, is what I use for bait for a folding editor.    This is what turns up on the fold. 

Code: [Select]

File: D:\save\cdata\BATCH\zsource\zrxc.cmd 47 occurrences found on 47 lines
     6: !topic About
    21: !topic Settings
    41: !topic Conversion factors
   130: !topic functions
   161: !topic - vf (vulgar fractions)
   175: !topic - sp, sm
   190: !topic - star()
   209: !topic - klein (convert Eq to Kq)
   253: !topic h2k and k2h  [Guage rule]
   294: !topic - tube
   334: !topic - a1_a2
   348: !topic - c1_c2
   366: !topic - ij
   410: !topic - fact()
   422: !topic - borr()
   443: !topic Complex
   461: !topic Base
   478: !topic fract
   494: !topic Zspans
   534: !topic Diameters & Edges - d2 and e2
   560: !topic some sequences
   591: !topic distances   dx
   604: !topic isoquad
   644: !topic addquad
   668: !topic modulo functions
   718: !topic - rss
   732: !topic - ddif
   743: !topic - mp
   755: !topic - DOS
   761: !topic - rxxmath
   774: !topic Twelfty
   810: !topic - Powerset(base, pos number)
   834: !topic - other bases
   863: !topic Program
   881: !topic - RexCalc
   905: !topic version stuff
   912: !topic Standard functions
   933: !topic - cbrt
   954: !topic - sqrt
   975: !topic - sin
  1001: !topic - - sinp
  1014: !topic - - cosp
  1023: !topic - pi
  1056: !topic - - piconst
  1065: !topic - pow
  1080: !topic - Ln()
  1128: !eof !topic Remmed out stuff