4326 doc examples replace fixes

doc/sphinx-guides/source/api/dataaccess.rst

@@ -27,9 +27,11 @@ Value           Description
 ==============  ===========
 original        "Saved Original", the proprietary (SPSS, Stata, R, etc.) file from which the tabular data was ingested;
 RData           Tabular data as an R Data frame (generated; unless the "original" file was in R);
-prep		"Pre-processed data", in JSON. (TODO: *get a proper description of the feature from James/Vito*)
+prep		"Pre-processed data", in JSON.
 ==============  ===========
 
+---------------------------
+
 ``imageThumb``
 
 the following parameter values are supported (for image and pdf files only): 
@@ -41,6 +43,8 @@ true            Generates a thumbnail image, by rescaling to the default thumbna
 ``N``           Rescales the image to ``N`` pixels.
 ==============  ===========
 
+---------------------------
+
 ``vars``
 
 For column-wise subsetting (available for tabular data files only).

doc/sphinx-guides/source/api/native-api.rst

@@ -244,7 +244,7 @@ For example, after making your edits, your JSON file might look like :download:`
 
     curl -H "X-Dataverse-key: $API_TOKEN" -X PUT $SERVER_URL/api/datasets/:persistentId/versions/:draft?persistentId=$PID --upload-file dataset-update-metadata.json
 
-Note that in example JSON file above, there is a single JSON object with ``metadataBlocks`` as a key. When you download a representation of your dataset in JSON format, the ``metadataBlocks`` object you need is nested inside another object called ``json``. To extract just the ``metadataBlocks`` key when downloading a JSON representation, you can use a tool such as ``jq`` like this::
+Note that in the example JSON file above, there is a single JSON object with ``metadataBlocks`` as a key. When you download a representation of your dataset in JSON format, the ``metadataBlocks`` object you need is nested inside another object called ``json``. To extract just the ``metadataBlocks`` key when downloading a JSON representation, you can use a tool such as ``jq`` like this::
 
     curl -H "X-Dataverse-key: $API_TOKEN" $SERVER_URL/api/datasets/:persistentId/versions/:latest?persistentId=$PID | jq '.data | {metadataBlocks: .metadataBlocks}' > dataset-update-metadata.json
 
@@ -332,7 +332,7 @@ A more detailed "add" example using curl::
 
 Example python code to add a file. This may be run by changing these parameters in the sample code:
 
-* ``dataverse_server`` - e.g. https://dataverse.harvard.edu
+* ``dataverse_server`` - e.g. https://demo.dataverse.org
 * ``api_key`` - See the top of this document for a description
 * ``persistentId`` - Example: ``doi:10.5072/FK2/6XACVA``
 * ``dataset_id`` - Database id of the dataset
@@ -466,11 +466,11 @@ Replace an existing file where ``id`` is the database id of the file to replace.
 
 A more detailed "replace" example using curl (note that ``forceReplace`` is for replacing one file type with another)::
 
-    curl -H "X-Dataverse-key:$API_TOKEN" -X POST -F 'file=@data.tsv' -F 'jsonData={"description":"My description.","categories":["Data"],"forceReplace":false}' "https://example.dataverse.edu/api/files/$FILE_ID/replace"
+    curl -H "X-Dataverse-key:$API_TOKEN" -X POST -F 'file=@data.tsv' -F 'jsonData={"description":"My description.","categories":["Data"],"forceReplace":false}' "https://demo.dataverse.org/api/files/$FILE_ID/replace"
 
 Example python code to replace a file.  This may be run by changing these parameters in the sample code:
 
-* ``dataverse_server`` - e.g. https://dataverse.harvard.edu
+* ``dataverse_server`` - e.g. https://demo.dataverse.org
 * ``api_key`` - See the top of this document for a description
 * ``file_id`` - Database id of the file to replace (returned in the GET API for a Dataset)
 

doc/sphinx-guides/source/api/sword.rst

@@ -45,21 +45,21 @@ Differences in Dataverse 4 from DVN 3.x lead to a few minor backward incompatibl
 New features as of v1.1
 -----------------------
 
-- Dataverse 4 supports API tokens and they must be used rather that a username and password. In the ``curl`` examples below, you will see ``curl -u $API_TOKEN:`` showing that you should send your API token as the username and nothing as the password. For example, ``curl -u 54b143b5-d001-4254-afc0-a1c0f6a5b5a7:``.
+- Dataverse 4 supports API tokens and requires them to be used for APIs instead of a username and password. In the ``curl`` examples below, you will see ``curl -u $API_TOKEN:`` showing that you should send your API token as the username and nothing as the password. For example, ``curl -u 54b143b5-d001-4254-afc0-a1c0f6a5b5a7:``.
 
-- SWORD operations no longer require "admin" permission. In order to use any SWORD operation in DVN 3.x, you had to be "admin" on a dataverse (the container for your dataset) and similar rules were applied in Dataverse 4.4 and earlier (the ``EditDataverse`` permission was required). The SWORD API has now been fully integrated with the Dataverse 4 permission model such that any action you have permission to perform in the GUI or "native" API you are able to perform via SWORD. This means that even a user with a "Contributor" role can operate on datasets via SWORD. Note that users with the "Contributor" role do not have the ``PublishDataset`` permission and will not be able publish their datasets via any mechanism, GUI or API.
+- SWORD operations no longer require "admin" permission. In order to use any SWORD operation in DVN 3.x, you had to be an "admin" on a dataverse (the container for your dataset) and similar rules were applied in Dataverse 4.4 and earlier (the ``EditDataverse`` permission was required). The SWORD API has now been fully integrated with the Dataverse 4 permission model such that any action you have permission to perform in the GUI or "native" API you are able to perform via SWORD. This means that even a user with a "Contributor" role can operate on datasets via SWORD. Note that users with the "Contributor" role do not have the ``PublishDataset`` permission and will not be able publish their datasets via any mechanism, GUI or API.
 
 - Dataverses can be published via SWORD.
 
-- Datasets versions will only be increased to the next minor version (i.e. 1.1) rather than a major version (2.0) if possible. This depends on the nature of the change. Adding or removing, a file, for example, requires a major version bump.
+- Datasets versions will only be increased to the next minor version (i.e. 1.1) rather than a major version (2.0) if possible. This depends on the nature of the change. Adding or removing a file, for example, requires a major version bump.
 
 - "Author Affiliation" can now be populated with an XML attribute. For example: <dcterms:creator affiliation="Coffee Bean State University">Stumptown, Jane</dcterms:creator>
 
 - "Contributor" can now be populated and the "Type" (Editor, Funder, Researcher, etc.) can be specified with an XML attribute. For example: <dcterms:contributor type="Funder">CaffeineForAll</dcterms:contributor>
 
 - "License" can now be set with dcterms:license and the possible values are "CC0" and "NONE". "License" interacts with "Terms of Use" (dcterms:rights) in that if you include dcterms:rights in the XML, the license will be set to "NONE". If you don't include dcterms:rights, the license will default to "CC0". It is invalid to specify "CC0" as a license and also include dcterms:rights; an error will be returned. For backwards compatibility, dcterms:rights is allowed to be blank (i.e. <dcterms:rights></dcterms:rights>) but blank values will not be persisted to the database and the license will be set to "NONE".
 
-- "Contact E-mail" is automatically populated from dataset owners email.
+- "Contact E-mail" is automatically populated from dataset owner's email.
 
 - "Subject" uses our controlled vocabulary list of subjects. This list is in the Citation Metadata of our User Guide > `Metadata References <http://guides.dataverse.org/en/latest/user/appendix.html#metadata-references>`_. Otherwise, if a term does not match our controlled vocabulary list, it will put any subject terms in "Keyword". If Subject is empty it is automatically populated with "N/A".
 

