Latest revision as of 01:53, 6 April 2017

Wrap Scripts Into An Archive File For Downloading

Metapattern Code: ZIP

Because script files are really just text files, they are often treated as such, and their contents copy-pasted into on-line forums, e-mails, web pages and blog posts.

However, doing that often causes problems. In the process, line endings are often changed from one type to another (see LINE_END_CRLF).

Sometimes particular characters, like quotes or double quotes, can inadvertently get changed over to their curly versions, which breaks the script.

In order to protect a script from these undesirable modifications, it is best to store it into a ZIP archive before releasing it to the world.

ZIP archives are well-supported, both on Macintosh and on Windows.

For Graphics Designers

Windows

When you get hold of a ZIP-ped script, you need to first decompress it.

There are many ways to go about it, and many tools that help you do this.

Our favorite approach is the following:

• put the .ZIP file onto the desktop
• right-click the .ZIP file icon and select ‘Extract All...’. A new folder by the same name should now appear on your desktop.

You can now either delete the original .ZIP file or move it somewhere else for safekeeping - you don’t need it any more.

Navigate into the folder, and open the ReadMe files and .JSX files you find in your text editor.

In some cases, you might find one or more additional levels of folders that you need to navigate into before getting to the ‘meat’.

Windows And Green File Names

If you find that all filenames in the resulting folder are green instead of black, that’s a sign the .ZIP file was created on a Macintosh.

For some reason, extracting Mac-created .ZIP files results in encrypted files on Windows. Such files can be recognized by their green filenames.

As such, the green filename is harmless - the setting only affects how the file is stored on disk, and does not affect how you use the file.

To get rid of the green names:

• right-click the folder on the desktop, and select ‘Properties...’

• click the ‘Advanced...’ button

• untick the ‘Encrypt contents to secure data’ option

• click OK 

• click Apply

• select ‘Apply changes to this folder, subfolders and files’

• click OK.

More info in the Appendix - Encrypted Windows Files Have Green Filenames

Macintosh

Macintosh users can normally simply double-click the ZIP file and it should automatically expand.

If it does not, you might have a broken file name extension association. To correct that, right-click or control-click the ZIP file icon, and select the ‘Get Info...’ context menu item.

On the resulting dialog, make sure the ‘Open With...’ selection is set to ‘Archive Utility’ or ‘BOM Archive Helper’.

If it is not, make sure to click the ‘Change All...’ button after correcting it, so any new .ZIP files you receive will open correctly from then on.

For Software Developers

There are many ways to create a .ZIP file. I’ll outline the approach we use for our material at Rorohiko.

The idea is to have

• as few levels of nesting in the .ZIP file as possible.
• avoid the ‘green filename’ issue for Windows users with Macintosh-originating .ZIP files.

Follow the procedures below closely. It is easy to get it wrong and create sub-optimal .ZIP files that cause unnecessary confusion for the end-users.

If you don’t do it exactly right, you’ll end up with a .ZIP with additional nested folder levels.

Windows

Put the script (.JSX file) and the ReadMe.txt icons right next to one another on your desktop.

Select the icons of both files by click, shift-clic. With both icons selected, use right-click to bring up the context menu.

Select ‘Send To’ - ‘Compressed (zipped) Folder’.

The resulting .ZIP file is incorrectly named; it will be named after one of the two files.

Modify the .ZIP file name to match the name of the script, but without the .JSX extension.

For example, if the script is called ‘CreateOutlines.jsx’, the .ZIP file might initially be called ‘ReadMe.txt.zip’ or ‘CreateOutlines.jsx.zip’.

It should then be renamed to ‘CreateOutlines.zip’.

Pay attention as to whether Explorer shows or hides file name extensions, and avoid doubling up the name extension. For example, do not accidentally rename the zip file to CreateOutlines.zip.zip.

Warning: don’t put the script and the ReadMe into a folder, then compress the folder. Doing it that way enforces an extra ‘folder level’ into the .ZIP file which confuses a lot of users.

Macintosh

By using the command-line zip utility instead of the Finder’s built in compression feature, we can avoid the ‘green name’ issue for Windows users.

Create a folder on your desktop that has the same name as the script, but without the .JSX file name extension.

Put the script and the ReadMe file into this folder.

Go into the /Applications/Utilities and start the Terminal

For the sake of argument, let’s assume the script is called ‘CreateOutlines.jsx’ and you’ve stored both script and ReadMe.txt in a folder called ‘CreateOutlines’ on your desktop.

Also, you want to delete any .DS_Store files before zip-ping: they are confusing for Windows users.

Type the following commands into the Terminal window. Pay attention to spaces. Omitting any spaces will cause things to fail:

cd ~/Desktop

cd CreateOutlines
rm -f .DS_Store
zip -r ../CreateOutlines.zip *

You should now have CreateOutlines.zip on your desktop - this is a cross-platform compatible .ZIP that is not prone to the green filename issue and does not have a .DS_Store file in it.

Detailed description of the metapattern

The script file and its ReadMe.txt file are released inside of a cross-platform compatible .ZIP file, which does not have unnecessary nested folders inside.

Avoid using the Macintosh Finder ‘Compress’ functionality.