Adjustemnts to DRUPAL_HOME docs

docs/user_guide.rst

@@ -1,5 +1,5 @@
 User's Guide
-==============
+============
 
 
 .. toctree::
@@ -8,6 +8,7 @@ User's Guide
    :glob:
 
    user_guide/what_is_tripal
+   user_guide/drupal_home
    user_guide/install_tripal
    user_guide/drupal_overview
    user_guide/example_genomics

docs/user_guide/bulk_loader.rst

@@ -1,7 +1,10 @@
-
 Bulk Loader
 ===========
 
+.. note::
+
+  Remember you must set the ``$DRUPAL_HOME`` environment variable if you want to cut-and-paste the commands below. See :doc:`drupal_home`
+
 The bulk loader is a tool that Tripal provides for loading of data contained in tab delimited files. Tripal supports loading of files in standard formats (e.g. ``FASTA``, ``GFF``, ``OBO``), but Chado can support a variety of different biological data types and there are often no community standard file formats for loading these data. For example, there is no file format for importing genotype and phenotype data. Those data can be stored in the feature, stock and natural diversity tables of Chado. The Bulk Loader was introduced in Tripal v1.1 and provides a web interface for building custom data loader. In short, the site developer creates the bulk loader "template". This template can then be used and re-used for any tab delimited file that follows the format described by the template. Additionally, bulk loading templates can be exported allowing Tripal sites to share loaders with one another.  Loading templates that have been shared are available on the Tripal website here: http://tripal.info/extensions/bulk-loader-templates.
 
 The following commands can be executed to install the Tripal Bulk Loader using Drush:
@@ -20,7 +23,7 @@ To demonstrate use of the Bulk Loader, a brief example that imports a list of or
 
 .. code-block bash
 
-  cd /var/www/html/sites/default/files
+  cd $DRUPAL_HOME/sites/default/files
   wget http://tripal.info/sites/default/files/book_pages/Fragaria_0.txt
 
 
@@ -244,10 +247,14 @@ Provide the following values:
 
 * Job Name: Import of Fragaria species
 * Template: NCBI Taxonomy Importer (taxid, genus species).
-* Data File: /var/www/html/sites/default/files/Fragaria_0.txt
+* Data File: [DRUPAL_HOME]/sites/default/files/Fragaria_0.txt
 * Keep track of inserted IDs: No
 * File has a header: No
 
+.. note::
+
+  Be sure to change the [DRUPAL_HOME] token to where Drupal is installed.
+
 Click **Save**. The page then appears as follows:
 
 .. image:: ./bulk_loader.9.png
@@ -261,7 +268,7 @@ Now that we have created a job, we can submit it for execution by clicking the *
 .. code-block:: shell
 
   cd /var/www
-  drush trp-run-jobs --username=admin --root=/var/www/html
+  drush trp-run-jobs --username=admin --root=$DRUPAL_HOME
 
 After execution of the job you should see similar output to the terminal window:
 

docs/user_guide/drupal_home.rst

@@ -0,0 +1,9 @@
+DRUPAL_HOME Variable
+====================
+An important convention in this document is the use of the ``$DRUPAL_HOME`` environment variable.  If you are new to UNIX/Linux you can learn about environment variables `here <https://www.tutorialspoint.com/unix/unix-environment.htm>`_.  Drupal is a necessary depenency of Tripal.  The setup and installation sections describe how to install Drupal.  If you follow the instructions exactly as described in this User's Guide you will install Drupal into ``/var/www/html``. However, some may desire to install Drupal elsewhere.  To ensure that all command-line examples in this guide can be cut-and-pasted you **must** set the ``$DRUPAL_HOME`` variable.  You can set the variable in the following way:
+
+  .. code-block:: bash
+
+    DRUPAL_HOME=/var/www/html
+    
+Be sure to change the path ``/var/www/html`` to the location where you have installed Drupal.  If you have never installed Drupal and you intend on following this guide step-by-step then use the command-line above to get started.

docs/user_guide/example_genomics/pub_import.rst

@@ -1,5 +1,9 @@
 Importing Publications
 ======================
+.. note::
+
+  Remember you must set the ``$DRUPAL_HOME`` environment variable if you want to cut-and-paste the commands below. See :doc:`../drupal_home`
+  
 Tripal provides an interface for automatically and manually adding publications.
 
 Manually Adding a Publication
