Blame Manuals/Docbook/Entities/Repository/Usage/syncronizing-paths.docbook

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