mdw@git.distorted.org.uk Git - cfd/blob - common.texi

   1 \input texinfo.tex @c -*-texinfo-*-
   2 @c
   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
  34 @dircategory Development
  35 @direntry
  36 * Common Files Distribution: (common).  A central place for boilerplate
  37 @end direntry
  38 @iftex
  39 @input texinice
  40 @afourpaper
  41 @end iftex
  42 @include version.texi
  43 @c %**end of header
  44
  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::
 129
 130 @detailmenu
 131  --- The Detailed Node Listing ---
 132
 133 The file repository
 134
 135 * The mklinks command::
 136 * The findlinks command::
 137
 138 @end detailmenu
 139 @end menu
 140
 141 @c --------------------------------------------------------------------------
 142 @node Copying, Introduction, Top, Top
 143 @unnumbered The GNU General Public License
 144
 145 @include gpl-2.0.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 --------------------------------------------------------------------------
 170 @node The file repository,  , Introduction, Top
 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
 232 @c --------------------------------------------------------------------------
 233
 234 @contents
 235 @bye