@@ -81,7 +85,7 @@ Next, there are two ways to import these publications. The first it to manually
 
 ::
 
-  cd /var/www/html
+  cd $DRUPAL_HOME
   drush trp-import-pubs --username=administrator
 
 You should see output to the terminal that begins like this:
@@ -105,7 +109,7 @@ Some things to know about the publication importer:
 
   ::
 
-    cd /var/www/html
+    cd $DRUPAL_HOME
     drush trp-run-jobs --user=administrator
 
 The second way to import publications is to add an entry to the UNIX cron. We did this previously for the Tripal Jobs management system when we first installed Tripal. We will add another entry for importing publications. But first, now that we have imported all of the relevant pubs, we need to return to the importers list at **Tripal → Data Loaders → Chado Publication Importers** and disable the first importer we created. We do not want to run that importer again, as we've already imported all historical publications on record at PubMed. Click the edit button next to the importer named Pubs for Citrus sinensis, click the disable checkbox and then save the template. The template should now be disabled.
@@ -120,11 +124,12 @@ Now add the following line to the bottom of the crontab:
 
 ::
 
-  30 8 1,15 * *  su - www-data -c '/usr/local/drush/drush -r /var/www/html -l http://[site url] trp-import-pubs --report=[your email] > /dev/null'
+  30 8 1,15 * *  su - www-data -c '/usr/local/drush/drush -r [DRUPAL_HOME] -l http://[site url] trp-import-pubs --report=[your email] > /dev/null'
 
 Where
 
 - [site url] is the full URL of your site
 - [your email] is the email address of the user that should receive an email containing a list of publications that were imported. You can separate multiple email addresses with a comma.
+- [DRUPAL_HOME] is the directory where Drupal is installed
 
 The cron entry above will launch the importer at 8:30am on the first and fifteenth days of the month. We will run this importer twice a month in the event it fails to run (e.g. server is down) at least one time during the month.

docs/user_guide/install_tripal/automating_job_execution.rst

@@ -1,6 +1,10 @@
 Automating Job Execution
 ========================================
 
+.. note::
+
+  Remember you must set the ``$DRUPAL_HOME`` environment variable if you want to cut-and-paste the commands below. See :doc:`../drupal_home`
+
 The Drupal cron is used to automatically execute necessary Drupal housekeeping tasks on a regular interval.  You should *always* setup the Drupal cron to ensure your site checks for updates and security issues.  To do this, we want to integrate Drupal cron with the UNIX cron facility.  The UNIX cron will automatically execute commands on set regular intervals.  First, we must get the appropriate URL for the cron by navigating to **Configuration → Cron**. On this page you will see a link that we will use for cron:
 
 .. image:: automating_job_execution.cron.png
@@ -36,9 +40,9 @@ Any job that is added to the Job's system can be run manually on the command lin
 
 .. code-block:: bash
 
-  drush trp-run-jobs --username=administrator --root=/var/www/html
+  drush trp-run-jobs --username=administrator --root=$DRUPAL_HOME
 
-Remember to change the username from **administrator** to the name of the administrator on your site and change **/var/www/html** to the location where your site installed on the server.
+Remember to change the username from **administrator** to the name of the administrator on your site.
 
 Option #2: Additional Cron Entry
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -53,7 +57,7 @@ Add this line to the crontab:
 
 .. code-block:: bash
 
-  0,5,10,15,20,25,30,35,40,45,50,55 * * * * drush trp-run-jobs --username=administrator --root=/var/www/html
+  0,5,10,15,20,25,30,35,40,45,50,55 * * * * drush trp-run-jobs --username=administrator --root=$DRUPAL_HOME
 
 Here, job execution will occur every 5 minutes.
 

docs/user_guide/install_tripal/manual_install/install_drupal.rst

@@ -35,11 +35,7 @@ Software Installation
 
 .. note::
 
