     [file version.texi not included]

This file documents version VERSION of the Common Files Distribution.

Copyright (c) 1997 Mark Wooding

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled `Copying' and `GNU General Public License' are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.

The Common Files Distribution
*****************************

The Common Files Distribution provides a convenient way to manage files shared between a number of developments.

This manual documents version VERSION of the Common Files Distribution.

The GNU General Public License
******************************

     [file gpl.texi not included]

Introduction
************

When you have a number of development trees, managing files which are common to all of them starts to become a real pain.  When a new version of some file comes out, checking out all your source directories, replacing the old version with the new one, and committing all the changes back gets to be very tiresome rather quickly.

The Common File Distribution attempts to be a solution to some of the problems caused sharing files between source trees.  It provides a single repository for shared files, and lets you create links to the shared copies from your source trees.  It also provides a simple method for constructing text files from small bits of `text libraries'.

The whole lot is held together by a collection of small shell scripts.  They can easily be modified to suit the requirements of an individual site, or used as the basis of other similar scripts.

The file repository
*******************

When the Common File Distribution is installed, it creates a repository where shared files can be placed, and it places a few standard GNU files there.  By default, the repository is PREFIX/share/common, although this can be set using the --datadir option to the configuration script.

You can place your own files in the repository if you like.  If you do, they'll be treated in exactly the same way as ones in the distribution.

The command mklinks reads a list of filenames and creates symbolic links to the corresponding names in the repository.  This ensures that when a file in the repository gets updated, any source trees automatically use the new version.  Obviously, when you build a source distribution, you must ensure that links are followed, rather than saved as links; the h option to tar does this (this is the default in Automake; see Overview (GNU Automake)).

The command findlinks scans the current directory (and its subdirectories) for files whose names match those in the repository.

The mklinks command
===================

Links into the file repository are made with the mklinks command:

     mklinks [FILE]...

If you don't specify any files, it reads .links from the current directory; you can pass - to read standard input.  The program expects the files to contain a list of filenames; for each name read, it creates a symbolic link to the appropriate file in the repository.

You can create a list of files which probably need linking using the findlinks command.  See The findlinks command.

The findlinks command
=====================

The findlinks searches the current directory and any subdirectories and writes to standard output a list of files whose names match files in the file repository.  It takes no arguments, although typically output will be redirected to the file .links, which the mklinks command reads by default:

     findlinks >.links

Text libraries
**************

Just being able to share files isn't always good enough: it's sometimes useful to able to share small parts of files.  The Common Files Distribution comes with a simple system for extracting requested parts from a text library.

Anatomy of a library file
=========================

Text libraries contain a header followed by a number of chunks. The start of a chunk is marked by a line containing a string of the form *@-NAME-@*; the chunk continues until the start of the next chunk, or the end of the file.  The header is simply the text preceding the first chunk.

Here's a simple example of a text library.

     % -*-tex-*-
     %
     % Collection of useful macros
     %

     % *@-todo-@*

     \newcommand\todo[1]{%
       \par%
       \dimen@\linewidth%
       \advance\dimen@-\tw@\fboxsep%
       \advance\dimen@-\tw@\fboxrule%
       \fbox{\expandafter\parbox\expandafter{\the\dimen@}{%
         \begin{note}[To do:]%
         #1%
         \end{note}%
       }}%
       \par%
     }

     % *@-indexing-@*

     \newindex{default}{idx}{ind}{Index}
     \atdef^{\index}
     \atdef_{\index*}

The file contains a short header containing a line to tell Emacs what mode to use when editing it and a brief description of the file.  It contains two chunks, named todo and indexing

The txtlib program
==================

The txtlib program can be used to perform some simple operations on text libraries:

     txtlib [-x] [-o FILE] LIBRARY...
     txtlib -l LIBRARY...

By default, or if the -x option is given, txtlib extracts chunks from libraries.  It reads a list of chunk names from standard input, one per line.  It then examines each LIBRARY named on the command line, and extracts the requested chunks, writing them to standard output, or to a named file.  Note that the chunks are extracted in the order they appear in the libraries, not the order in which their chunk names were listed.

If the -l option is given, txtlib scans each LIBRARY in turn, writing the names of all the chunks it finds to standard output.