b91e2391 |
1 | \input texinfo.tex @c -*-texinfo-*- |
2 | @c |
68bd460a |
3 | @c $Id: common.texi,v 1.2 2003/11/09 16:12:11 mdw Exp $ |
b91e2391 |
4 | @c |
5 | @c Documentation for `common' |
6 | @c |
7 | @c (c) 1997 Mark Wooding |
8 | @c |
9 | |
10 | @c ----- Licensing notice --------------------------------------------------- |
11 | @c |
12 | @c This file is part of the Common Files Distribution (`common'). |
13 | @c |
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. |
18 | @c |
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. |
23 | @c |
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. |
27 | |
28 | @c ----- Standard boilerplate header ---------------------------------------- |
29 | |
30 | @c --- Formatting header --- |
31 | |
32 | @c %**start of header |
33 | @setfilename common.info |
34 | @settitle The Common Files Distribution |
35 | @paragraphindent 0 |
68bd460a |
36 | @dircategory Development |
37 | @direntry |
38 | * Common Files Distribution: (common). A central place for boilerplate |
39 | @end direntry |
b91e2391 |
40 | @iftex |
41 | @input texinice |
42 | @afourpaper |
43 | @end iftex |
44 | @include version.texi |
45 | @c %**end of header |
46 | |
b91e2391 |
47 | @c ----- Introductory stuff and copyright pages ----------------------------- |
48 | @c |
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. |
51 | |
52 | @c --- Info version --- |
53 | |
54 | @ifinfo |
55 | |
56 | This file documents version @value{VERSION} of the Common Files Distribution. |
57 | |
58 | Copyright (c) 1997 Mark Wooding |
59 | |
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. |
63 | |
64 | @ignore |
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). |
69 | |
70 | @end ignore |
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. |
77 | |
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. |
82 | |
83 | @end ifinfo |
84 | |
85 | @c --- Printed version --- |
86 | |
87 | @titlepage |
88 | @title The Common Files Distribution |
89 | @subtitle version @value{VERSION} |
90 | @author Mark Wooding |
91 | @page |
92 | @vskip 0pt plus 1 filll |
93 | |
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. |
97 | |
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. |
104 | |
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. |
109 | |
110 | @end titlepage |
111 | |
112 | |
113 | @c -------------------------------------------------------------------------- |
114 | @ifinfo |
115 | @node Top, Copying, (dir), (dir) |
116 | @unnumbered The Common Files Distribution |
117 | |
118 | |
119 | The Common Files Distribution provides a convenient way to manage files |
120 | shared between a number of developments. |
121 | |
122 | This manual documents version @value{VERSION} of the Common Files |
123 | Distribution. |
124 | |
125 | @end ifinfo |
126 | |
127 | @menu |
128 | * Copying:: |
129 | * Introduction:: |
130 | * The file repository:: |
131 | * Text libraries:: |
132 | |
133 | --- The Detailed Node Listing --- |
134 | |
135 | The file repository |
136 | |
137 | * The mklinks command:: |
138 | * The findlinks command:: |
139 | |
140 | Text libraries |
141 | |
142 | * Anatomy:: Structure of a text library. |
143 | * The txtlib program:: |
144 | @end menu |
145 | |
146 | @c -------------------------------------------------------------------------- |
147 | @node Copying, Introduction, Top, Top |
148 | @unnumbered The GNU General Public License |
149 | |
150 | @include gpl.texi |
151 | |
152 | @c -------------------------------------------------------------------------- |
153 | @node Introduction, The file repository, Copying, Top |
154 | @unnumbered Introduction |
155 | |
156 | |
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. |
162 | |
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'. |
168 | |
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. |
172 | |
173 | |
174 | @c -------------------------------------------------------------------------- |
175 | @node The file repository, Text libraries, Introduction, Top |
176 | @chapter The file repository |
177 | |
178 | |
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. |
183 | |
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. |
186 | |
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}). |
194 | |
195 | The command @code{findlinks} scans the current directory (and its |
196 | subdirectories) for files whose names match those in the repository. |
197 | |
198 | @menu |
199 | * The mklinks command:: |
200 | * The findlinks command:: |
201 | @end menu |
202 | |
203 | |
204 | |
205 | @node The mklinks command, The findlinks command, The file repository, The file repository |
206 | @section The @code{mklinks} command |
207 | |
208 | Links into the file repository are made with the @code{mklinks} command: |
209 | |
210 | @example |
211 | mklinks [@var{file}]... |
212 | @end example |
213 | |
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. |
218 | |
219 | You can create a list of files which probably need linking using the |
220 | @code{findlinks} command. @xref{The findlinks command}. |
221 | |
222 | |
223 | |
224 | @node The findlinks command, , The mklinks command, The file repository |
225 | @section The @code{findlinks} command |
226 | |
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 |
231 | by default: |
232 | |
233 | @example |
234 | findlinks >.links |
235 | @end example |
236 | |
237 | |
238 | @c -------------------------------------------------------------------------- |
239 | @node Text libraries, , The file repository, Top |
240 | @chapter Text libraries |
241 | |
242 | |
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 |
246 | library}. |
247 | |
248 | |
249 | @menu |
250 | * Anatomy:: Structure of a text library. |
251 | * The txtlib program:: |
252 | @end menu |
253 | |
254 | |
255 | |
256 | @node Anatomy, The txtlib program, Text libraries, Text libraries |
257 | @section Anatomy of a library file |
258 | |
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 |
263 | first chunk. |
264 | |
265 | Here's a simple example of a text library. |
266 | |
267 | @example |
268 | % -*-tex-*- |
269 | % |
270 | % Collection of useful macros |
271 | % |
272 | |
273 | % *@@-todo-@@* |
274 | |
275 | \newcommand\todo[1]@{% |
276 | \par% |
277 | \dimen@@\linewidth% |
278 | \advance\dimen@@-\tw@@\fboxsep% |
279 | \advance\dimen@@-\tw@@\fboxrule% |
280 | \fbox@{\expandafter\parbox\expandafter@{\the\dimen@@@}@{% |
281 | \begin@{note@}[To do:]% |
282 | #1% |
283 | \end@{note@}% |
284 | @}@}% |
285 | \par% |
286 | @} |
287 | |
288 | % *@@-indexing-@@* |
289 | |
290 | \newindex@{default@}@{idx@}@{ind@}@{Index@} |
291 | \atdef^@{\index@} |
292 | \atdef_@{\index*@} |
293 | @end example |
294 | |
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} |
298 | |
299 | |
300 | @node The txtlib program, , Anatomy, Text libraries |
301 | @section The @code{txtlib} program |
302 | |
303 | The @code{txtlib} program can be used to perform some simple operations on |
304 | text libraries: |
305 | |
306 | @example |
307 | txtlib [-x] [-o @var{file}] @var{library}... |
308 | txtlib -l @var{library}... |
309 | @end example |
310 | |
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. |
317 | |
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. |
320 | |
321 | |
322 | |
323 | |
324 | @c -------------------------------------------------------------------------- |
325 | |
326 | @contents |
327 | @bye |