-  The user's guide makes use the environmental variable ``$DRUPAL_HOME`` to track where Drupal will be installed.  The default location for Drupal is ``/var/www/html``, but set this variable to wherever you would like your Drupal site installed.  For example, older Ubuntu setups use ``/var/www`` instead.  To use ``/var/www/html``, execute the below command, or, replace the path with your desired location.  **YOU MUST SET THIS VARIABLE FOR THE BELOW GUIDE TO SUCCEED**.
-
-  .. code-block:: bash
-
-    DRUPAL_HOME=/var/www/html
+  Remember you must set the ``$DRUPAL_HOME`` environment variable if you want to cut-and-paste the commands below. See :doc:`../../drupal_home`
 
 
 Before we can install Drupal we must ensure that that we are allowed to add files into the root directory.  Select a user account that will be the owner of all web files and change the owner of the ``$DRUPAL_HOME`` directory to that user:

docs/user_guide/install_tripal/manual_install/install_prereqs.rst

@@ -3,12 +3,7 @@ Tripal Prerequisites
 
 .. note::
 
-  The user's guide makes use the environmental variable ``$DRUPAL_HOME`` to track where Drupal will be installed.  The default location for Drupal is ``/var/www/html``, but set this variable to wherever you would like your Drupal site installed.  For example, older Ubuntu setups use ``/var/www`` instead.  To use ``/var/www/html``, execute the below command, or, replace the path with your desired location.  **YOU MUST SET THIS VARIABLE FOR THE BELOW GUIDE TO SUCCEED**.
-
-  .. code-block:: bash
-
-    DRUPAL_HOME=/var/www/html
-
+  Remember you must set the ``$DRUPAL_HOME`` environment variable if you want to cut-and-paste the commands below. See :doc:`../../drupal_home`
 
 
 Tripal v3.x requires several Drupal modules. These include  `Entity <https://www.drupal.org/project/entity>`_,  `Views <https://www.drupal.org/project/views>`_, `CTools <https://www.drupal.org/project/ctools>`_, `Display Suite <https://www.drupal.org/project/ds>`_, `Field Group <https://www.drupal.org/project/field_group>`_, `Field Group Table <https://www.drupal.org/project/field_group_table>`_, `Field Formatter Class <https://www.drupal.org/project/field_formatter_class>`_ and `Field Formatter Settings <https://www.drupal.org/project/field_formatter_settings>`_ modules.   Modules can be installed using the graphical Drupal website by clicking on the Modules link in the top adminstrative menu bar.  Instructions for instaling Modules via the web-interface can be found here:  https://www.drupal.org/documentation/install/modules-themes/modules-7. However, Drush can be quicker for module installation. The following instructions will show how to install a module using the Drush command-line tool.

docs/user_guide/install_tripal/manual_install/install_tripal.rst

@@ -3,11 +3,7 @@ Tripal Installation
 
 .. note::
 
-  The user's guide makes use the environmental variable ``$DRUPAL_HOME`` to track where Drupal will be installed.  The default location for Drupal is ``/var/www/html``, but set this variable to wherever you would like your Drupal site installed.  For example, older Ubuntu setups use ``/var/www`` instead.  To use ``/var/www/html``, execute the below command, or, replace the path with your desired location.  **YOU MUST SET THIS VARIABLE FOR THE BELOW GUIDE TO SUCCEED**.
-
-  .. code-block:: bash
-
-    DRUPAL_HOME=/var/www/html
+  Remember you must set the ``$DRUPAL_HOME`` environment variable if you want to cut-and-paste the commands below. See :doc:`../../drupal_home`
 
 
 Before installation of Tripal, you must first have a working Drupal installation.  Please see the previous section of this tutorial for step-by-step examples for server setup and Drupal installation instructions.  After installation of Tripal, you may install any Tripal extension modules you may want.

docs/user_guide/install_tripal/rapid_install.rst

@@ -1,6 +1,11 @@
 Installation Method #1: Rapid Installation
 ==========================================
 
+.. note::
+
+  Remember you must set the ``$DRUPAL_HOME`` environment variable if you want to cut-and-paste the commands below. See :doc:`../drupal_home`
+
+
 Before installing via the rapid installation process please ensure drush is installed, and the server is setup.   Rapid Installation works with Tripal v3.0-rc2 (release candidate 2) and later.  If you are using a previous version of Tripal, please proceed to the step-by-step instructions.
 
 Database Setup
@@ -33,16 +38,6 @@ We no longer need to be the postgres user so exit
 Tripal Installation
 -------------------
 
