"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 or download the uninterpreted source code file.

    1 <!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
    3 <book id=xsitecopy>
    5 <bookinfo>
    6   <title>XSitecopy</title>
    7   <author>
    8     <firstname>Lee</firstname>
    9     <surname>Mallabone</surname>
   10     <authorblurb><para>lee0@callnetuk.com</para></authorblurb>
   11   </author>
   12 </bookinfo>
   14 <chapter><title>Requirements</title>
   15 <para>
   16 XSitecopy requires the Gnome libraries, version 1.0.14 or above, and all
   17 of the pre-requisites of those libraries.
   18 </para>
   19 </chapter>
   21 <chapter><title>Installation</title>
   22 <para>
   23 To compile from the source distribution, change into the source directory
   24  and run:
   26 <simplelist><member><computeroutput>./configure --enable-gnomefe</computeroutput></member>
   27 <member><computeroutput>make</computeroutput></member>
   28 <member><computeroutput>make install  (become root first)</computeroutput></member>
   29 </simplelist>
   30 </para>
   32 <para>
   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):
   36 </para>
   38 <para><computeroutput>rpm -iv xsitecopy-VERSION-1.i386.rpm
   39 </computeroutput></para>
   41 <para>To rebuild a binary rpm from a source rpm, do the following:
   42 <computeroutput>rpm --rebuild sitecopy-VERSION-1.src.rpm
   43 </computeroutput></para>
   45 <para>This will place a binary rpm in /usr/src/redhat/RPMS/i386/ which can be
   46  installed as above.
   47 </para>
   48 </chapter>
   50 <chapter><title>Usage</title>
   51 <para>
   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.
   56 </para>
   57 <sect1><title>Quick-Start</>
   58 <para>
   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 &amp; remote directory names. All other
   71 options may be left at their default values, or configured to your personal
   72 taste.
   73 </para>
   74 </sect1>
   75 </chapter>
   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>
   86 </chapter>
   89 <chapter><title>The Main Interface</>
   90 <para>
   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.
   94 </para>
   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.
  100 </para>
  101 <!-- FIXME: Add something about site name colours and configurability here -->
  102 <para>
  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
  106 window.
  107 <!--FIXME: Make the above less crap, and a little more verbose -->
  108 </para>
  109 </chapter>
  113 <chapter><title>Sites</>
  114 <para>
  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
  118 below.
  119 </para>
  121 <sect1><title>Basic Details</title>
  122 <para>
  123 <itemizedlist>
  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>
  153 </itemizedlist>
  154 </para>
  155 </sect1>
  157 <sect1><title>Locations &amp; Files</title>
  158 <para>
  159 <itemizedlist>
  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
  162 filesystem.
  163 </para></listitem>
  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
  168 directory.
  169 </para></listitem>
  170 <listitem><para>
  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.
  175 </para></listitem>
  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,
  181 respectively.
  182 </para></listitem>
  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.
  189 </para></listitem>
  191 </itemizedlist>
  192 </para>
  193 </sect1>
  195 <sect1><title>Update Options</title>
  196 <para>
  197 <itemizedlist>
  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.
  199 </para></listitem>
  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.
  204 </para></listitem>
  205 <listitem><para><emphasis>When uploading changed files, first delete them</emphasis>
  206 </para></listitem>
  207 <listitem><para><emphasis>Convert all filenames to lowercase when uploading</emphasis>
  208 </para></listitem>
  209 <listitem><para><emphasis>Use &quot;safe mode&quot;</emphasis>
  210 </para></listitem>
  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.
  217 </para></listitem>
  218 </itemizedlist>
  219 </para>
  220 </sect1>
  222 <sect1><title>Excludes, ASCII, and Ignores</title>
  223 <para>
  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>
  231 <para>
  232 <itemizedlist>
  233 <listitem><para>*.bak</para></listitem>
  234 <listitem><para>core</para></listitem>
  235 <listitem><para>oldweb</para></listitem>
  236 </itemizedlist>
  237 </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'.
  241 </para>
  242 </sect1>
  243 </chapter>
  245 <chapter><title>Files &amp; Directories</title>
  246 <sect1 id="existingfiles"><title>Existing Files</title>
  247 <para>
  248 FIXME: Add a list of the types here, added, changed, unchanged.
  249 </para>
  250 </sect1>
  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.
  257 </para>
  258 </sect1>
  260 </chapter>
  262 <chapter id="menus"><title>The Menus</title>
  263 <sect1><title>File</title>
  264 <sect2><title>New</title>
  265 <para>
  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.
  272 </para>
  273 </sect2>
  275 <sect2><title>Open</title>
  276 <para>
  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.
  280 </para>
  281 </sect2>
  284 <sect2><title>Save sites</title>
  285 <para>Saves your site definitions file to the default configuration file.
  286 </para>
  287 </sect2>
  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.
  293 </para>
  294 </sect2>
  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.
  299 </para>
  300 </sect2>
  303 <sect2><title>Quit</title>
  304 <para>
  305 Select this to exit the program. If your site definitions have not been
  306 saved, you will be prompted to save them.
  307 </para>
  308 </sect2>
  309 </sect1>
  311 <sect1><title>Operations</title>
  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.
  314 </para>
  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.
  319 </para>
  320 </sect2>
  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.
  326 </para>
  327 </sect2>
  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.
  335 </para>
  336 </sect2>
  338 <sect2><title>Resynchronize site</title>
  339 <para>Expected by 0.11.0.
  340 </para>
  341 </sect2>
  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.
  349 </para>
  350 </sect2>
  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.
  355 </para>
  356 </sect2>
  357 </sect1>
  359 <sect1><title>Reports</title>
  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>
  364 </sect2>
  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).
  371 </para>
  372 <para>
  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.
  376 </para>
  377 </sect2>
  379 <sect2><title>Print site info</title>
  380 <para>Not currently implemented.</para>
  381 </sect2>
  382 </sect1>
  384 <sect1><title>Settings</title>
  385 <sect2><title>Preferences</title>
  386 <para>This allows you to set various things. Or at least it will do as soon as
  387 I write it. :o)
  388 </para>
  389 </sect2>
  390 </sect1>
  392 <sect1><title>Backup</title>
  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>
  398 </sect2>
  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>
  403 </sect2>
  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>
  408 </sect2>
  410 <sect2><title>Restore site definitions</title>
  411 <para>
  412 If you have previously backed up your site configurations, this will restore
  413 them.</para>
  414 </sect2>
  415 </sect1>
  417 <sect1><title>Help</title>
  419 <sect2><title>About</title>
  420 <para>Short dialog about the program.</para>
  421 </sect2>
  423 <sect2><title>XSitecopy Manual</title>
  424 <para>Should bring up this online manual.</para>
  425 </sect2>
  426 </sect1>
  427 </chapter>
  429 <chapter><title>Troubleshooting</title>
  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.
  433 </para>
  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>
  439 </chapter>
  441 <chapter id="todo"><title>Todo</title>
  442 <para>
  443 <itemizedlist>
  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>
  450 </itemizedlist>
  451 Feel free to email me at lee0@callnetuk.com with any feature requests.
  452 </para>
  453 </chapter>
  455 <chapter id="bugs"><title>Known Bugs</title>
  456 <para>
  457 <itemizedlist>
  458 <listitem><para>
  459 Switching between time-size and checksum for change-detection is a bit dodgy
  460 at the moment.
  461 </para></listitem>
  462 <listitem><para>
  463 Occasional crashes are seen every so often when rescanning. These could be
  464 random memory corruption, but seem to have gone away recently.
  465 </para></listitem>
  467 </itemizedlist>
  468 </para>
  469 </chapter>
  471 </book>