b91e2391 |
1 | \input texinfo.tex @c -*-texinfo-*- |
2 | @c |
b91e2391 |
3 | @c Documentation for `common' |
4 | @c |
5 | @c (c) 1997 Mark Wooding |
6 | @c |
7 | |
8 | @c ----- Licensing notice --------------------------------------------------- |
9 | @c |
10 | @c This file is part of the Common Files Distribution (`common'). |
11 | @c |
12 | @c `Common' is free software; you can redistribute it and/or modify |
13 | @c it under the terms of the GNU General Public License as published by |
14 | @c the Free Software Foundation; either version 2 of the License, or |
15 | @c (at your option) any later version. |
16 | @c |
17 | @c `Common' is distributed in the hope that it will be useful, |
18 | @c but WITHOUT ANY WARRANTY; without even the implied warranty of |
19 | @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
20 | @c GNU General Public License for more details. |
21 | @c |
22 | @c You should have received a copy of the GNU General Public License |
23 | @c along with `common'; if not, write to the Free Software Foundation, |
24 | @c Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
25 | |
26 | @c ----- Standard boilerplate header ---------------------------------------- |
27 | |
28 | @c --- Formatting header --- |
29 | |
30 | @c %**start of header |
31 | @setfilename common.info |
32 | @settitle The Common Files Distribution |
33 | @paragraphindent 0 |
68bd460a |
34 | @dircategory Development |
35 | @direntry |
36 | * Common Files Distribution: (common). A central place for boilerplate |
37 | @end direntry |
b91e2391 |
38 | @iftex |
39 | @input texinice |
40 | @afourpaper |
41 | @end iftex |
42 | @include version.texi |
43 | @c %**end of header |
44 | |
b91e2391 |
45 | @c ----- Introductory stuff and copyright pages ----------------------------- |
46 | @c |
47 | @c Yes indeed, by the way: I'm willing to allow a translation approved |
48 | @c by the FSF, not me. I can't be bothered to vet translations. |
49 | |
50 | @c --- Info version --- |
51 | |
52 | @ifinfo |
53 | |
54 | This file documents version @value{VERSION} of the Common Files Distribution. |
55 | |
56 | Copyright (c) 1997 Mark Wooding |
57 | |
58 | Permission is granted to make and distribute verbatim copies of this |
59 | manual provided the copyright notice and this permission notice are |
60 | preserved on all copies. |
61 | |
62 | @ignore |
63 | Permission is granted to process this file through TeX and print the |
64 | results, provided the printed document carries a copying permission |
65 | notice identical to this one except for the removal of this paragraph |
66 | (this paragraph not being relevant to the printed manual). |
67 | |
68 | @end ignore |
69 | Permission is granted to copy and distribute modified versions of this |
70 | manual under the conditions for verbatim copying, provided also that the |
71 | sections entitled `Copying' and `GNU General Public License' are |
72 | included exactly as in the original, and provided that the entire |
73 | resulting derived work is distributed under the terms of a permission |
74 | notice identical to this one. |
75 | |
76 | Permission is granted to copy and distribute translations of this manual |
77 | into another language, under the above conditions for modified versions, |
78 | except that this permission notice may be stated in a translation |
79 | approved by the Free Software Foundation. |
80 | |
81 | @end ifinfo |
82 | |
83 | @c --- Printed version --- |
84 | |
85 | @titlepage |
86 | @title The Common Files Distribution |
87 | @subtitle version @value{VERSION} |
88 | @author Mark Wooding |
89 | @page |
90 | @vskip 0pt plus 1 filll |
91 | |
92 | Permission is granted to make and distribute verbatim copies of this |
93 | manual provided the copyright notice and this permission notice are |
94 | preserved on all copies. |
95 | |
96 | Permission is granted to copy and distribute modified versions of this |
97 | manual under the conditions for verbatim copying, provided also that the |
98 | sections entitled `Copying' and `GNU General Public License' are |
99 | included exactly as in the original, and provided that the entire |
100 | resulting derived work is distributed under the terms of a permission |
101 | notice identical to this one. |
102 | |
103 | Permission is granted to copy and distribute translations of this manual |
104 | into another language, under the above conditions for modified versions, |
105 | except that this permission notice may be stated in a translation |
106 | approved by the Free Software Foundation. |
107 | |
108 | @end titlepage |
109 | |
110 | |
111 | @c -------------------------------------------------------------------------- |
112 | @ifinfo |
113 | @node Top, Copying, (dir), (dir) |
114 | @unnumbered The Common Files Distribution |
115 | |
116 | |
117 | The Common Files Distribution provides a convenient way to manage files |
118 | shared between a number of developments. |
119 | |
120 | This manual documents version @value{VERSION} of the Common Files |
121 | Distribution. |
122 | |
123 | @end ifinfo |
124 | |
125 | @menu |
126 | * Copying:: |
127 | * Introduction:: |
128 | * The file repository:: |
b91e2391 |
129 | |
1f79a056 |
130 | @detailmenu |
b91e2391 |
131 | --- The Detailed Node Listing --- |
132 | |
133 | The file repository |
134 | |
135 | * The mklinks command:: |
136 | * The findlinks command:: |
137 | |
1f79a056 |
138 | @end detailmenu |
b91e2391 |
139 | @end menu |
140 | |
141 | @c -------------------------------------------------------------------------- |
142 | @node Copying, Introduction, Top, Top |
143 | @unnumbered The GNU General Public License |
144 | |
145 | @include gpl.texi |
146 | |
147 | @c -------------------------------------------------------------------------- |
148 | @node Introduction, The file repository, Copying, Top |
149 | @unnumbered Introduction |
150 | |
151 | |
152 | When you have a number of development trees, managing files which are common |
153 | to all of them starts to become a real pain. When a new version of some file |
154 | comes out, checking out all your source directories, replacing the old |
155 | version with the new one, and committing all the changes back gets to be |
156 | very tiresome rather quickly. |
157 | |
158 | The Common File Distribution attempts to be a solution to some of the |
159 | problems caused sharing files between source trees. It provides a single |
160 | repository for shared files, and lets you create links to the shared copies |
161 | from your source trees. It also provides a simple method for constructing |
162 | text files from small bits of `text libraries'. |
163 | |
164 | The whole lot is held together by a collection of small shell scripts. They |
165 | can easily be modified to suit the requirements of an individual site, or |
166 | used as the basis of other similar scripts. |
167 | |
168 | |
169 | @c -------------------------------------------------------------------------- |
1f79a056 |
170 | @node The file repository, , Introduction, Top |
b91e2391 |
171 | @chapter The file repository |
172 | |
173 | |
174 | When the Common File Distribution is installed, it creates a repository where |
175 | shared files can be placed, and it places a few standard GNU files there. By |
176 | default, the repository is @file{@var{prefix}/share/common}, although this |
177 | can be set using the @code{--datadir} option to the configuration script. |
178 | |
179 | You can place your own files in the repository if you like. If you do, |
180 | they'll be treated in exactly the same way as ones in the distribution. |
181 | |
182 | The command @code{mklinks} reads a list of filenames and creates symbolic |
183 | links to the corresponding names in the repository. This ensures that when a |
184 | file in the repository gets updated, any source trees automatically use the |
185 | new version. Obviously, when you build a source distribution, you must |
186 | ensure that links are followed, rather than saved as links; the @code{h} |
187 | option to @code{tar} does this (this is the default in Automake; @pxref{Top, |
188 | , Overview, automake, GNU Automake}). |
189 | |
190 | The command @code{findlinks} scans the current directory (and its |
191 | subdirectories) for files whose names match those in the repository. |
192 | |
193 | @menu |
194 | * The mklinks command:: |
195 | * The findlinks command:: |
196 | @end menu |
197 | |
198 | |
199 | |
200 | @node The mklinks command, The findlinks command, The file repository, The file repository |
201 | @section The @code{mklinks} command |
202 | |
203 | Links into the file repository are made with the @code{mklinks} command: |
204 | |
205 | @example |
206 | mklinks [@var{file}]... |
207 | @end example |
208 | |
209 | If you don't specify any @code{file}s, it reads @file{.links} from the |
210 | current directory; you can pass @samp{-} to read standard input. The program |
211 | expects the files to contain a list of filenames; for each name read, it |
212 | creates a symbolic link to the appropriate file in the repository. |
213 | |
214 | You can create a list of files which probably need linking using the |
215 | @code{findlinks} command. @xref{The findlinks command}. |
216 | |
217 | |
218 | |
219 | @node The findlinks command, , The mklinks command, The file repository |
220 | @section The @code{findlinks} command |
221 | |
222 | The @code{findlinks} searches the current directory and any subdirectories |
223 | and writes to standard output a list of files whose names match files in the |
224 | file repository. It takes no arguments, although typically output will be |
225 | redirected to the file @file{.links}, which the @code{mklinks} command reads |
226 | by default: |
227 | |
228 | @example |
229 | findlinks >.links |
230 | @end example |
231 | |
b91e2391 |
232 | @c -------------------------------------------------------------------------- |
233 | |
234 | @contents |
235 | @bye |