-
-.. note::
-
-  The user's guide makes use the environmental variable ``$DRUPAL_HOME`` to track where Drupal will be installed.  The default location for Drupal is ``/var/www/html``, but set this variable to wherever you would like your Drupal site installed.  For example, older Ubuntu setups use ``/var/www`` instead.  To use ``/var/www/html``, execute the below command, or, replace the path with your desired location.  **YOU MUST SET THIS VARIABLE FOR THE BELOW GUIDE TO SUCCEED**.
-
-  .. code-block:: bash
-
-    DRUPAL_HOME=/var/www/html
-
-
 Navigate to your Drupal install directory.
 
 .. code-block:: bash

docs/user_guide/install_tripal/upgrade_from_tripal2.rst

@@ -141,7 +141,7 @@ The process allows you to create Tripal 3 content types exposing the same data a
 
   .. code-block:: bash
 
-    cd /var/www/html
+    cd $DRUPAL_HOME
     drush trp-run-jobs --user=administrator
 
 6. Now repeat 1-5 for each content type. Since this step simply creates new Tripal v3 content without touching the existing Tripal v2 content, there really is no reason not to migrate all your content types. Especially since the Tripal v3 content remains private and thus hidden from your users.

docs/user_guide/job_management.rst

@@ -1,6 +1,11 @@
 Job Management (Tripal Daemon)
 ==============================
 
+.. note::
+
+  Remember you must set the $DRUPAL_HOME environment variable to cut-and-paste the commands below. See see :doc:`drupal_home`
+
+
 The Tripal Daemon module is meant to provide a simple means of creating a robust command-line-driven, fully bootstrapped PHP Daemon. It uses the PHP-Daemon (https://github.com/shaneharter/PHP-Daemon) Library to create the Daemon (via the Libraries API) in order to not re-invent the wheel. It allows you to execute Jobs submitted to Tripal without using cron.  It provides a faster user experience for running jobs.  Prior to Tripal v3, the Tripal Daemon module was an extension module. It was integrated into the core Tripal pacakge.
 
 Features
@@ -27,7 +32,7 @@ Next, we need the `PHP-Daemon Library version 2.0 <https://github.com/shaneharte
 
 .. code-block:: shell
 
-  cd /var/www/html/sites/all/libraries
+  cd $DRUPAL_HOME/sites/all/libraries
   wget https://github.com/shaneharter/PHP-Daemon/archive/v2.0.tar.gz
   tar -zxvf v2.0.tar.gz
   mv v2.0.tar.gz PHP-Daemon

docs/user_guide/mviews.rst

@@ -1,6 +1,10 @@
 Materialized Views
 ==================
 
+.. note::
+
+  Remember you must set the ``$DRUPAL_HOME`` environment variable if you want to cut-and-paste the commands below. See :doc:`drupal_home`
+
 Chado is efficient as a data warehouse but queries can become slow depending on the type of query. To help simplify and speed up these queries, materialized views can be employed. For a materialized view, a new database table is created and then populated with the results of a pre-defined SQL query. This allows you to execute a much simpler and faster query on the materialized view when producing user pages. A side effect, however is redundant data, with the materialized view becoming stale if not updated regularly.
 
 Tripal provides a mechanism for populating and updating these materialized views. These can be found on the **Tripal → Data Storage → Chado -> Materialized Views** page.
@@ -13,7 +17,7 @@ This will submit jobs to populate the views with data. Now, run the jobs:
 
 .. code-block:: shell
 
-  cd /var/www/html
+  cd $DRUPAL_HOME
   drush trp-run-jobs --user=administrator
 
 You can now see that all views are up-to-date on the **Materialized Views Page**. The number of rows in the view table is shown.

docs/user_guide/web_services.rst

@@ -1,6 +1,10 @@
 Web Services
 ============
 
+.. note::
+
+  Remember you must set the ``$DRUPAL_HOME`` environment variable if you want to cut-and-paste the commands below. See :doc:`drupal_home`
+
 Overview
 --------
 
@@ -31,7 +35,7 @@ To enable web services, simply install the ``tripal_ws`` module, either using th
 
 .. code-block:: shell
 
-  cd /var/www/html
+  cd $DRUPAL_HOME
   drush pm-enable tripal_ws
 
 Exploring Web Services