external/customize.txt

customize.txt 1.0.0                   UTF-8                       2015-01-08

               CUSTOMIZING EXTERNAL DOWNLOADS FOR OTHER DOWNLOADS
               ==================================================

    The external\ folder holds scripts and the download\ sub-folder for
    external software that Corinthia Windows Win32 x86 builds depend on.

    Note: This repository folder is intended to be usable when cloned to a
    Microsoft platform.  The notation for file paths reflects that, even
    though POSIX path notation is used in the git and when viewed on GitHub.

BASIC CUSTOMIZATION APPROACH

The files, listed below, can be moved in their entirety to a new folder
location where download of external materials is desired.

The scripts are designed to operate relative to where they are stored.  So
if the scripts are moved to a folder named test-documents\, they will produce
and populate a further sub-folder, either named download\ or a different name
that is customized.

One can make further modifications that deviate further from this structure.
It is useful to make such changes in stages to ensure that the new organiza-
tion is being honored correctly.

Once the eight files are moved to their intended new home, customization at
the detail is similar to following the maintenance procedure with allowance
for the changes in location and desired operation.

FILES TO MODIFY

    .gitignore
        Change the name of the download\ subfolder here if a different
        folder outside of the managed source tree is used.

    fetch_downloads.bat
        The "download" name must be replaced everywhere that a different
        folder name is to be used as the location of downloaded files.  The
        number of downloads and the names will also be changed by creation
        of appropriate :FETCH calls in place of the ones in the script.

    extract_downloads.bat
        The "download" name must be replaced everywhere that a different
        folder name is to be used as the location of the downloaded files
        and of the new directories created as part of the extraction.  Note
        that all extractions of Zips are  into a subfolder "T\" and then the
        extracts are selectively moved to other places in the chosen download\
        location.  This procedure requires the greatest customization
        depending on the purpose of the download procedure.

    README.txt
        replace with appropriate text, if needed at all.

    customize.txt
        this file can be kept unchanged or touched-up slightly for the new
        location.  Alternatively, simply refer to the originals that were
        customized, linking to where this procedure was found.

    maintenance.txt
        This can still apply, depending on how much difference there is,
        especially in the extraction process.  Most of the advice remains
        applicable.

    unzip-win.js
        This helper script takes the archive filename and the destination
        folder as parameters.  It does not need to be modified.

    wget-win.js
        This helper script takes the URL and the download location as
        parameters.  It does not need to be modified.


 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

      Licensed to the Apache Software Foundation (ASF) under one
      or more contributor license agreements.  See the NOTICE file
      distributed with this work for additional information
      regarding copyright ownership.  The ASF licenses this file
      to you under the Apache License, Version 2.0 (the
      "License"); you may not use this file except in compliance
      with the License.  You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing,
      software distributed under the License is distributed on an
      "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
      KIND, either express or implied.  See the License for the
      specific language governing permissions and limitations
      under the License.

TODO

 * Add maintainance.txt for the maintenance procedure for the scripts in their
   original external\ portion of the Corinthia repository.

 * Add customize.txt for the procedure for customizing the scripts in another
   location or project.

 * Update README.txt to reflect these when present.

 * Add Apache license notice to anything of much length.

 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

 1.0.0 2015-01-08-16:48 Create initial version to account for the way
       the scripts will produce different download folders in other places.

                     *** end of customize.txt ***