Confused in the docs... What's literal and what's variable?

[McFateM]

Working through the migration_guide.md and I'm frequently confused: What is to be taken literally, and what is "variable"? An example from Step 2 of the aforementioned document:

The docker-compose.yml file found within /opt/ISLE/config/enduser-renamed-directory-prod.institution is ready for editing to "point" to these data directories. This process will be explained in further detail in Step 6 of this guide.

Overall, I find this paragraph, and some others, invoke more questions than answers.

In my case, I have no /opt/ISLE/config/enduser-renamed-directory-prod.institution directory, but I did find an isle-prod-project.institution directory at that location. Is one of these names "literal", not to be modified, or are one or both "variable"?

A suggestion... Is it too late to adopt a convention here? Maybe using {curly braces} to wrap elements of the text that are "variable"? If that were the case, then my interpretation, right or wrong, of the paragraph above would read something like this:

The docker-compose.yml file found within /opt/ISLE/config/{enduser-renamed-directory}-prod.{institution} is ready for editing to "point" to these data directories. This process will be explained in further detail in Step 6 of this guide.

Assuming a convention like this, I'd expect to find other references to {enduser-renamed-directory} and {institution} elsewhere in the document, and perhaps in some of the code, and I would expect to give all matching {variables} the same value.

Another case in point... there's a section of migration_guide.md with a directory tree diagram like so:

Example future directory structure:

  /path_to/isle_production_data_storage/
           |
           ├──enduser-renamed-directory-dev.institution
           |  ├── apache  
           |  ├── fedora   
           |  ├── mysql  
           |  └── solr  
           |
           ├──enduser-renamed-directory-prod.institution
           |  ├── apache  
           |  ├── fedora   
           |  ├── mysql  
           |  └── solr  
           |
           ├──enduser-renamed-directory-stage.institution
           |  ├── apache  
           |  ├── fedora   
           |  ├── mysql  
           |  └── solr     
           |

When I worked through that section of the document I assumed something like this:

Example future directory structure:

  /{mount}/isle_production_data_storage/
           |
           ├──{enduser-renamed-directory}-dev.{institution}
           |  ├── apache  
           |  ├── fedora   
           |  ├── mysql  
           |  └── solr  
           |
           ├──{enduser-renamed-directory}-prod.{institution}
           |  ├── apache  
           |  ├── fedora   
           |  ├── mysql  
           |  └── solr  
           |
           ├──{enduser-renamed-directory}-stage.{institution}
           |  ├── apache  
           |  ├── fedora   
           |  ├── mysql  
           |  └── solr     
           |

And I made the following "global" substitutions in my build...

• {mount} = mnt
• {enduser-renamed-directory} = dg
• {institution} = grinnell

Comments? Suggestions?

[hamhpc]

Thanks for bringing this up. This is about where I'm at (once I have my 3TB massaged in the islandora_production_data_storage directory). I also would ask to remove the .institution from the whole thing. At each location we *are* the institution aren't we? So it's semi-redundant. It might make sense for a private company though, that manages lots of different "institutions" ;-) so I can see the merit. But to make it as simple as possible I'd just remove it and leave it for the enduser to decide. I'd also like to see the /ISLE/config/isle-prod-project.institution get renamed to isle-config-template or something of the sort to indicate it's a "template". Then in the instructions for this I'd replace {enduser-renamed-directory} to {copy_of_isle_config_template_dir}-prod or something like that. To help indicate what those directories are.

…

-Steve ***************************************** Steven L. Young Unix/HPC System Administrator Hamilton College *****************************************

On Thu, Feb 22, 2018 at 6:05 PM, Mark McFate ***@***.***> wrote: Working through the migration_guide.md and I'm frequently confused: What is to be taken literally, and what is "variable"? An example from Step 2 of the aforementioned document: The docker-compose.yml file found within /opt/ISLE/config/enduser- renamed-directory-prod.institution is ready for editing to "point" to these data directories. This process will be explained in further detail in Step 6 of this guide. Overall, I find this paragraph, and some others, invoke more questions than answers. In my case, I have no /opt/ISLE/config/enduser-renamed-directory-prod.institution file, but I did find an isle-prod-project.institution file at that location. Is one of these names "literal", not to be modified, or is one or both "variable"? A suggestion... Is it too late to adopt a convention here? Maybe using {curly braces} to wrap elements of the text that are "variable"? If that were the case, then my interpretation of the paragraph above would read something like this: The docker-compose.yml file found within /opt/ISLE/config/{enduser- renamed-directory}-prod.{institution} is ready for editing to "point" to these data directories. This process will be explained in further detail in Step 6 of this guide. Assuming a convention like this, I'd expect to find other references to {enduser-renamed-directory} and {institution} elsewhere in the document, and perhaps in some of the code, and I would expect to give all matching {variables} the same value. Another case in point... there's a section of migration_guide.md with a directory tree diagram like so: *Example future directory structure*: /path_to/isle_production_data_storage/ | ├──enduser-renamed-directory-dev.institution | ├── apache | ├── fedora | ├── mysql | └── solr | ├──enduser-renamed-directory-prod.institution | ├── apache | ├── fedora | ├── mysql | └── solr | ├──enduser-renamed-directory-stage.institution | ├── apache | ├── fedora | ├── mysql | └── solr | When I worked through that section of the document I assumed something like this: *Example future directory structure*: /{mount}/isle_production_data_storage/ | ├──{enduser-renamed-directory}-dev.{institution} | ├── apache | ├── fedora | ├── mysql | └── solr | ├──{enduser-renamed-directory}-prod.{institution} | ├── apache | ├── fedora | ├── mysql | └── solr | ├──{enduser-renamed-directory}-stage.{institution} | ├── apache | ├── fedora | ├── mysql | └── solr | And I made the following "global" substitutions in my build... - {mount} = mnt - {enduser-renamed-directory} = dg - {institution} = grinnell Comments? Suggestions? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#116>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEinltiFrGGiae6bQ_G2FP4iAM4euXeGks5tXfKjgaJpZM4SQIbu> .

[dmer]

We discussed this morning adding glossary of terms and variables - this can be a separate page in the docs that defines some of the more basic terminology and also has all of the "variables" called out and explained