Revision as of 01:20, 6 April 2017

Terse Read Me File

Code: TERSE_README (with an underscore character between TERSE and README)

For Graphics Designers

If this metapattern was applied, it means that the documentation for the script is contained in the script itself rather than in a separate 'read me' file.

To read the documentation, open the script in your text editor.

There is a ReadMe file, but it will be terse and essentially will contain nothing more than instructions that direct you to open the script in a text editor.

The script file is self-contained: even if the ReadMe file gets lost, all the necessary information can be found in the script file.

First open and read the ReadMe.txt file to make sure you’re supposed to open the script.

Then open the script in a text editor, and read the documentation you’ll find at the start of the script.

For Software Developers

Your script should be accompanied by a ReadMe.txt file which contains:

• The script name
• Instructions on how to open a script in a text editor

The idea is to keep the ReadMe.txt as short and terse as possible.

This to avoid having to update it each time you update the script; the goal is a ‘write once, use forever’ ReadMe file.

The rest of the script’s documentation is contained in the script itself - the ReadMe.txt’s only function is to point people to opening the script.

The script file is self-contained: it serves as script, but also contains the documentation to the script, and possibly even does triple-duty as a default preferences file for configuring the script.

The contents of the ReadMe.txt are repeated inside the script, so that even when the script gets separated from the ReadMe.txt file, the script remains complete, and the terse ReadMe.txt can be reconstructed from the script.

Detailed description of the metapattern

The script file or files are accompanied by a file called ‘ReadMe.txt’.

This ReadMe.txt only contains the following info:

• the file name of the script
• instructions on how to open the script in a text editor

The contents of the ReadMe.txt are copied verbatim into the header area of the script, and embedded between two -- delimiters.

Example ReadMe.txt:

Script name: Outlines.jsx

For more information, please open the file 'Outlines.jsx' in a text editor program.

Example script header (with many lines removed):

/*

Script name: Outlines.jsx

 
Version: 0.0.2

 
Script Home Page: http://www.rorohiko.com/scriptcollection/outlines

 
Target(s): Adobe InDesign


... snip ...
 
ReadMe.txt contents:
 If you encounter this script without accompanying ReadMe.txt file, 
 please copy the following lines (between the two -- markers), and 
 save that text into a file called 'ReadMe.txt'

--

Script name: Outlines.jsx

For more information, please open the file 'Outlines.jsx' in a text
 editor program.

--

*/

Related metapatterns:

VERSION INTRO LICENSE