Export Collection

Select Export Collection in the Collection menu to export the current collection, the selected clips, or the active clips, into one of various file formats that can be read by other applications.

There is no toolbar button for the Export Collection command. If you’ve hidden the main menu, you can access the command by right-clicking on a collection’s tab.

The Export Collection dialog offers a lot of options to choose what is exported and in which format. Some options are geared towards producing a document for a person (who doesn’t use AceText) to read. Other options are geared towards producing files that can be processed with other applications.

What to Export

You can choose to export all the clips on the active collection tab, or the clips you’ve selected in the clip tree, or just the clip being shown in the AceText Editor. If you want to export all clips in all open collections, switch to the All Collections tab before exporting. If you only want to export the body text of the active clip without anything else, use the Save Text item in the Text menu instead of the Export Collection item in the Collection menu.

File Format

The “plain text” file format exports your collection into .txt files that can be viewed in any text editor, including Microsoft Notepad.

The “comma- or tab-delimited values” choice allows you to export .csv or .tsv files. Which will be produced depends on the delimiter characters that you specify in the bottom right corner of the Export dialog. Many applications can import data from CSV and TSV files.

The “HTML” format produces files that can be used as web pages or that can be loaded into a word processor. This is the only export format for which you can choose a color palette to retain emphasis and syntax coloring. If you choose to export into a single file in the next section then AceText embeds the style sheets for emphasis and syntax coloring into the one HTML file. If you export into multiple HTML files then AceText exports the style sheets into a separate CSS file that is then referenced by all the HTML files.

If your goal is to programmatically process a collection then it may be easier to just process the .atc file that the collection is saved in instead of exporting your collection. The AceText Collection file format is based on XML with a schema that is published at the schema URL referenced by each .atc file. This gives you access to all the details of your collection.

Not all of the following options are available for all file formats. So you should choose your file format before proceeding to set the other options.

How Many Files

The first three options export everything into a single file. You can choose to add the contents of this file as a new clip to the collection you’re exporting or to copy the contents of this file to the clipboard. In those cases AceText only produces the exported file in memory. The file is only written to disk if you select “one file for all the exported clips”.

If you are exporting multiple folders then you can choose “one file for each exported clip folder” to export all the clips in each folder into a separate file for that folder. If the folder contains subfolders then the clips in those subfolders are also exported into separate files for each of those subfolders. The details of the folder itself are exported to the same file as the folder’s clips. If the folder doesn’t have any clips then the file is still created with only the details of the folder itself.

The last two options export each clip into a separate file. Folder details are not exported. You can choose to export a subfolder for each clip folder. This uses the label of each clip folder as the name of the subfolder.

File Names

When exporting to disk you can choose how AceText should determine the file name of each exported file. The “fixed file name” option is only available when exporting everything into a single file. You’ll specify the actual file name below in the Export Location section.

When exporting one file per folder or one file per clip you can use the label of each clip or folder as the name of the file that that clip or folder is exported to. If you didn’t enter a label for a folder or a clip then the file name uses the default label such as “New Folder” or the start of the clip’s contents as the folder or file name, just as the folder or clip is displayed with in the clip tree in AceText.

When exporting one file per clip you can choose to use the clip’s AceType abbreviation as the name of the file that the clip is exported to. The file name of the Export Location is used for clips that don’t have an AceType abbreviation.

Duplicate File Names

AceText allows collections and folders to contain multiple folders and multiple clips and with the same labels or AceType abbreviations. When using labels or abbreviations to determine file names this can result in duplicate file names. Since folders on disk cannot contain multiple files with the same name, you need to choose how to handle this eventuality.

If you choose “export multiple clips to the same file” then clips with the same label are all exported into one file using that label as its file name. With this option, "one file for each clip” and “one file for each clip folder” are not strictly true. Instead you get one file or each different clip label or one file for each different folder label.

If you chose “append numbers to make file names unique” then you do get one file per clip or one file per exported clip folder in all circumstances. When the same file name is needed for multiple clips or multiple folders, the second and following ones have (2), (3), etc. appended to the file name.

Export Location

Specify the full path to the file that should be exported. You can click the (...) button to select the file in Save dialog.

The export location should always include a file name with an extension that matches the file format. AceText changes the extension to match the file format when you change the file format. But it does not enforce this extension when you edit the export location, allowing you to use a custom extension.

Even when basing file names on labels or abbreviations you need to specify a file name for the export location. It will be used as a fallback when no file name can be determined based on the label or abbreviation. This can happen when a clip doesn’t have an abbreviation or a label that contains only characters that are not valid in file names.

Kinds of Clips to Export

