Merge pull request #1131 from semanticarts/migrationREADME-updates

Fix minor nits in migration README

Author: rjyounes

.gitignore

@@ -2,4 +2,5 @@
 *_webDownload/
 .DS_Store
 *.orig
+**/*venv
 catalog-v001.xml

bundle.yaml

@@ -290,6 +290,16 @@ actions:
   target: "{output}/migration/v13.0/"
   includes:
     - "*.md"
+- action: "move"
+  message: "Patching documentation links in gist 13.0 HTML migration documentation."
+  source: "{output}/migration/v13.0/"
+  target: "{output}/migration/v13.0/"
+  includes:
+    - "*.html"
+  # Replaces ./*.md local links with ./*.html
+  replace:
+    from: "(?:docs|documentation)/(.*)\\.md"
+    to: "../../documentation/\\g<1>.html"
 - action: "move"
   message: "Patching local links in gist 13.0 HTML migration documentation."
   source: "{output}/migration/v13.0/"
@@ -298,5 +308,6 @@ actions:
     - "*.html"
   # Replaces ./*.md local links with ./*.html
   replace:
-    from: "./(.*)\\.md"
-    to: "./\\g<1>.html"
+    from: "\\./(\\w*)\\.md"
+    to: "\\g<1>.html"
+

migration/v13.0/README.md

@@ -3,7 +3,7 @@
 This file gives a quick overview of using the migration utilities provided
 by the gist team to help migrate from the previous version of gist.
 
-> See also additional documentation in the file `../../docs/MajorVersionMigration.md`.
+> See also additional documentation in the [Major Version Migration](../../docs/MajorVersionMigration.md).
 
 ## Important Remarks
 
@@ -23,26 +23,23 @@ All of our migration tools are SPARQL queries.
 
 The following directory structure holds the migration scripts:
 
-```
-.
-└── queries/
-    │
-    ├── action/
-    │   ├── default/
-    │   │   └── *.rq
-    │   └── ngraphs/
-    │       └── *.rq
-    │
-    ├── report/
-    │   ├── default/
-    │   │   └── *.rq
-    │   └── ngraphs/
-    │       └── *.rq
-    │
-    └── uom_queries/
-        └── *.rq
-
-```
+    .
+    └── queries/
+        │
+        ├── action/
+        │   ├── default/
+        │   │   └── *.rq
+        │   └── ngraphs/
+        │       └── *.rq
+        │
+        ├── report/
+        │   ├── default/
+        │   │   └── *.rq
+        │   └── ngraphs/
+        │       └── *.rq
+        │
+        └── uom_queries/
+            └── *.rq
 
 The `./queries/` directory contains the following directories:
 
@@ -66,42 +63,47 @@ The action and report directories each contain the following two directories:
 
 These migration scripts are meant to be run using the open source `onto_tool`
 program. Information about onto_tool and how to install it, is available at
-[github](https://github.com/semanticarts/ontology-toolkit).
+[PyPi](https://pypi.org/project/onto-tool).
 
 ## Run on local files
 
 > Note: A known limitation of `onto_tool` is that it does not support named graphs when run against local files. It does support named graphs when run against a SPARQL endpoint.
 
-1. Starting in this directory, put source data files in the `./input/` directory (the sample data can be removed). See the onto_tool documentation for which file formats are supported.
+1. Starting in this directory, either place source data files in the `./input/` directory or point the script at the location of your data via `-v input` flag (see example below). See the onto_tool documentation for which file formats are supported.
 
-   > The `migrate_local.yaml` file currently looks in the `./input/` directory for `*.owl` and `*.ttl` files. If other formats are supported and you plan to use them, you will need to update the yaml.
+   > * The `migrate_local.yaml` file currently looks in the input directory for `*.owl` and `*.ttl` files. If other formats are supported and you plan to use them, you will need to update the yaml.
+   > * The script will only transform RDF data files at the top level of the input directory, and will not recursively descend into sub-directories. Invoke the script multiple times with different directories specified via the `-v input` flag as needed.
 
-2. Execute the following command:
+2. Execute the following command for the default `./input` director:
 
    ```shell
    onto_tool bundle migrate_local.yaml
    ```
 
-3. `onto_tool` will output to STDOUT, you should see something like the following (this is the output from the sample data included in the `./input/` directory):
+   or with a custom input directory:
 
+   ```shell
+   onto_tool bundle -v input <directory of RDF data> migrate_local.yaml
    ```
-   INFO:root:Rename properties in named graphs.
-   INFO:root:Replace address classes in named graphs.
-   INFO:root:Replace properties with inverses in named graphs.
-   INFO:root:Use new gist:offers property in named graphs (script 1).
-   INFO:root:Use new gist:offers property in named graphs (script 2).
-   INFO:root:Rename properties in named graphs.
-   INFO:root:Replace address classes in named graphs.
-   INFO:root:Replace properties with inverses in named graphs.
-   INFO:root:Use new gist:offers property in named graphs (script 1).
-   INFO:root:Use new gist:offers property in named graphs (script 2).
-   INFO:root:Check the named graphs for other items that should be reviewed.
-   INFO:root:Check named graphs for other items that should be reviewed.
-   ```
 
-   - Output files will be created in the `./output/` directory.
+3. `onto_tool` will output to STDOUT, you should see something like the following:
+
+        INFO:root:Rename properties in named graphs.
+        INFO:root:Replace address classes in named graphs.
+        INFO:root:Replace properties with inverses in named graphs.
+        INFO:root:Use new gist:offers property in named graphs (script 1).
+        INFO:root:Use new gist:offers property in named graphs (script 2).
+        INFO:root:Rename properties in named graphs.
+        INFO:root:Replace address classes in named graphs.
+        INFO:root:Replace properties with inverses in named graphs.
+        INFO:root:Use new gist:offers property in named graphs (script 1).
+        INFO:root:Use new gist:offers property in named graphs (script 2).
+        INFO:root:Check the named graphs for other items that should be reviewed.
+        INFO:root:Check named graphs for other items that should be reviewed.
+
+   - Output files will be created in the `./output/` directory. The location can be overriden by specifying `-v output <existing directory for output>`.
 
-   - Report files will be created in the `./reports/` directory.
+   - Report files will be created in the `./reports/` directory. The location can be overriden by specifying `-v report <existing directory for report>`. 
 
 ## Run Against SPARQL Endpoint
 
@@ -124,7 +126,7 @@ onto_tool bundle -v user <USER> -v password <PWD>
 - replaceAddressClasses replaces `gist:EmailAddress` with `gist:ElectronicAddress`
 - replaceAddressClasses replaces `gist:StreetAddress` with `gist:PhysicalAddress`
 
-The different types and uses of addresses can be modeled as categories; see [the address migration documentation(AddressMigration.md) as well as the [full documentation of the new address model](/docs/model_documentation/AddressGuidance.md).
+The different types and uses of addresses can be modeled as categories; see [the address migration documentation](./AddressMigration.md) as well as the [full documentation of the new address model](../../docs/models/AddressGuidance.md).
 
 - replacePropertiesWithInverses replaces `gist:hasPart` with `gist:isPartOf`
 - useOffersProperty (scripts 1 and 2) replaces `gist:hasPart` with `gist:offers` in the context of an offer