What is it ?

Stapled is an original utility letting you share your artistic creations in their best quality, at locations previously reserved to photographs (1)

Any plain document can be morphed into a picture document, and, consequently, handled and stored as an image file can be.

For more information, see Staple (the action of creating a picture from a document) or Unstaple (the action of re-creating the original document from its picture).

(1) registered under the i-Depot number 052803 at the BOIP

What’s new ?

Stapled 2.4 adds a “scrambling” feature.

In previous versions, any stapled document was used “as is” in the generated picture. This never caused any problem until a recent change in the way some protective software (antivirus, a.o.) now handles such pictures.

This version allows the document to staple to be scrambled in the generated picture : you are now able to send them by mail, as before — no more “This message was blocked because its content presents a potential security issue”.

This version is fully compatible with Monterey and uses the latest SF Symbols.

A small Trash icon will let you select back the Trash as a destination for remaining documents, in case you changed it and want to revert to the default location (the Finder, on Monterey, won’t let you select the trash — which makes the previous official method obsolete).

This version also detects when the application is used as a Droplet but the destination of the processed documents was the trash — the application still remains opened after correctly processing the items (disabling the Droplet effect), but now explains the reason.

Last point, but not least, the webservice douwere.com/unstapler has been modified to process files locally : the unstaple process does NOT required any upload to our servers, insuring user privacy (of course, now, it can also unstaple the new scrambled documents).

Stapled 2.3 is a maintenance update.

This version is supported on Big Sur, and runs natively on Apple Silicon.

Stapled 2.3.1 brings back the ability to use a custom image for the stapled file.

Stapled 2.2 adds a Preferences window.

You can now change the default preferences of the Staple operation without actually making one.

Select the appearance to be dark or light, independently of the global settings defined in System Preferences.

This version is supported on Catalina and has been adapted to exploit its advanced security mechanisms.

Stapled 2.1 brings alternate behaviours.

This new version allows you to define the specific preferences for each operation : simply hold down the option key (alt) when dropping an item on the application, to bring up a window.

These preferences can be used as default preferences for subsequent operations by holding down the option key (alt) when you want to continue processing.

This version also fixes a problem when processing empty files (these were not handled correctly).

Finally, it improves the mechanism detecting the desired operation (the presence or absence of “-stapled” in the name is no longer taken into account).

Stapled 2.0 is a major update.

This version is supported on Mojave and has been adapted to exploit its dark mode.

This new version uses a window mechanism with a more “modern” look... where the sidebar is displayed in the window.

The generated images are in high resolution and are displayed more clearly on the Retina screens.

A complete rewrite of the application (and its associated processing module) was done in Swift, a programming language that offers improved performance.

Stapled 1.3 also processes folders.

Now, the Stapled application accepts folders by compressing them for you in a .zip file, as soon as you drop them for processing. This also work for self-contained applications and bundles.

The document format remains unchanged : the operation of getting the original document from these new images remains compatible with the previous versions of Stapled, as well as with the free Web service.

This version is supported on El Capitan, and has been adapted to use Photos (with a valid picture).

It also corrects a small regression introduced in version 1.2.1 : the post-process script is now remembered again between launches.

Stapled 1.2 drag and drop behaviour has been drastically enhanced, as it is now possible to use the application as a “Droplet”.

Now, when the Stapled application is NOT running yet, once files are dropped on the application icon, the window appears classically, but disappears as soon as the processing is done. You have a convenient way to just Staple one document (thanks, Tod, for your feedback about this).

Put the icon in the Dock : you just need to drag the file to Staple (or Unstaple) there, and voilà! it has been processed : you can return to another task.

IMPORTANT

Be sure to specify, in the popup menu, where the created files are to be placed.

Stapled 1.1 brought a way to post-process Stapled or Unstapled files, automatically, in stride, using custom User Scripts, written in AppleScript.

For example, you can upload the pictures just Stapled from any document to iPhoto automatically (and to your Photo Stream, if applicable)…