doc/sphinx-guides/source/developers/index.rst

@@ -12,6 +12,7 @@ Developer Guide
 
    intro
    dev-environment
+   windows
    tips
    troubleshooting
    version-control

doc/sphinx-guides/source/developers/tips.rst

@@ -76,6 +76,27 @@ Netbeans Connector Chrome Extension
 
 For faster iteration while working on JSF pages, it is highly recommended that you install the Netbeans Connector Chrome Extension listed in the :doc:`tools` section. When you save XHTML or CSS files, you will see the changes immediately. Hipsters call this "hot reloading". :)
 
+Database Schema Exploration
+---------------------------
+
+With over 100 tables, the Dataverse PostgreSQL database ("dvndb") can be somewhat daunting for newcomers. Here are some tips for coming up to speed.
+
+pgAdmin3
+~~~~~~~~
+
+Back in the :doc:`dev-environment` section, we had you install pgAdmin3, which can help you explore the tables and execute SQL commands. It's also listed in the :doc:`tools` section.
+
+SchemaSpy
+~~~~~~~~~
+
+SchemaSpy is a tool that creates a website of entity-relationship diagrams based on your database.
+
+As part of our build process for running integration tests against the latest code in the "develop" branch, we drop the database on the "phoenix" server, recreate the database by deploying the latest war file, and run SchemaSpy to create the following site: http://phoenix.dataverse.org/schemaspy/latest/relationships.html
+
+To run this command on your laptop, download SchemaSpy and take a look at the syntax in ``scripts/deploy/phoenix.dataverse.org/post``
+
+To read more about the phoenix server, see the :doc:`testing` section.
+
 Deploying With ``asadmin``
 --------------------------
 

doc/sphinx-guides/source/developers/tools.rst

@@ -13,6 +13,11 @@ Netbeans Connector Chrome Extension
 The `Netbeans Connector <https://chrome.google.com/webstore/detail/netbeans-connector/hafdlehgocfcodbgjnpecfajgkeejnaa?hl=en>`_ extension for Chrome allows you to see changes you've made to HTML pages the moment you save the file without having to refresh your browser. See also 
 http://wiki.netbeans.org/ChromeExtensionInstallation
 
+pgAdmin3
+++++++++
+
+You probably installed pgAdmin3 when following the steps in the :doc:`dev-environment` section but if not, you can download it from https://www.pgadmin.org
+
 Maven
 +++++
 

doc/sphinx-guides/source/developers/version-control.rst

@@ -67,7 +67,7 @@ If you tell us your GitHub username we are happy to add you to the "read only" t
 Create a New Branch off the develop Branch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Always create your feature branch from the latest code in develop, pulling the latest code if necessary. As mentioned above, your branch should have a name like "3728-doc-apipolicy-fix" that starts with the issue number you are addressing, and ends with a short, descriptive name.
+Always create your feature branch from the latest code in develop, pulling the latest code if necessary. As mentioned above, your branch should have a name like "3728-doc-apipolicy-fix" that starts with the issue number you are addressing, and ends with a short, descriptive name. Dashes ("-") and underscores ("_") in your branch name are ok, but please try to avoid other special characters such as ampersands ("&") than have special meaning in Unix shells.
 
 Commit Your Change to Your New Branch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/sphinx-guides/source/developers/windows.rst

@@ -1,6 +1,6 @@
-=======
-Windows
-=======
+===================
+Windows Development
+===================
 
 Development on Windows is not well supported, unfortunately. You will have a much easier time if you develop on Mac or Linux as described under :doc:`dev-environment` section.