1 \input texinfo.tex @c -*-texinfo-*-
3 @c $Id: common.texi,v 1.2 2003/11/09 16:12:11 mdw Exp $
5 @c Documentation for `common'
7 @c (c) 1997 Mark Wooding
10 @c ----- Licensing notice ---------------------------------------------------
12 @c This file is part of the Common Files Distribution (`common').
14 @c `Common' is free software; you can redistribute it and/or modify
15 @c it under the terms of the GNU General Public License as published by
16 @c the Free Software Foundation; either version 2 of the License, or
17 @c (at your option) any later version.
19 @c `Common' is distributed in the hope that it will be useful,
20 @c but WITHOUT ANY WARRANTY; without even the implied warranty of
21 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 @c GNU General Public License for more details.
24 @c You should have received a copy of the GNU General Public License
25 @c along with `common'; if not, write to the Free Software Foundation,
26 @c Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
28 @c ----- Standard boilerplate header ----------------------------------------
30 @c --- Formatting header ---
33 @setfilename common.info
34 @settitle The Common Files Distribution
36 @dircategory Development
38 * Common Files Distribution: (common). A central place for boilerplate
47 @c ----- Introductory stuff and copyright pages -----------------------------
49 @c Yes indeed, by the way: I'm willing to allow a translation approved
50 @c by the FSF, not me. I can't be bothered to vet translations.
52 @c --- Info version ---
56 This file documents version @value{VERSION} of the Common Files Distribution.
58 Copyright (c) 1997 Mark Wooding
60 Permission is granted to make and distribute verbatim copies of this
61 manual provided the copyright notice and this permission notice are
62 preserved on all copies.
65 Permission is granted to process this file through TeX and print the
66 results, provided the printed document carries a copying permission
67 notice identical to this one except for the removal of this paragraph
68 (this paragraph not being relevant to the printed manual).
71 Permission is granted to copy and distribute modified versions of this
72 manual under the conditions for verbatim copying, provided also that the
73 sections entitled `Copying' and `GNU General Public License' are
74 included exactly as in the original, and provided that the entire
75 resulting derived work is distributed under the terms of a permission
76 notice identical to this one.
78 Permission is granted to copy and distribute translations of this manual
79 into another language, under the above conditions for modified versions,
80 except that this permission notice may be stated in a translation
81 approved by the Free Software Foundation.
85 @c --- Printed version ---
88 @title The Common Files Distribution
89 @subtitle version @value{VERSION}
92 @vskip 0pt plus 1 filll
94 Permission is granted to make and distribute verbatim copies of this
95 manual provided the copyright notice and this permission notice are
96 preserved on all copies.
98 Permission is granted to copy and distribute modified versions of this
99 manual under the conditions for verbatim copying, provided also that the
100 sections entitled `Copying' and `GNU General Public License' are
101 included exactly as in the original, and provided that the entire
102 resulting derived work is distributed under the terms of a permission
103 notice identical to this one.
105 Permission is granted to copy and distribute translations of this manual
106 into another language, under the above conditions for modified versions,
107 except that this permission notice may be stated in a translation
108 approved by the Free Software Foundation.
113 @c --------------------------------------------------------------------------
115 @node Top, Copying, (dir), (dir)
116 @unnumbered The Common Files Distribution
119 The Common Files Distribution provides a convenient way to manage files
120 shared between a number of developments.
122 This manual documents version @value{VERSION} of the Common Files
130 * The file repository::
133 --- The Detailed Node Listing ---
137 * The mklinks command::
138 * The findlinks command::
142 * Anatomy:: Structure of a text library.
143 * The txtlib program::
146 @c --------------------------------------------------------------------------
147 @node Copying, Introduction, Top, Top
148 @unnumbered The GNU General Public License
152 @c --------------------------------------------------------------------------
153 @node Introduction, The file repository, Copying, Top
154 @unnumbered Introduction
157 When you have a number of development trees, managing files which are common
158 to all of them starts to become a real pain. When a new version of some file
159 comes out, checking out all your source directories, replacing the old
160 version with the new one, and committing all the changes back gets to be
161 very tiresome rather quickly.
163 The Common File Distribution attempts to be a solution to some of the
164 problems caused sharing files between source trees. It provides a single
165 repository for shared files, and lets you create links to the shared copies
166 from your source trees. It also provides a simple method for constructing
167 text files from small bits of `text libraries'.
169 The whole lot is held together by a collection of small shell scripts. They
170 can easily be modified to suit the requirements of an individual site, or
171 used as the basis of other similar scripts.
174 @c --------------------------------------------------------------------------
175 @node The file repository, Text libraries, Introduction, Top
176 @chapter The file repository
179 When the Common File Distribution is installed, it creates a repository where
180 shared files can be placed, and it places a few standard GNU files there. By
181 default, the repository is @file{@var{prefix}/share/common}, although this
182 can be set using the @code{--datadir} option to the configuration script.
184 You can place your own files in the repository if you like. If you do,
185 they'll be treated in exactly the same way as ones in the distribution.
187 The command @code{mklinks} reads a list of filenames and creates symbolic
188 links to the corresponding names in the repository. This ensures that when a
189 file in the repository gets updated, any source trees automatically use the
190 new version. Obviously, when you build a source distribution, you must
191 ensure that links are followed, rather than saved as links; the @code{h}
192 option to @code{tar} does this (this is the default in Automake; @pxref{Top,
193 , Overview, automake, GNU Automake}).
195 The command @code{findlinks} scans the current directory (and its
196 subdirectories) for files whose names match those in the repository.
199 * The mklinks command::
200 * The findlinks command::
205 @node The mklinks command, The findlinks command, The file repository, The file repository
206 @section The @code{mklinks} command
208 Links into the file repository are made with the @code{mklinks} command:
211 mklinks [@var{file}]...
214 If you don't specify any @code{file}s, it reads @file{.links} from the
215 current directory; you can pass @samp{-} to read standard input. The program
216 expects the files to contain a list of filenames; for each name read, it
217 creates a symbolic link to the appropriate file in the repository.
219 You can create a list of files which probably need linking using the
220 @code{findlinks} command. @xref{The findlinks command}.
224 @node The findlinks command, , The mklinks command, The file repository
225 @section The @code{findlinks} command
227 The @code{findlinks} searches the current directory and any subdirectories
228 and writes to standard output a list of files whose names match files in the
229 file repository. It takes no arguments, although typically output will be
230 redirected to the file @file{.links}, which the @code{mklinks} command reads
238 @c --------------------------------------------------------------------------
239 @node Text libraries, , The file repository, Top
240 @chapter Text libraries
243 Just being able to share files isn't always good enough: it's sometimes
244 useful to able to share small parts of files. The Common Files Distribution
245 comes with a simple system for extracting requested parts from a @dfn{text
250 * Anatomy:: Structure of a text library.
251 * The txtlib program::
256 @node Anatomy, The txtlib program, Text libraries, Text libraries
257 @section Anatomy of a library file
259 Text libraries contain a @dfn{header} followed by a number of @dfn{chunks}.
260 The start of a chunk is marked by a line containing a string of the form
261 @samp{*@@-@var{name}-@@*}; the chunk continues until the start of the next
262 chunk, or the end of the file. The header is simply the text preceding the
265 Here's a simple example of a text library.
270 % Collection of useful macros
275 \newcommand\todo[1]@{%
278 \advance\dimen@@-\tw@@\fboxsep%
279 \advance\dimen@@-\tw@@\fboxrule%
280 \fbox@{\expandafter\parbox\expandafter@{\the\dimen@@@}@{%
281 \begin@{note@}[To do:]%
290 \newindex@{default@}@{idx@}@{ind@}@{Index@}
295 The file contains a short header containing a line to tell Emacs what mode
296 to use when editing it and a brief description of the file. It contains two
297 chunks, named @code{todo} and @code{indexing}
300 @node The txtlib program, , Anatomy, Text libraries
301 @section The @code{txtlib} program
303 The @code{txtlib} program can be used to perform some simple operations on
307 txtlib [-x] [-o @var{file}] @var{library}...
308 txtlib -l @var{library}...
311 By default, or if the @code{-x} option is given, @code{txtlib} extracts
312 chunks from libraries. It reads a list of chunk names from standard input,
313 one per line. It then examines each @var{library} named on the command line,
314 and extracts the requested chunks, writing them to standard output, or to a
315 named file. Note that the chunks are extracted in the order they appear in
316 the libraries, not the order in which their chunk names were listed.
318 If the @code{-l} option is given, @code{txtlib} scans each @var{library} in
319 turn, writing the names of all the chunks it finds to standard output.
324 @c --------------------------------------------------------------------------