on stapled(newPictureFile)

tell application "iPhoto" to open newPictureFile

end stapled

…and re-open documents recovered from Stapled pictures automatically.

on unstapled(previousDocumentFile)

tell application "Finder" to open previousDocumentFile

end unstapled

Just select the action you want using the popup menu at the bottom of the main window (see the Frequently asked Questions).

How does it work ?

Staple

Open any document with the application : it creates a new document — litterally a picture — rendering a preview of the original document… but a somewhat special picture, that also embeds the original document, at its full quality.

Wherever you put this picture, you also put the original document : the original document has been “stapled” with the picture (hence the staple, drawn on the picture).

Unstaple

When you open back a picture created by Stapled (or a copy of it) into the application : it will magically re-create the original document !

The original document has been “unstapled” from the picture.

IMPORTANT

This re-creation of any original document can also be done using a free and anonymous web service, at douwere.com/unstapler.

Practical uses

Share your pictures in full quality

Many sharing services in the cloud let you share pictures in a standard format (.jpeg or .png)… but few will let you share them in their native unaltered format (.raw).

Using Staple, you can create a “stapled” .png document embedding the original .raw file.

This “stapled” document, when downloaded at its original quality, can then be used to re-create the original .raw file.

Share your document in native format

Most pictures on the web are shared in a so called “bitmap” format (.jpeg or .png)… for sharing “vectorial” formats (.eps, .svg, .psd, .pdf, etc), you need to use specialised services, or disk based services (a fee is often required after few megabytes are used).

Using Staple, you can create a “stapled” .png document embedding the original file.

This “stapled” document, when download at its original quality, can then be used to re-create the vectorial original file… such a file offers a significatively better printout.

This illustrates bitmap versus vector images (drawn on the screen at the resolution of the printout).

Classical image	Image from “Stapled” document

IMPORTANT

Please, be sure to respect the guidelines of your provider and not, for example, to succumb to the tentation of using their services as CDN replacements. Be also aware that the policy of such providers are able to change at any time, and that the recovery of stored pictures in their original format may not be indefinitely guaranteed.

Store and retrieve your archived documents visually

Use your favorite picture navigator to categorise and browse your “stapled” documents.

Group them by events.

Add tags.

Find them back, by their visual appearance (here using GraphicConverter).

Synchronise documents across OS X devices automatically

Photo Stream is a service provided by Apple, inc. to synchronise the iPhoto library across your devices. You can turn on Photo Stream for any of these supported devices, and your latest photos will automatically be shared between any devices on your Apple account that have Photo Stream turned on.

As any document created with Staple is a picture, it can be added in a iPhoto library… with Photo Stream turned on, your added document will automatically be shared between your OS X devices.

Photo Stream is also available on iOS devices, but, today, the ability to get pictures in their original format (required to recover the original document stapled with the picture) seems unavailable. Anyway, the iOS design supersedes the document concept.

Fill your free terabyte of storage with backups

Some excellent providers are giving away hundreds of megabytes for free, to store pictures… as any document created with Staple is a picture (a .png file, using the official “Portable Network Graphic” format), it can be stored in their facilities.

To backup files, you can compress them in a so called “archive” file (.zip, .tgz, .rar, etc). Using Staple, you can then create a “stapled” .png document embedding such a file. This “stapled” document, when downloaded at its original quality, can then be used to re-create the original archive, hence the original files.

IMPORTANT

Please, be sure to respect the guidelines of your provider and not, for example, to succumb to the tentation of using their services as CDN replacements. Be also aware that the policy of such providers are able to change at any time, and that the recovery of stored pictures in their original format may not be indefinitely guaranteed.

Safely transmit “special” files by mail

Many security programs or anti virus facilities are not so clever, and sometimes reject innocuous files just because of their undesired file name extension.

If you ever tried to send by mail a JavaScript™ file to someone working in a company where such tools are running, you know the frustration of seeing your file deleted just because of its .js extension — the attachement being intrinsically OK… and you know that sending a .zip file will often receive the same treatment.

