<?xml version="1.0"?>
<sect1 id="repo-usage-section-6" xreflabel="Syncronizing path information" label="3.6">

    <title>Syncronizing path information</title>

    <para>Syncronizing path information is the action of keeping all
    path information up to date in the repository. This action implies
    both file movement and replacement of content inside files already
    moved, in this very specific order. File movement is related to
    actions like duplicate, delete and rename files and directories in
    the repository.  Replacement of content inside files is related to
    replace information, path information in this case, inside files
    in the repository.</para>
    
    <para>The order followed to syncronize path information is
    relevant because the versioned nature of the files we are working
    with. We don't perform file content replacement first because that
    would imply a repository change which will immediatly demmand a
    commit in order for actions like duplicate, delete or rename to
    take place. However, if we perform file movement first, it is
    possible to commit both file moved and file content replacements
    as if they were just one change. In this case the file content
    replacement takes palce in the target location that have been
    duplicated or renamed, not the one use as source location. This
    configuration is specially useful when files are renamed (i.e.,
    one file is copied from a source location to a target location and
    then the source location of it is removed from repository).</para>
    
    <warning><para>There is no support for URLs actions inside
    <command>centos-art.sh</command> script.  The
    <command>centos-art.sh</command> script is designed to work with
    local files inside the working copy only. If you need to perform
    URL actions directly, use Subversion commands
    instead.</para></warning>
    
    <para>When one master path is changed it is required that all
    related auxiliar paths be changed, too. This is required in order
    for master paths to retain their relation with auxiliar paths.
    This way, automation scripts are able to know where to retrive
    translation messages from, where to store final output images to
    and where to look for documentation. If relation between master
    paths and auxiliar paths is lost, there is no way for automation
    scripts to know where to retrive the information they need.</para>
    
    <para>The auxiliar paths should never be modified under any reason
    but to satisfy the relationship with the master path.  Liberal
    change of auxiliar paths may suppress the conceptual idea they
    were initially created for; and certainly, automation scripts may
    stop working as expected. The update direction to rename path
    information must be from master path to auxiliar path and never
    the opposite.</para>
    
    <para>The relation between master and auxiliar paths is useful to
    keep repository organized but introduce some complications when we
    work with files that use master path information as reference to
    build structural information.  This is the case of repository
    documentation manual source files where inclusions, menus, nodes
    and cross references are built using master path information as
    reference.  Now, to see what kind of complication we are talking
    about, consider what would happen to a structural definitions
    (i.e., inlusions, menus, nodes and cross refereces) already set in
    the manual from one master path that is suddenly renamed to
    something different.  If the path information is not syncronized,
    at this point, we lose connection between the master path and the
    auxiliar path created to store the related documentation entry, as
    well as the related structural definitions that end up pointing to
    a master path that no longer exist.</para>
    
    <para>The syncronization of path information is aimed to solve
    these kind of issues.</para>
    
</sect1>