Add note about new publisher field. (#2293)

* Add publisher note.

* Add instructions on adding a new field.

docs/user-documentation/metadata.md

@@ -218,12 +218,34 @@ The list of available relations for this Contributors field is configurable at '
     - If you apply this field to another content type, you can define unique relations available for that instance of the field.
     - However, multiple instances of this field means administrative overhead to maintain the separate lists of relations defined for each instance.
 
+!!! Note "Publishers"
+    Until Mar 2024, the Islandora Starter Site included publishers in the Contributors (`field_linked_agent`) field. The MIG made the decision to make publisher
+    its own text field, in order to make it easier to separate publishers from other contributors, and to prevent clutter in the linked taxonomies. Publishers
+    are often recorded by transcribing what is on the item, rather than formatting the name per Authority rules, so variations on a single name are expected. 
+
 Relations are defined in the format *key\|value*, and the key is used in the RDF mapping (see below).
 
 ![Screenshot of the 'Available Relations' configuration text box for the 'Contributor' field.](../assets/metadata_available_relations_config.png)
 
 By default, facets can be created for typed relation fields that will facet based on the linked entity alone, not separating references based on the relationship type.
 
+## Adding a new field
+
+You are free to add new fields to your Islandora content type(s). After you set one up, you may want to configure the following:
+
+* **Form Display** - set the field to display (or not) in your form, and set its widget, at  **Administration** \>\> **Structure** \>\> **Content types** \>\> [Your Content Type] \>\> **Manage form display**. You can also set it to display (or not) to certain users based on Field permissions at **Administration** \>\> **Structure** \>\> **Content types** \>\> [Your Content Type] \>\> **Manage fields** \>\> [Your new field].
+* **Display** - set the field to display (or not) to the public at **Administration** \>\> **Structure** \>\> **Content types** \>\> [Your Content Type] \>\> **Manage display**. You can also set it to display or not to certain users based on Field permissions at **Administration** \>\> **Structure** \>\> **Content types** \>\> [Your Content Type] \>\>  **Manage fields** \>\> [Your new field].
+* **Solr** - Solr configuration is set at **Administration** \>\> **Configuration** \>\> **Search and metadata** \>\> **Search API** \>\> [Default Solr content index] \>\> **Fields**.
+By default, Solr indexes the "Rendered Item" using the display mode "Search index". By default, the "Search index" display mode is not configured separately, so it renders using the "Default" display mode which is the default (or only) tab when configuring Display, above. This means that if you configured your new field to display, then it will be automatically available to fulltext search. But if you want to make a facet, or a fielded search (using Advanced Search), then you need to index the field separately, as either String (for a facet) or fulltext (for a fielded search). To do this, use the "**+ Add field**" button in the Solr configuration and select your field, under the "Content" section. If it is a reference field (such as a taxonomy term field or a related item field) then you may want to "dive down" using the "(+)" buttons to index the name or title of the referenced entity.
+* **Facet** - to make a facet, index the field as a string field (above). Then, create the facet at  **Administration** \>\> **Configuration** \>\> **Search and metadata** \>\> **Facets**. Finally, configure the facet to display by placing the corresponding block in the desired region.
+* **Fielded Search** - to make your new field one of the drop-downs in the Advanced Search block, first index it in Solr as fulltext (as above). Find the Advanced Search block and click "Configure" and then drag and drop your new field into the non-hidden section. Save the block config.
+* **RDF** - In the following section ("Getting Metadata into Fedora and a Triple-Store") we discuss how to index a field using Drupal's RDF mappings. You will want to do this if you are using Fedora or a Triple-store, or if you are using RDF to generate OAI-PMH DC data.
+* **OAI-PMH MODS** - if you are using OAI-PMH to generate MODS for each object, you can configure how this field displays by setting it in the appropriate View, by default "OAI PMH Item Data". After adding the field, give it a label that matches the `rest_oai_pmh` module's [`templates/mods.html.twig`](https://git.drupalcode.org/project/rest_oai_pmh/-/blob/2.0.x/templates/mods.html.twig). For example, that template file includes `{{ elements.publisher }}` so the label in views needs to be exactly `publisher`. Save the View.
+* **Citation CSL Mapping** - To let a new field be used in the creation of citations with Citation Select, navigate to the Citation CSL Settings (as of Citation Select version 2.0, this is at  **Administration** \>\> **Configuration** \>\> **Citation Select Settings** \>\> **CSL Mappings**. Select your new field where applicable.
+
+An example of this, in terms of config changes, is visible in the [changeset of the Starter Site's 1.6.0 version](https://github.com/Islandora-Devops/islandora-starter-site/compare/1.5.0...1.6.0) for the Publisher field. However, pulling such a changeset is unlikely to work smoothly and it is recommended to set these configurations manually.
+
+
 ## Getting Metadata into Fedora and a Triple-store
 
 Depending on the needs at your institution, you may or may not be using Fedora with your Islandora installation. You also may or may not be hoping to publish your metadata as RDF triples that can be queried in a triplestore. Both of these functionalities are driven by the JSON-LD module (written for Islandora), which provides a JSON-LD serialization of your content nodes, media nodes, as well as your taxonomy terms. This JSON-LD is what gets ingested by Fedora, and is also what is used to add RDF triples to the [blazegraph triplestore](https://islandora.github.io/documentation/installation/manual/installing_fedora_syn_and_blazegraph/) if you choose to use that service.