Filesets and the Fileset Menu

Alpha
Version:	9.2.3 - "Suhail"
Last update:	2021-05-21 14:43:30

This help file describes filesets and the Fileset Menu.

Introduction
Activating the Fileset Menu
Getting started
Fileset types
Fileset Menu Cache
Current Fileset
Filesets Handling Submenus
Fileset Preferences
TeX Filesets
Additional fileset information
License and Disclaimer

Introduction

A fileset is simply a method or set of rules to create a list of files. This list can then be used for several different purposes. The most basic usage is to present the list of files so that one of them can be opened for editing. The Fileset Menu will present the contents of most filesets in a drop-down menu; selecting any one of them will open the file in Alpha.
See the Menus Preferences dialog. Filesets are also used to create lists of files for multiple-file searches and tag searches, among other things. Typically, a user will set up several different file sets, such as:

all html files in a web site
all source files in a programming project
a local image of a remote cvs code repository
all files on a remote ftp site
all documents in a multi-part LaTeX document

Each fileset is composed of a set of criteria to create a list. These criteria can be as simple as

All files recursively contained within a given directory.

All of the files in this specific list.

or there can be more complex membership rules such as

All of the files in a given hierarchy, including those whose names begin with draft, but excluding those whose names end with .log and .aux

The Fileset Menu allows you to include the listing of your commonly used filesets: each one will appear as a submenu whose label is the name of the fileset (which you specify when you create the fileset), and whose contents are the names of the files within the fileset. Selecting an item in the menu will open the file for editing. For each fileset you create, you may also decide not to place it in the menu but rather to have it hidden. Hidden filesets are fully functional in every way to every other part of Alpha which interacts with filesets; they are simply not shown in the menu.
In fact Alpha automatically creates some special filesets which you can use, but which do not appear in the filesets menu. One of these is a fileset containing all recently used files; another is a fileset containing all currently open windows --- these can be very useful for search operations, for example. The reason these filesets are not shown in the filesets menu is that they are updated very frequently, and already feature in the Windows and Recent-Files menus.

Activating the Fileset Menu

The Fileset Menu, like all of Alpha's menus, is activated in the dialog Alpha ↣ Global Setup ↣ Menus.
See the Menus Preferences dialog. Check the Fileset Menu box among the global menus, and it should appear in the menu bar. For new users it is automatically activated, so it should already be in the menu bar. If icons are used in your menu bar, this menu looks like a stack of overlapping documents. If icons are not used, then this menu is simply called Fileset.

Getting started

As an introductory example this section describes how to create a new fileset with all files in a folder. (See the Fileset types section below for information about the proper settings for other types of filesets.)