Using Staple, you can create a “stapled” .png document embedding the original .js file. This “stapled” document, being a picture, is safe : it will not be removed from your mail… and will reach its destination.  Your recipient can then get your original .js file back, by dropping the picture into the Staple utility or into the free and anonymous web page, at douwere.com/unstapler.

Make nice mails, attaching previews of your documents

When they are not in a known graphical format, files attached to e-mails are often rendered with generic icons.

On the other hand, most mail programs preview attached graphic files.

Some clever mail clients do even try to render non graphical attachment (such as Office documents, or .pdf files)… but then, such rendering is sometimes a longer than expected task.

By sending your documents as “stapled” pictures, you make the recipient work easier, by giving an immediate preview of your document.

Embed your documents directly in your website

Creating nice website pages is today often easy, with affordable and powerful tools… but things are getting a little more difficult when you need to attach documents.

Indeed, after designing your page, you have to add hypertext links to encoded URLs, and to upload the related documents accordingly.

Buy using “stapled” images, you drop your documents into your pages as easily as you drop your images — documents generated by Stapled are images !… and the visitors just do the drag from the page to their desktop before retrieving the original document, by dropping them into the Staple utility or into the free and anonymous web page, at douwere.com/unstapler.

Free (as in beer) — or not ?

The Stapled utility is free (and will always be).

The documents generated by the Stapled utility are fully compliant with the given description — they are full featured pictures (in the .png format) embedding the original documents.

Original documents could always be re-created by just opening the pictures generated by the application (the “attached” pictures) with the same application.

There is no demo mode nor time limitation.

We do our best in order to maintain an anonymous web service available at douwere.com/unstapler… in case you need to get back original documents but have no access to the standalone utility.

Unlocking

If you like the idea of Stapled, if you want to help us improve the product, or if you would like to avoid the manual renaming of the files (they are, by default, only named “Stapled DEMO”), you can unlock the product.

The unlocked application will create its files with the same names as the original documents, postfixed with “-stapled”.

This purchase is triggered by clicking the lock, in the top right of the main window (or by choosing “Unlock…” from the application menu).

You only need to make the purchase once, and it will be available on all your devices. The payment is secured and handled by Apple, thru the App Store.

Frequently asked Questions

I can’t find the picture created — where is it ?

The Stapled utility creates its files inside the application, each using the same name (1) as the original document, postfixed with “-stapled” (or with the original document name, when extracting from a picture).

For its own safety, as required by the App Store guidelines, it’s up to the user to move the created documents away from the application window, wherever appropriate.

Any item still in the application window when quitting, is not lost but moved, by default, to the trash. The user can change this default behaviour, and select another location where the files will be kept. Anyway, if there is any name conflict, the default behaviour will prevail.

(1) Please note that the locked version of Stapled always uses the “Stapled DEMO” file name when creating the picture.

I can’t see the rendering of .eps files anymore — what is wrong ?

Before Monterey, when dropping a .eps file, Stapled was able to create a picture with the rendering of the embedded postscript.

Picture with preview

Since Monterey, Stapled renders a generic icon (with a small text, indicating the EPS nature of the file).

Picture with generic icon

Stapled is using official system calls to generate its preview... the EPS rendering was deliberately disabled in the OS by Apple (probably for security reasons), but you can bring it back by entering this into the Terminal application.

    cp -pR /System/Library/QuickLook/Illustrator.qlgenerator /tmp

    sed -i '' -e 's|>string>com.adobe.illustrator.ai-image>/string>|>string>com.adobe.illustrator.ai-image>/string>>string>com.adobe.encapsulated-postscript>/string>|' /tmp/Illustrator.qlgenerator/Contents/Info.plist

    sudo mv /tmp/Illustrator.qlgenerator /Library/QuickLook

These changes are only effective at next login (i.e. you may need to log out of your session).

I edited my picture, and can’t find back my document — what did I do wrong ?

