1 \input texinfo.tex @c -*-texinfo-*-
3 @c $Id: common.texi,v 1.1 1999/05/05 19:23:47 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
43 @c --- Info directory entry ---
46 * Common: (common). The Common Files Distribution.
49 @c ----- Introductory stuff and copyright pages -----------------------------
51 @c Yes indeed, by the way: I'm willing to allow a translation approved
52 @c by the FSF, not me. I can't be bothered to vet translations.
54 @c --- Info version ---
58 This file documents version @value{VERSION} of the Common Files Distribution.
60 Copyright (c) 1997 Mark Wooding
62 Permission is granted to make and distribute verbatim copies of this
63 manual provided the copyright notice and this permission notice are
64 preserved on all copies.
67 Permission is granted to process this file through TeX and print the
68 results, provided the printed document carries a copying permission
69 notice identical to this one except for the removal of this paragraph
70 (this paragraph not being relevant to the printed manual).
73 Permission is granted to copy and distribute modified versions of this
74 manual under the conditions for verbatim copying, provided also that the
75 sections entitled `Copying' and `GNU General Public License' are
76 included exactly as in the original, and provided that the entire
77 resulting derived work is distributed under the terms of a permission
78 notice identical to this one.
80 Permission is granted to copy and distribute translations of this manual
81 into another language, under the above conditions for modified versions,
82 except that this permission notice may be stated in a translation
83 approved by the Free Software Foundation.
87 @c --- Printed version ---
90 @title The Common Files Distribution
91 @subtitle version @value{VERSION}
94 @vskip 0pt plus 1 filll
96 Permission is granted to make and distribute verbatim copies of this
97 manual provided the copyright notice and this permission notice are
98 preserved on all copies.
100 Permission is granted to copy and distribute modified versions of this
101 manual under the conditions for verbatim copying, provided also that the
102 sections entitled `Copying' and `GNU General Public License' are
103 included exactly as in the original, and provided that the entire
104 resulting derived work is distributed under the terms of a permission
105 notice identical to this one.
107 Permission is granted to copy and distribute translations of this manual
108 into another language, under the above conditions for modified versions,
109 except that this permission notice may be stated in a translation
110 approved by the Free Software Foundation.
115 @c --------------------------------------------------------------------------
117 @node Top, Copying, (dir), (dir)
118 @unnumbered The Common Files Distribution
121 The Common Files Distribution provides a convenient way to manage files
122 shared between a number of developments.
124 This manual documents version @value{VERSION} of the Common Files
132 * The file repository::
135 --- The Detailed Node Listing ---
139 * The mklinks command::
140 * The findlinks command::
144 * Anatomy:: Structure of a text library.
145 * The txtlib program::
148 @c --------------------------------------------------------------------------
149 @node Copying, Introduction, Top, Top
150 @unnumbered The GNU General Public License
154 @c --------------------------------------------------------------------------
155 @node Introduction, The file repository, Copying, Top
156 @unnumbered Introduction
159 When you have a number of development trees, managing files which are common
160 to all of them starts to become a real pain. When a new version of some file
161 comes out, checking out all your source directories, replacing the old
162 version with the new one, and committing all the changes back gets to be
163 very tiresome rather quickly.
165 The Common File Distribution attempts to be a solution to some of the
166 problems caused sharing files between source trees. It provides a single
167 repository for shared files, and lets you create links to the shared copies
168 from your source trees. It also provides a simple method for constructing
169 text files from small bits of `text libraries'.
171 The whole lot is held together by a collection of small shell scripts. They
172 can easily be modified to suit the requirements of an individual site, or
173 used as the basis of other similar scripts.
176 @c --------------------------------------------------------------------------
177 @node The file repository, Text libraries, Introduction, Top
178 @chapter The file repository
181 When the Common File Distribution is installed, it creates a repository where
182 shared files can be placed, and it places a few standard GNU files there. By
183 default, the repository is @file{@var{prefix}/share/common}, although this
184 can be set using the @code{--datadir} option to the configuration script.
186 You can place your own files in the repository if you like. If you do,
187 they'll be treated in exactly the same way as ones in the distribution.
189 The command @code{mklinks} reads a list of filenames and creates symbolic
190 links to the corresponding names in the repository. This ensures that when a
191 file in the repository gets updated, any source trees automatically use the
192 new version. Obviously, when you build a source distribution, you must
193 ensure that links are followed, rather than saved as links; the @code{h}
194 option to @code{tar} does this (this is the default in Automake; @pxref{Top,
195 , Overview, automake, GNU Automake}).
197 The command @code{findlinks} scans the current directory (and its
198 subdirectories) for files whose names match those in the repository.
201 * The mklinks command::
202 * The findlinks command::
207 @node The mklinks command, The findlinks command, The file repository, The file repository
208 @section The @code{mklinks} command
210 Links into the file repository are made with the @code{mklinks} command:
213 mklinks [@var{file}]...
216 If you don't specify any @code{file}s, it reads @file{.links} from the
217 current directory; you can pass @samp{-} to read standard input. The program
218 expects the files to contain a list of filenames; for each name read, it
219 creates a symbolic link to the appropriate file in the repository.
221 You can create a list of files which probably need linking using the
222 @code{findlinks} command. @xref{The findlinks command}.
226 @node The findlinks command, , The mklinks command, The file repository
227 @section The @code{findlinks} command
229 The @code{findlinks} searches the current directory and any subdirectories
230 and writes to standard output a list of files whose names match files in the
231 file repository. It takes no arguments, although typically output will be
232 redirected to the file @file{.links}, which the @code{mklinks} command reads
240 @c --------------------------------------------------------------------------
241 @node Text libraries, , The file repository, Top
242 @chapter Text libraries
245 Just being able to share files isn't always good enough: it's sometimes
246 useful to able to share small parts of files. The Common Files Distribution
247 comes with a simple system for extracting requested parts from a @dfn{text
252 * Anatomy:: Structure of a text library.
253 * The txtlib program::
258 @node Anatomy, The txtlib program, Text libraries, Text libraries
259 @section Anatomy of a library file
261 Text libraries contain a @dfn{header} followed by a number of @dfn{chunks}.
262 The start of a chunk is marked by a line containing a string of the form
263 @samp{*@@-@var{name}-@@*}; the chunk continues until the start of the next
264 chunk, or the end of the file. The header is simply the text preceding the
267 Here's a simple example of a text library.
272 % Collection of useful macros
277 \newcommand\todo[1]@{%
280 \advance\dimen@@-\tw@@\fboxsep%
281 \advance\dimen@@-\tw@@\fboxrule%
282 \fbox@{\expandafter\parbox\expandafter@{\the\dimen@@@}@{%
283 \begin@{note@}[To do:]%
292 \newindex@{default@}@{idx@}@{ind@}@{Index@}
297 The file contains a short header containing a line to tell Emacs what mode
298 to use when editing it and a brief description of the file. It contains two
299 chunks, named @code{todo} and @code{indexing}
302 @node The txtlib program, , Anatomy, Text libraries
303 @section The @code{txtlib} program
305 The @code{txtlib} program can be used to perform some simple operations on
309 txtlib [-x] [-o @var{file}] @var{library}...
310 txtlib -l @var{library}...
313 By default, or if the @code{-x} option is given, @code{txtlib} extracts
314 chunks from libraries. It reads a list of chunk names from standard input,
315 one per line. It then examines each @var{library} named on the command line,
316 and extracts the requested chunks, writing them to standard output, or to a
317 named file. Note that the chunks are extracted in the order they appear in
318 the libraries, not the order in which their chunk names were listed.
320 If the @code{-l} option is given, @code{txtlib} scans each @var{library} in
321 turn, writing the names of all the chunks it finds to standard output.
326 @c --------------------------------------------------------------------------