Documenting the HESSI object parameters,  
Kim Tolbert, 14-Aug-2002
Updated 1-Dec-2020

Key files used in process:

hsi_params_manual.pro - a procedure that returns a structure with all of the manually modified entries for the parameter table.  
 
hsi_params.pro - a procedure that returns a structure with all of the descriptions of HESSI parameters.  This file (hsi_params.pro) is generated by the program hsi_params_write_pro automatically by looking at the HESSI source code (all of the hsi*control__define procedures, etc) and finding all control and info parameters, then merging the information it found automatically with the information in hsi_params_manual.pro.  Once this file has been generated, to run it, just type hsi_params,d.  d will be a structure with the following tags:
   str = {hsi_params_str, $
	name: '', $
	class: '', $
	main_object: '', $
	type: '', $
	units: '', $
	default: '', $
	range: '', $
	control_or_info: '', $
	level: '', $
	purpose: '', $
	more_doc: '' }
NOTE: this file should never be modified by hand.  It will be overwritten.


hsi_params_write_pro - Run this procedure to create the hsi_params.pro.  Tries to figure out what it can from the source code in $SSW/hessi/idl.  Merges that information with what's already been entered into hsi_params_manual.pro.  Gets the main_object information from a text file called hsi_params_main_object.txt.

hsi_params_write_htm - Run this procedure to create the html tables from the structure created by hsi_params.pro.  Compares each htm file it is going to create with the existing file (on $SSW/hessi/doc) if any, and if the content has changed, writes a new one in the current directory.  Uses the file hsi_params_template.htm as a template to create the htm files.


The procedure for updating the parameter tables is mostly automated, but requires some intervention.  These are the steps required:

1. Run hsi_params_write_pro.  This will create a hsi_params.pro in your working directory.  Look at the messages printed in the IDL log to see if there are new parameters that need to be added to hsi_params_manual.pro or if something has changed.  If so copy a version of hsi_params_manual.pro to your working directory.  For each new parameter copy the stanza in the hsi_params to hsi_params_manual.pro, deleting the lines defining the following tags: main_object, type, and control_or_info (can now do this afterwards, all at once, with the script called fix_hsi_params_manual).  (If you leave them there, they will always override what was found automatically, even if they changed.)  Edit the other fields to be correct - especially 'default', 'purpose', and 'more_doc'.  Purpose should be a short description that can fit in the description column in the html table.  Also edit any parameters whose default has changed, or if the class has changed, delete the old stanza in the old class, and copy the new one, etc.
If more explanation is necessary, then more_doc should contain a complete description.  If more_doc is not a blank string (and does not start with '>', see below), then a separate little html file will be made containing that description called xxx.htm, and in the html table, the parameter name will be made a hyperlink which will bring up that little description html page.  For some parameters that are linked, it is better to have all of those explanations in a single little html file.  In that case put all of the explanations in one of the parameter's more_doc field (doesn't matter which parameter), and for the others that are also explained in that single 'more_doc', put '>xxx' in the more_doc field, where xxx is the name of the parameter that has the full more_doc explanation (e.g. see im_time_interval which explains ~4 parameters). 

2. Compile the new hsi_params_manual.pro, and run hsi_params_write_pro again.  Repeat steps 1 and 2 until the manual file has all of the new parameters.  

3. Compile the most recently written version of hsi_params.pro and run hsi_params_write_htm.

4. Any new htm files that were written, or any existing htm files in $SSW/hessi/doc that were re-written are in the current directory.  Copy the new htm files to $SSW/hessi/doc to put them online. 

5. Copy the new hsi_params_manual.pro to $SSW/hessi/idl/gen.