In order to restore the original document, the Stapled application of course requires some extra information embedded into the picture.

If the picture has been modified, it should still contain this information but we got some feedback about some graphical utilities that do not respect the Portable Network Graphics standard and do remove this information… others keep this information, but alter the order of them, rendering the unstapling operation impossible.

You should avoid modifying any picture created by Stapled.

IMPORTANT

If you need a special image for the picture to staple, create it and assign it using the Finder before you drop your file onto the application : Stapled will always give priority to any custom icon when generating its picture.

I can’t find back any document out of my picture — what did I do wrong ?

By dropping a picture created by Stapled (or a copy of it) onto the application, the original document is restored.

If the picture has been transfered, it should still contain the information required to re-create the document but some transfer mechanisms do remove this information… hopefully this is not frequent.

If you downloaded from a web site, you just need to be sure that you requested the file in its “original” format or “best” resolution — as some web based solution do adjust the size of the download regarding to the screen size, screen resolution or medium.

If you got the image by mail, some systems do rewrite attachements ignoring “comment-like” information in images. But this is very infrequent — maybe the image sent was already wrong. You should ask the sender to check.

I have an error executing my script — what did I do wrong ?

The script requires two handlers to be present : “on staple” and “on unstaple”. The first handler is called when an image is generated; the second one, when an original document is restored. Each of them receive the related file as argument (an alias of a file, to be correct).

If you do not need any action for one of the handlers, just leave an empty body (i.e. do not remove the handler completely)… as the Stapled application will always try to call them, and generates an error message when the expected handler is not found.

If both handlers are present, you can check if they are running as expected out of the Stapled application, by using the standard AppleScript tools… just be sure to have a “on run” handler calling your code with an alias file, and run the script.

By choosing the item “Save an example of User Script” in the popup menu at the bottom of the main window, the application will save a valid script that you can use as a starting point for your own needs.

I see, in examples, PaperClips instead of Staples — Why ?

Version 1.0 used to add a PaperClip on each generated picture… from version 1.1, the default behaviour is to add a real Staple.

Version 1.0	Version 1.1

You can revert to original behaviour by entering this into the Terminal application…

    defaults write com.douwere.Stapled usePaperClip -bool YES

…and, if you change your mind,

    defaults write com.douwere.Stapled usePaperClip -bool NO

to draw Staples again.

Please note that since version 2.1, it is possible to modify the preferences directly in the application.

How can I (re-)select the Trash as a destination for unused files ?

The default behaviour of the application is to move unused files to the Trash... and this destination can be changed to any folder, using this popup menu.

The Desktop is here the default destination

The Finder never let you chose back the Trash easily ! Since Monterey, the previous trick (this sequence of keys while the selection dialog is open)

    Command-Shift-H   Command-Shift-G   T   R   Tab   Enter

seems even impossible. You now just need to click the Trash, to revert to the initial behaviour.

I prefer low resolutions images, because they require less space… how do I get back the old behaviour ?

Version 1.3 generated low resolution pictures… from version 2.0 onwards, the default behaviour is to generate hight resolution pictures.

You can revert to original behaviour by entering this into the Terminal application…

    defaults write com.douwere.Stapled doesNotWantRetina -bool YES

…and, if you change your mind,

    defaults write com.douwere.Stapled doesNotWantRetina -bool NO

to generate low resolution pictures again.

Please note that since version 2.1, it is possible to modify the preferences directly in the application.

How can I assign a special image using the Finder ?

How can I assign a special image using the Finder ?

Three steps are required:

     1. put the image into the clipboard (a way to do this is to open this image using “Preview”, select all of it (pressing command-A) then copy it using command-C);

     2. open the Information window of the file to staple (select it, in the Finder, then press command-I);

     3. click the icon on the top left corner of this window, and paste the image from the clipboard (pressing command-V).

This last step should change the file icon displayed by the Finder… and the image used by Stapled. You can revert to the original icon, by pressing the delete key, after selecting it in the information window of the Finder.