Initial revision

[cfd] / common.texi

\input texinfo.tex @c -*-texinfo-*-
@c
@c $Id: common.texi,v 1.1 1999/05/05 19:23:47 mdw Exp $
@c
@c Documentation for `common'
@c
@c (c) 1997 Mark Wooding
@c

@c ----- Licensing notice ---------------------------------------------------
@c
@c This file is part of the Common Files Distribution (`common').
@c
@c `Common' is free software; you can redistribute it and/or modify
@c it under the terms of the GNU General Public License as published by
@c the Free Software Foundation; either version 2 of the License, or
@c (at your option) any later version.
@c
@c `Common' is distributed in the hope that it will be useful,
@c but WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with `common'; if not, write to the Free Software Foundation,
@c Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

@c ----- Standard boilerplate header ----------------------------------------

@c --- Formatting header ---

@c %**start of header
@setfilename common.info
@settitle The Common Files Distribution
@paragraphindent 0
@iftex
@input texinice
@afourpaper
@end iftex
@include version.texi
@c %**end of header

@c --- Info directory entry ---

@direntry
* Common: (common).             The Common Files Distribution.
@end direntry

@c ----- Introductory stuff and copyright pages -----------------------------
@c
@c Yes indeed, by the way: I'm willing to allow a translation approved
@c by the FSF, not me.  I can't be bothered to vet translations.

@c --- Info version ---

@ifinfo

This file documents version @value{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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
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.

@end ifinfo

@c --- Printed version ---

@titlepage
@title The Common Files Distribution
@subtitle version @value{VERSION}
@author Mark Wooding
@page
@vskip 0pt plus 1 filll

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.

@end titlepage


@c --------------------------------------------------------------------------
@ifinfo
@node Top, Copying, (dir), (dir)
@unnumbered 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 @value{VERSION} of the Common Files
Distribution.

@end ifinfo

@menu
* Copying::                     
* Introduction::                
* The file repository::         
* Text libraries::              

 --- The Detailed Node Listing ---

The file repository

* The mklinks command::         
* The findlinks command::       

Text libraries

* Anatomy::                     Structure of a text library.
* The txtlib program::          
@end menu

@c --------------------------------------------------------------------------
@node Copying, Introduction, Top, Top
@unnumbered The GNU General Public License

@include gpl.texi

@c --------------------------------------------------------------------------
@node Introduction, The file repository, Copying, Top
@unnumbered 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.


@c --------------------------------------------------------------------------
@node The file repository, Text libraries, Introduction, Top
@chapter 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 @file{@var{prefix}/share/common}, although this
can be set using the @code{--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 @code{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 @code{h}
option to @code{tar} does this (this is the default in Automake; @pxref{Top,
, Overview, automake, GNU Automake}).

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

@menu
* The mklinks command::         
* The findlinks command::       
@end menu



@node The mklinks command, The findlinks command, The file repository, The file repository
@section The @code{mklinks} command

Links into the file repository are made with the @code{mklinks} command:

@example
mklinks [@var{file}]...
@end example

If you don't specify any @code{file}s, it reads @file{.links} from the
current directory; you can pass @samp{-} 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
@code{findlinks} command.  @xref{The findlinks command}.



@node The findlinks command,  , The mklinks command, The file repository
@section The @code{findlinks} command

The @code{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 @file{.links}, which the @code{mklinks} command reads
by default:

@example
findlinks >.links
@end example


@c --------------------------------------------------------------------------
@node Text libraries,  , The file repository, Top
@chapter 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 @dfn{text
library}.


@menu
* Anatomy::                     Structure of a text library.
* The txtlib program::          
@end menu



@node Anatomy, The txtlib program, Text libraries, Text libraries
@section Anatomy of a library file

Text libraries contain a @dfn{header} followed by a number of @dfn{chunks}.
The start of a chunk is marked by a line containing a string of the form
@samp{*@@-@var{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.

@example
% -*-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*@}
@end example

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 @code{todo} and @code{indexing}


@node The txtlib program,  , Anatomy, Text libraries
@section The @code{txtlib} program

The @code{txtlib} program can be used to perform some simple operations on
text libraries:

@example
txtlib [-x] [-o @var{file}] @var{library}...
txtlib -l @var{library}...
@end example

By default, or if the @code{-x} option is given, @code{txtlib} extracts
chunks from libraries.  It reads a list of chunk names from standard input,
one per line.  It then examines each @var{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 @code{-l} option is given, @code{txtlib} scans each @var{library} in
turn, writing the names of all the chunks it finds to standard output.




@c --------------------------------------------------------------------------

@contents
@bye