Create a new fileset by selecting Filesets Menu ↣ Utilities ↣ New Fileset (click here for an example.
You are now asked for the name and type of the fileset you want. Let's give it the name My fileset, and for the type, we'll use From Directory (the default) since we wish to create a fileset with the files in a directory. Assuming you want to keep this fileset permanently, don't click the box saying this is a temporary fileset.
You are now presented with a dialog from which you can set all aspects of this fileset. The most important is to select the folder/directory containing files you might like quick access to. Click on the Set... button to do this.
Next you need to give a pattern for the fileset, specifying which files in the folder to include in the fileset. To include all files use the default pattern '*' (or leave the pattern empty). See the section File Patterns in the Alpha manual ("Alpha Manual # File Patterns") to learn how to specify file patterns.
There are a number of other options in the dialog, which we will ignore for the moment. Once you are done, click on OK.

Alpha now builds a new submenu of the Fileset Menu called My fileset with all the files in the folder you selected. Selecting a file in the submenu will open the file in Alpha.
Your fileset can also be used for multi-file searching. In the Find dialog when selecting multi file searching, you can choose to search the files in your fileset.
You can also do multi file search and replace in your fileset, by selecting Filesets Menu ↣ Utilities ↣ Replace In Fileset.

Fileset types

Some fileset types require that you give file patterns specifying which files to include in the fileset. Read the Section File Patterns in the Alpha manual to learn about how to specify file patterns.

From Directory

The basic type: create a fileset of all files in a given folder which match a given pattern. You have to specify:

The folder with the files.
A file pattern matching the files to include.
A list of patterns of files to exclude.

From Hierarchy

Takes the above one step further and allows filesets to include all files in a nested set of folders. You have to specify:

The base folder with the files.
The depth of nested folders.
A file pattern matching the files to include.
A list of patterns of files to exclude.

Recurse In

A simplification of From Hierarchy which includes all files contained in the given base folder and its subfolders recursively. These filesets are meant to be used programmatically. They are not displayed in the Filesets menu. You only need to specify:

The base folder with the files.

From Open Windows

Make a fileset containing all currently open windows.

Tex

Make a fileset of all parts of a multi-part TeX/LaTeX document. Alpha's LaTeX mode understands these and will automatically send your TeX application the base .tex/.ltx file when you select Typeset on any component part. Details about TeX filesets can be found in the LaTeX mode documentation; see the Help ↣ LaTeX Mode Help menu item for more information.

Ftp

Make a fileset of files at a remote machine via ftp. You have to specify:

Host, path (optional), user id, and password
A regular expression (not a file pattern!) matching the files to include.

Procedural

Make a fileset from a Tcl procedure. This type requires that you write a Tcl procedure which returns a list of paths to all files in the fileset. When you create a new procedural fileset Alpha puts an empty procedure (with the correct name!) in your global preferences file. You must then write the body of this procedure. Procedural filesets are completely dynamic and will not appear in the Fileset Menu.

Fileset Menu Cache

Rather than rebuilding the Fileset Menu every time you launch Alpha, the menu building scripts are saved in cache files. This helps speed up launching of Alpha as building the filesets may take a while if there are many of them.
Therefore the fileset submenus may become out of date and you have to rebuild them (indeed, they may become out of date while you are using Alpha, in any case, if you add or remove files from the relevant directories). You can rebuild a single fileset with Fileset Menu ↣ Rebuild A Fileset or rebuild all of them at once with Fileset Menu ↣ Rebuild All Filesets.

Current Fileset

All of the Fileset Menu ↣ Fileset Utilities commands will prompt you to select a fileset on which the operation should be performed. The default value of these dialogs is the internal current fileset. If you turn on the preference named Auto Adjust Fileset the current fileset will be automatically adjusted when you open a file via the Fileset Menu.
See the Fileset Preferences panel.

Filesets Handling Submenus

Manage Filesets

The commands in this menu allow you to manage your collection of filesets.

New Fileset…: Prompts you to select a new fileset type, name, and other information.
Edit Filesets…: Allows you to modify all details of all the filesets you have created. It also allows you to edit additional information which some packages might attach to each fileset (for example, whether to use a version control system for the files, or whether to use a particular tab size setting).
Rename Fileset…: Change a fileset's name
Duplicate Fileset…: Duplicate an existing fileset, so that you can use it as a template and make modifications as desired.
Rebuild A Fileset…: Prompts you to select a fileset to rebuild.
Rebuild All Filesets: Total menu rebuild, including all ftp filesets.
Delete Fileset…: Remove a fileset, permanently if desired.
Rebuild Fileset Menu: This item should rarely be necessary, unless you have changed the sorting order regime. Note that this does not rebuild the filesets, and all previous cached information is still used; rebuilding the menu will generally only change the order in which items appear, and ensure that commands are enabled as appropriate.
Menu Shortcuts…: Different users tend to use filesets in very different ways, so there is no default set of keyboard shortcuts for the "most common" fileset operations. If you wish to create a personalized shortcut for a particular item in the Fileset Utilities or Manage Filesets submenus, then select this item.
Fileset Menu Prefs: Opens the preferences Fileset Preferences panel dialog. Several of these preferences affect how the Fileset Menu is built; after changing one of the Fileset Menu is always rebuilt when necessary. See the Fileset Preferences section below for more information.
Fileset Menu Help: Opens this file.

Fileset Utilities

The items below may not all work for all types of filesets.

Browse Fileset

Opens a browser window containing all fileset items, from which any can be opened. The browser window displays either a Browser view or an Outline view: this can be selected with the Browse Filesets Using preference (in the Filesets panel of the Global Preferences). Double-clicking on an item opens the corresponding file. Here are two snapshots to show the difference:
Fileset Browser View

Close Entire Fileset

Close all windows which belong to a given fileset.

Create Tag File

See the package Tags help for more information.

Fileset To Alpha

Convert all text files in a fileset to Alpha's creator.

Find Tag

See the package Tags help window for more information.

List New Files

Presents a dialog to specify an elapsed time (in days, hours, or minutes) and then displays a window with the list of all the files in the selected fileset that have been modified since this time.

Open Entire Fileset

Open all the windows contained in the fileset for editing.

Open Fileset Folder

Tells the Finder to open the base folder which contains a fileset.

Print Fileset

Print all currently opened files from a given fileset.

Replace In Fileset

Global search and replace in all files. All the windows corresponding to elements that belong to the specified fileset will be closed before performing the search and replace operations. These operations are performed on the files on disk. Use this item with care!

Tar Fileset

Make a compressed tar archive of the fileset. For filesets which are based on a directory hierarchy, you will be given the option of compressing the entire hierarchy (as opposed to just the files listed in the fileset).

Word Count

Count all words (lines, words, chars) in a fileset. The dialog displaying the results has buttons which allow you to write the results in a document window or to copy them to the pasteboard.

Zip Fileset

Make a compressed zip archive of the fileset. For filesets which are based on a directory hierarchy, you will be given the option of compressing the entire hierarchy (as opposed to just the files listed in the fileset).

Show Filesets

The Fileset Menu ↣ Show Fileset submenu allows you to show or hide filesets from the main menu. Filesets that are hidden are still available for all operations that offer you a choice of filesets. Only those filesets that create a hard-wired list of files can be shown. Procedural filesets such as Open Windows or Recurse In Folder can never be shown in the main menu.

Fileset Preferences

The following preferences can be changed at any time by selecting the toggleable items in the Fileset Menu ↣ Utilities ↣ Fileset Flags menu:

Auto Adjust Fileset: Opening a file from the menu will adjust current fileset.
Show Hidden Files In Built In Filesets: Include all hidden files (but not "." and "..") in Top Window's Folder Top Window's Hierarchy or Recurse In filesets.

TeX Filesets

The following items will be added to the utilities menu if you use TeX filesets.

Extract Eps BoxSizes

Search all document parts for included eps graphics, extract bounding box information from the .eps files and insert it explicitly into the document (can lead to much quicker typesetting).

Delete Eps Box Sizes

Remove all the above bounding box information

Hierarchical Bib Files

Bibliography files may \input others, so they should be searched (the default is not to do this, because .bib files may be enormous).
TeX mode also creates a number of its own TeX Filesets preferences.
See the TeX mode preferences.

Additional fileset information

Some packages may attach pieces of data to each fileset. Examples could be the default tab size to use for a fileset (useful if the files use a different value to your own global default), or the type of version control under which the files are registered.
Authors of Tcl extensions to Alpha use the proc [fileset::attachNewInformation] to add such data. It automatically appears in the Edit Filesets dialog. The packages which currently attach such information, and/or provide additional fileset functionality are as follows (list current only at the time of writing):

Recent files multi menu

If you use this more sophisticated version of the recent files menu, you will find a new checkbox Use As Recent Files Group by each fileset in the Edit dialogs. If ticked for a fileset, then recently edited files from that fileset are listed separately in the recent files menu.

Fileset Tab Preference

If activated, you can select a default tab size to use for all files in a given fileset.

Fileset Indentation Preference

Similar to the tab preference, but, if activated, allows you to select tab size, indentation amount, and indent using spaces only settings for any given fileset.

Fileset Encoding Preference

Alphatk and Alpha 8 understand different types of textual encoding in which files may be saved. This feature allows you to specify a default encoding to use for editing files in each fileset.

Fileset Ftp Mirror

If you would like copies of all files in a fileset to be mirrored on a remote ftp site, this feature allows you to attach information about the site (site address, path, username and password) to a fileset, and then provides a new menu item Update Fileset Mirror in the fileset utilities menu which automatically synchronizes the contents of the remote site with any changed documents.

License and Disclaimer

This document has been placed in the public domain.
Original Author: Peter Keleher.
Co-Authors: Vince Darley, Craig Barton Upright, Bernard Desgraupes.
Copyright (c) 1996-2021, the Alpha Community and Contributors.
Contributors: Vince Darley, Craig Barton Upright, Bernard Desgraupes.
All rights reserved.
The Filesets Menu package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Alpha Community nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE ALPHA COMMUNITY OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.