Document Projects Help

Name:	Document Projects
Version:	2.1
Last update:	2019-11-27 14:12:52

Introduction
Activation
Quick Start
New Document Windows
Projects
File Headers
Templates
Preferences
Additional Menu Items
Known problems
License and Disclaimer

This help file describes the AlphaTcl package Document Projects, a feature that aims to simplify the creation of new documents with shared templates. One can define multiple projects, as well as an unlimited number of project templates. This package complements others in the AlphaTcl library.

Introduction

The Document Projects package lets you define different kinds of projects. The projects allow you to have separate templates for different things on which you work, and to associate different projects with specific AlphaTcl modes: see the Projects section.
Document Templates save you the labour of typing in the same sort of basic information for every file you create, and to give your files a standard look. Document headers can also contain modification and creating dates, version numbering, etc., all of which may be updated very easily: see the Templates section.
Before you read any further, you should confirm that you have properly defined some identity fields for Alpha. The package Identities can be accessed via the Alpha ↣ Preferences ↣ Identities menu. Information from your Current Identity settings are used by this feature to create many of its templates.

Activation

In order to make use of this package, you must first turn it on via the Features Preferences dialog.
When this package is active, a new submenu called Document Projects is inserted in the Preferences submenu of the application menu (Alpha ↣ Preferences ↣ Document Projects). Two new commands are also inserted in the Window Utilities submenu (Tools ↣ Window Utilities): Update Date and Update File Version.
The items in the submenu let you only create and parameterize a new kind of project and new kinds of templates. In order to make use of this new kind of project, you must activate the New Document package as explained below.

Quick Start

Follow these steps to see Document Projects in action. The major concepts are explained in further detail below. You should be able to complete this process without changing any settings beyond those specified below.

Select Alpha ↣ Preferences ↣ Identities ↣ Edit Identity to enter personal information to be included in file headers (or click here).
Select Alpha ↣ Global Setup ↣ Features to activate the package Document Projects. See the Features Preferences dialog.
Select Alpha ↣ Preferences ↣ Document Projects ↣ New Project to define a new project (or click here).
Select Alpha ↣ Global Setup ↣ Features to activate the package New Document. See the Features Preferences dialog.
Change your New Document's New Document Handler preference setting to Document Projects. See the New Document Preferences panel to do so. This step is crucial. If you omit to set the handler, your document projects will be ignored.
Create a new document window via File ↣ New ↣ New Text Window (or click here) using some window name that includes a mode-specific file extension, such as test.tex or test.h.
This final step should create a window with a standardized header including information from your Current Identity and about the Current Project.

New Document Windows

This feature allows you to easily insert document templates into new windows, templates that are specific to your Current Identity, the Current Project, and the type of file that you are creating. The template can include not only a standardized file header (see File Headers), but also a basic TeX document, a web page, a C++ source file, etc.
Assuming that you have already activated this package, there are just two more steps to take advantage of new document window functionality.

Select Alpha ↣ Global Setup ↣ Features to activate the package New Document. See the Features Preferences dialog.
Change your New Document's New Document Handler preference setting to Document Projects. See the New Document Preferences panel.

Once these settings have been changed, the File ↣ New ↣ New Text Window command will prompt you to specify Project and Template information.

Projects

One of the core concepts introduced by this feature is the Document Project. A Project simply defines some field values that are used to create new documents. You might have one Project defined for a web site, another for your thesis, and a third for programming your favorite open-source software.
Each project has the following components:

Short Descriptive Name
Longer Descriptive Name
License Type
License Owner
License Organisation
Additional Text for File Headers
Associated AlphaTcl Modes

Use the Alpha ↣ Preferences ↣ Document Projects ↣ New Project menu item to set these fields for a new Project. The dialog looks like this: click here. All but the last item (associated modes) are used to create File Headers. The License can be one of any pre-set types, and you can modify these templates or add new ones. See the package License Templates Help for more information. The License Owner/Organisation fields are used when creating the license templates.
The list of modes is used to verify that the Current Project should be used when a new document is actually created. If the new document is to be opened in a mode that is _not_ associated with the Current Project, you will be asked if you want to switch projects.

File Headers

A file header is just a commented block of code inserted at the top of the new window. Click here to see the basic format. If you adjust settings for your identity or the current project, the content of the header will change.
File headers will be included in all new document windows created so long as

Document Projects remains your New Document Handler, and
the chosen template is not Empty.

If you are working with a document created without a header and you want to add one, activate the package Electric Menu Help and select the Electric Menu ↣ Templates ↣ Create Header menu command. See the Menus Preferences dialog.
Note that the style of the file header will vary slightly depending on whether the active window is a source or header file. (Sorry for any confusion here with the use of the term header, it can't be avoided.) This feature will do its best to figure that out based on the file name, and on the File Type defined for the Templates that you use.

Templates

For each of your different projects and modes you might probably want a standard document template, perhaps with some code/text already filled in or inserted as template prompts.
This package defines several default templates for you that you might find useful. Each template has several settings that you can adjust; see the Alpha ↣ Preferences ↣ Document Projects ↣ Edit Template command for the standard dialog (or click here).
The settings include:

Descriptive Name
Associated Modes
Procedure Name
File Type
Project
Sub-types Handled by the Procedure

The Procedure in an AlphaTcl proc that is called whenever the template is inserted into the active window. If there are several different sub-types available, these will be offered to you when you select the template, and then the name of the chosen sub-type will be passed along to the procedure as an argument.
When you create a new template, if you specify a Procedure name you will be prompted to add that to one of your prefs.tcl files.
Template procedures can be arbitrarily complex, and while they do require a little knowledge of Tcl (and AlphaTcl) to create you can start small and build them as you become more familiar with the syntax. Some examples of pre-defined templates that you could use as models include

     t_default
     t_latex
     t_package

It is not necessary, by the way, to name your procedures with a leading t_, but this might be an easy way for you to remember what these are for!

Preferences

Using the Alpha ↣ Preferences ↣ Document Projects ↣ Document Project Prefs menu item, you can set the following:

Auto Update Copyright Year

Would you like to auto-update the copyright year in the header of a file whenever it is saved?

Auto Update Header

Would you like to auto-update the time-stamp in the header of a file whenever it is saved?

Confirm Project Mode

If the mode of the active window doesn't match the Current Project, would you like to be warned?

Doc Templates Mode Specific

Would you like to only be offered mode-specific document template options in when new document windows are created? (This is useful if you have a lot of templates defined.)

Include Header Description

Do you want a Description: field in your file headers? The initial document creation dialog will allow you to enter some text for this description, which you can of course modify later.

Header Divider Character

You can set the character you want used for the divider. Do you want the header divider strings to look like one of the following ?

	========================================
	----------------------------------------
	########################################

Update File Version

The Tools ↣ Window Utilities ↣ Update File Version keyboard shortcut.

Click here to display the Document Projects Preferences panel.

Additional Menu Items

In addition to the package New Document, Document Projects interacts with other AlphaTcl features and menus.

A new Tools ↣ Window Utilities ↣ Update File Version command will add a new entry if your header was created with a History section.
The Electric Menu ↣ Templates menu will include some mode-specific commands, including Create Header and New Document. See the Electric Menu Help for more information about different template options.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 1997-2019, Vince Darley and Contributors.
Contributors: Craig Barton Upright.
All rights reserved.
The Document Projects 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 Vince Darley 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 VINCE DARLEY 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.
This documentation file has been placed in the public domain.