You can also choose which kinds of clips to export. If you deselect a certain kind of clip then no parts of clips of that kind are exported at all. If you deselect all clip kinds then only folders are exported. This can be useful to produce an outline of a large collection.

For secret clips there is an extra option whether the export may reveal secrets. If you tick “reveal secrets” and also tick the “text” part then the exported files will reveal the text of all the secret clips that you’re exporting. If you tick the “secret” kind but untick “reveal secrets” then the exported files includes all the parts of secret clips except for the “text” part. This can indirectly reveal that your collection contains secret clips as the “text” part will be exported for other kinds of clips but not for secret clips. But the secrets themselves won’t be revealed.

When exporting to plain text or a delimited text format, AceText cannot use actual colors and font styles to show emphasis. So for these formats there is another extra option to add tags to “text with emphasis” clips. If you tick this then the body text of “text with emphasis” clips has pseudo HTML tags added to the export. A clip with emphasis that looks like “label and caption” in AceText will be exported as “<lbl>label</lbl> and <cap>caption</cap>”. There’s no option to add tags to preserve syntax coloring when exporting to plain text.

Parts to Export

The “label”, “kind”, and “URL” parts apply to both clips and clip folders. The “sort” part only applies to folders. The “AceType”, “syntax”, “options”, “date”, “text”, “after text”, and “bytes” parts are the various clip parts that you can edit in the AceText Editor. The “text” part also covers the “before” text of “before & after text” clips. The “link” part is the link that is generated by the Edit|Copy Link command. The “ID” part is the item’s unique ID used by the Copy Link command. The “parent ID” parts is the ID of the folder that contains the item. Links and IDs are exported for both folders and clips if you select those parts.

You can use the Up and Down buttons to change the order of the exported parts. This determines the order in which the parts are exported for each clip each folder. This order is not used when you select “layout as in AceText” in the next section.

Layout

The “layout” section appears when exporting as plain text or as HTML. AceText can use spacing and indentation to arrange the exported parts of the clips similarly to how they are arranged in the AceText Editor. This is best if you want to present your collection for a person to read. If you want to process the export with another program then exporting the parts as a list produces a file that is easier to parse. A labeled list includes the labels from the “parts to export” list.

When exporting into HTML format, you can choose a palette for emphasis and syntax coloring. These are the same palettes that you can choose from and edit in the Appearance Preferences. If you choose a palette then clips with emphasis or syntax coloring will appear with that emphasis or syntax coloring using the colors from the selected palette when viewing the HTML file in a web browser. The palette’s background color is also used. If you intend to paste your HTML into a report that may end up being printed then you should probably choose one of the “print” palettes to give the exported HTML a pure white background.

Characters for Delimited Values

The “characters for delimited values” section appears when you set the file format to “comma- or tab-delimited values”. The value separator that you select determines whether the file will actually be comma-delimited or tab-delimited. You can also make it semicolon-delimited or pipe-delimited (vertical bar). Or you can enter any punctuation character or symbol of your choice as the value separator. In the exported file, the value separator will separate the different parts that are exported for the same clip or folder.

The row separator is the character that will separate different clips and folders. Windows files typically use CRLF line breaks while Linux or OS X files typically use LF line breaks. Some systems use the vertical tab so that line breaks within fields don’t need to be quoted or escaped. AceText also lets you use a page break (form feed character) or any punctuation character or symbol that is different from the value separator.

Since AceText clips can contain any text, there is always a possibility that one of the exported clips contains the value or row separator. To handle this, you need to specify a quote character, an escape character, or both.

If you specify only a quote character then fields that contain the value or row separator are surrounded by quote characters. If those fields also contain the quote character then those quotes are doubled. Quotes are not doubled in fields that contain the quote character but not the value or row separator.

If you specify only an escape character then that escape character is placed before the value separator, the row separator, and the escape character itself when these appear within fields.

If you specify both a quote and an escape character then fields that contain the value or row separator are surrounded by quote characters. The escape character is placed before all quote or escape characters within fields, regardless of whether those fields need to be surrounded by quote characters.

If you specify an escape character then you can also replace line breaks and tabs with escaped letters. If you tick this option and select the backslash as your escape character, then tabs are replaced with \t, carriage returns with \r, line feeds with \n, form feeds with \f, and vertical tabs with \v. If you enter another different escape character then you get the same letters with your chosen escape character. If you use this option and your value separator is a tab or your row separator is a line break then fields are never considered to contain that value or row separator as it will be replaced with an escaped letter, removing the need for the field to be quoted.

By default, AceText uses a comma as the value separator, a CRLF line break as the row separator, a double quote as the quote character, and no escape character. This is the format that Microsoft Excel uses for CSV files. If your computer is configured to use the comma as a decimal separator, then you should select the semicolon as your value separator for compatibility with Excel.