"Fossies" - the Fresh Open Source Software Archive
Member "sitecopy-0.16.6/gnome/doc/xsitecopy.sgml" (2 Jan 2005, 17139 Bytes) of archive /linux/www/sitecopy-0.16.6.tar.gz:
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard
) with prefixed line numbers.
Alternatively you can here view
the uninterpreted source code file.
1 <!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
3 <book id=xsitecopy>
16 XSitecopy requires the Gnome libraries, version 1.0.14 or above, and all
17 of the pre-requisites of those libraries.
23 To compile from the source distribution, change into the source directory
24 and run:
26 <simplelist><member><computeroutput>./configure --enable-gnomefe</computeroutput></member>
28 <member><computeroutput>make install (become root first)</computeroutput></member>
33 To install from a binary rpm, change directory to the location of your
34 freshly downloaded rpm and type the following, (substituting i386 for whatever
35 architecture you are running on, and VERSION for the version you've acquired):
38 <para><computeroutput>rpm -iv xsitecopy-VERSION-1.i386.rpm
41 <para>To rebuild a binary rpm from a source rpm, do the following:
42 <computeroutput>rpm --rebuild sitecopy-VERSION-1.src.rpm
45 <para>This will place a binary rpm in /usr/src/redhat/RPMS/i386/ which can be
46 installed as above.
53 Once installed, you should find a shortcut to XSitecopy in the Internet
54 section of your gnome system menu. If you are not running GNOME as your desktop
55 environment, simply type xsitecopy into an xterm.
60 If you've never used sitecopy before, you should take a look at the README
61 file that comes with the sitecopy distribution. When you run xsitecopy for
62 the first time, it will set up 2 things in your home directory; a
63 configuration file where your site definitions are stored ($HOME/.sitecopyrc),
64 and a storage directory where it will place configuration files to keep
65 track of the files you add, change, move or delete on the local copies of
66 your websites. ($HOME/.sitecopy/)
68 To create sites, click <emphasis>New site </emphasis>. A Gnome Druid will appear to
69 guide you through the creation process. You must type a name for the site,
70 along with server details and local & remote directory names. All other
71 options may be left at their default values, or configured to your personal
77 <chapter><title>Creating a site</title>
79 <para>To guide you through the process of creating a site, a step-by-step Druid is provided.
80 At each stage of the druid, the information required is explained. Almost all of the
81 information is optional and can be edited or added at a later date. If you miss out a
82 field that is mandatory for site creation, a dialog will pop up to warn you.</para>
84 <para>We'll now take a look at the various steps of the site creation druid. FIXME. Add
85 lots of nice screenshots, and a commentary.</para>
89 <chapter><title>The Main Interface</>
92 At the top is the menu. Below this is the toolbar. Both of these are used to
93 perform operations on sites, and/or retrieve more general information.
96 <para>Below these bars is the main part of Xsitecopy's user interface. As is
97 obvious from glancing at it, the UI is split into 2 main sections. On the
98 left is a tree view with a tree node for each of the sites that Xsitecopy
99 knows about.
101 <!-- FIXME: Add something about site name colours and configurability here -->
103 If you expand a site, the files and directories that it is aware of will be
104 shown in a similar manner to the gnome file manager, gmc. Clicking on a file
105 or directory brings up information about that file in the right side of the
107 <!--FIXME: Make the above less crap, and a little more verbose -->
115 If you click on a site, the details and attributes of that site will be
116 displayed in the main area of the program. These are divided into what are
117 hopefully logical sections. Each section is separated by a frame, described
121 <sect1><title>Basic Details</title>
125 <listitem><para><emphasis>Hostname</emphasis> is the name of your
126 remote web server. For example, ftp.geocities.com.</para></listitem>
128 <listitem><para><emphasis>Port</emphasis> specifies the port that
129 should be connected to on the remote server. Unless you know you need
130 to change this, it should be safe to simply use the default value
131 setup by your chosen protocol. </para></listitem>
133 <listitem><para><emphasis>Protocol</emphasis> determines the method
134 that sitecopy uses to transfer your files. This is
135 <emphasis>totally</emphasis> dependant upon whether or not you would
136 normally upload files to your website using FTP, or whether you are
137 using a WebDAV server. You should choose the protocol
138 accordingly. Note:- If xsitecopy has been compiled without WebDAV
139 support, FTP will be the only option here.</para></listitem>
141 <listitem><para><emphasis>Username</emphasis> is the name you normally
142 use to login when uploading files. If this is incorrect, you will
143 receive errors when trying to upload your files.</para></listitem>
145 <listitem><para><emphasis>Password</emphasis> is the password required
146 in order to login to the remote server. This will appear as asterisks
147 on the screen.</para></listitem>
149 <listitem><para><emphasis>Site Statistics</emphasis> provides a short
150 summary of the changes (if any) to the local site, since the last
151 update was performed.</para></listitem>
157 <sect1><title>Locations & Files</title>
160 <listitem><para><emphasis>Directory for local files</emphasis>, is an absolute path in your file system. It
161 should be the root directory <emphasis>of your website</emphasis> that resides on your
164 <listitem><para><emphasis>Directory for remote files</emphasis>, is the directory that all files will be
165 uploaded <emphasis>into</emphasis>. It must exist on the remote site for a successful
166 update to be completed. The directory must either have a / prefix if it is
167 an absolute path, or a \~/ prefix if it is relative to your remote login
171 <emphasis>Root URL of the remote site</emphasis>, is a non-essential field, that can be used to
172 generate a "recent changes" web page using the console application,
173 sitecopy, and a provided awk script. Support for report generation is
174 planned for a future version of Xsitecopy.
177 <listitem><para><emphasis>Permissions mode</emphasis>, can be one of Ignore All, Executables Only, or Maintain
178 For All. These options force XSitecopy to either ignore permissions of
179 uploaded files, maintain them for files with the execute bit set locally, or ensure
180 ALL remote files have the same permission bits as the local site,
183 <listitem><para><emphasis>Symbolic links</emphasis>, can be treated in
184 various ways. `Follow all' will tell
185 XSitecopy to upload the file (or directory?) that any symbolic links point to.
186 `Ignore links' tells XSitecopy not to care if it encounters a symbolic link
187 on the local site. `Maintain all' will attempt to create symbolic links on
188 the remote site, if this is supported by the selected protocol.
195 <sect1><title>Update Options</title>
198 <listitem><para><emphasis>Delete a file from the server if it is deleted locally</emphasis>. If this is not checked, then any local files that are deleted will be forgotten about. Selecting this option will force sitecopy to delete anything that is deleted on the local copy of the remote site.
200 <listitem><para><emphasis>Move a remote file if it is moved locally</emphasis>. When not checked, sitecopy will
201 not bother to check if a file has been moved locally, when it appears to be
202 deleted. If you wish all local file moves to be mirrored on the remote site,
203 ensure this option is checked.
205 <listitem><para><emphasis>When uploading changed files, first delete them</emphasis>
207 <listitem><para><emphasis>Convert all filenames to lowercase when uploading</emphasis>
209 <listitem><para><emphasis>Use "safe mode"</emphasis>
211 <listitem><para><emphasis>Use passive mode FTP</emphasis>, should only be unchecked if you actually
212 <emphasis>know</emphasis> you want it unchecked.</para></listitem>
213 <listitem><para><emphasis>When uploading changed files, first delete them</emphasis>. This option should
214 not be checked by default. If you find that your FTP server has trouble
215 dealing with over-writing files, then this option will force sitecopy to
216 first delete a changed file remotely, before uploading the newer local copy.
222 <sect1><title>Excludes, ASCII, and Ignores</title>
224 Chances are that while you're editing html locally, things like backup files
225 will get created. While useful, it's likely you don't want them uploaded to
226 your remote web site. The excludes section allows you to specify glob
227 patterns (see the fnmatch(3) and glob(7) man pages).
228 Any files on the local site matching these expressions will be
229 ignored by XSitecopy.</para>
230 <para>For example my excludes consist of:</para>
238 <para>because I don't want any backups or core dumps uploaded. I also have a
239 sub-directory on my local site called 'oldweb' which I keep for nostalgic
240 purposes only. This is not uploaded by specifying it as 'an exclude'.
245 <chapter><title>Files & Directories</title>
246 <sect1 id="existingfiles"><title>Existing Files</title>
248 FIXME: Add a list of the types here, added, changed, unchanged.
252 <sect1><title>Deleted Files</title>
253 <para>Deleted files appear in a site's file tree because they represent an
254 operation that Xsitecopy must still perform when doing an update. However,
255 given that these files don't exist, the only information Xsitecopy can
256 report is just that.
262 <chapter id="menus"><title>The Menus</title>
266 This will start the site creation wizard. This wizard will take you through
267 the step-by-step process required to give XSitecopy details about a website
268 you wish to upload using XSitecopy. When you click "apply" the program may
269 appear to freeze over for a number of seconds (or longer on large sites).
270 This is currently normal, while XSitecopy processes the local files for the
271 new site.
277 Prompts you for the filename of a valid sitecopy configuration file. (rc
278 file). If you specify a valid one, the sites that the file defines will be
279 loaded into XSitecopy.
284 <sect2><title>Save sites</title>
285 <para>Saves your site definitions file to the default configuration file.
290 <sect2><title>Save sites As...</title>
291 <para>Will prompt you for a filename, and then save your site definitions
292 to the file given.
296 <sect2><title>Delete this site</title>
297 <para>Asks for confirmation as to whether you wish to delete the
298 selected site or not. If you do, it will.
305 Select this to exit the program. If your site definitions have not been
306 saved, you will be prompted to save them.
312 <para>A site can be initialised, caught-up, updated, a listing can be
313 fetched, or it can be resynchronized, with the remote site.
315 <sect2><title>Initialise site</title>
316 <para>This will make xsitecopy think that there are <emphasis>no</emphasis> files on the
317 remote site. This should be used to upload new files, or if you decide to
318 change remote servers.
322 <sect2><title>Catchup site</title>
323 <para>This will force xsitecopy to assume that the remote site is identical to
324 your local copy. Useful for starting new sites that are already online, or
325 if you accidentally initialise a site.
329 <sect2><title>Fetch site listing</title>
330 <para>This will make xsitecopy connect to the remote site and attempt to
331 determine what files are there. This is useful if your configuration files
332 have become corrupted, and your local-remote sites are in an inconsistent
333 state. It is also required if you wish to perform a resynchronization on
334 your local site.
338 <sect2><title>Resynchronize site</title>
339 <para>Expected by 0.11.0.
343 <sect2><title>Update site</title>
344 <para>This will produce a dialog box. Once you are ready to connect to the
345 remote site, hit <emphasis>Begin</emphasis> and xsitecopy will attempt to make a
346 connection. Once one has been established, the operations required
347 to synchronize the remote site with the local one will be committed.
348 Progress indicators display the percentage completed of each operation.
352 <sect2><title>Update ALL sites</title>
353 <para>This will perform the above updates, for every site that requires one.
354 Expected by 0.13.0.
360 <sect2><title>Required updates</title>
362 <para>This displays a short report (depending upon how many sites you have
363 defined), simply stating which sites require an update.</para>
366 <sect2><title>Site web-report</title>
367 <para>This creates a report of all modifications of the selected site, and
368 displays them in your web browser. The browser use depends entirely upon how
369 your gnome-url settings have been configured. (see gnome control-center for
370 more info).
373 NOTE:- This feature is currently a complete hack that requires about 5
374 things all of which are not likely to hold on a system different to my own.
375 A wide range of report options will be created as soon as sitecopy has reached a 1.0 state.
379 <sect2><title>Print site info</title>
380 <para>Not currently implemented.</para>
386 <para>This allows you to set various things. Or at least it will do as soon as
387 I write it. :o)
393 <sect2><title>Backup files status</title>
394 <para>The state of your files on the remote site is actually stored in a file
395 on the local hard drive. If this file was to become corrupted, then the
396 state would normally have to be initialized, or "caught up". This gives you
397 an alternate option.</para>
400 <sect2><title>Restore files status</title>
401 <para>If you have a made a backup of your files' state information, this gives
402 you the option to restore it.</para>
405 <sect2><title>Backup site definitions</title>
406 <para>Saves a backup of your 'rcfile' - the file XSitecopy uses to store the
407 site definitions.</para>
410 <sect2><title>Restore site definitions</title>
412 If you have previously backed up your site configurations, this will restore
420 <para>Short dialog about the program.</para>
423 <sect2><title>XSitecopy Manual</title>
424 <para>Should bring up this online manual.</para>
430 <para><emphasis>Do NOT run xsitecopy as root</emphasis>. My experience has shown that for
431 some reason all the sanity tests that determine (for example) whether a site
432 is selected when you click certain buttons, just fail inexplicably.
434 <para>Once a new site has been created, the site's "statistics" seem
435 to occasionally be wrong. Restarting the program seems to correct that. I
436 *think* this is now fixed, but if you still encounter the problem,
437 please let me know.</para>
441 <chapter id="todo"><title>Todo</title>
444 <listitem><para>More, cleaner methods of reporting changes to sites.</para></listitem>
445 <listitem><para>Re-synchronize mode.</para></listitem>
446 <listitem><para>Preferences dialog.</para></listitem>
447 <listitem><para>Output of reports to printers. (use of gnome-print perhaps).</para></listitem>
448 <listitem><para>Clean up some of the saved-notsaved code.</para></listitem>
449 <listitem><para>Gnome panel applet for one-click updates.</para></listitem>
451 Feel free to email me at firstname.lastname@example.org with any feature requests.
455 <chapter id="bugs"><title>Known Bugs</title>
459 Switching between time-size and checksum for change-detection is a bit dodgy
460 at the moment.
463 Occasional crashes are seen every so often when rescanning. These could be
464 random memory corruption, but seem to have gone away recently.