Merge pull request #43 from CollectionBuilder/transcript-update

Transcript update

_change-log/transcript-update.md

@@ -0,0 +1,10 @@
+---
+title: object_transcript convention update
+release: 2023-10-16
+---
+
+The convention for referencing files in the "object_transcript" field has been updated to follow the relative url convention used in other object fields.
+A reference to a local transcript file should now always start with a `/`, (e.g. `/objects/demo_01.md`).
+Template logic also now supports including transcript files from any folder in the project repository (e.g. `/transcripts/example.txt` or `/text/demo_003.md`, etc).
+
+See [CB-CSV metadata docs]({{ '/docs/metadata/csv_metadata/#object_transcript' | relative_url }}) for details.

docs/metadata/csv_metadata.md

@@ -131,21 +131,21 @@ You will need to use the correct file paths or URLs for your objects. Here are s
 
 - A text transcript of the item's content. This is most commonly used with video and audio items, but can be for any item type.
 - The transcript content can be added in two ways: 
-    1. Add the full text as the value directly in the field. This is a straight forward way to keep transcript data directly in your metadata. Keep in mind that spreadsheet software typically has limits on the number of characters per cell, so this won't work well with larger transcripts. 
-    2. Add the transcript as a text file (.txt or .md) in your project's "objects" folder and put the filename and relative path as the value of `object_transcript`. For example, `objects/transcript1.txt`. See below for more information on preparing a transcript file.
+    1. Add the full text as the value directly in the field. This is a straight forward way to keep transcript data directly in your metadata. Keep in mind that spreadsheet software typically has limits on the number of characters per cell, so this won't work well with larger transcripts. Note the value can *not* start with `/`!
+    2. Add the transcript as a text file (.txt or .md) in your project repository (usually the "objects" folder) and put the relative path and filename as the value of `object_transcript`. For example, `/objects/transcript1.txt` or `/text/demo_01.md`. The relative path *must* start with `/`. See below for more information on preparing a transcript file.
 - The contents of the field or the transcript file will be rendered as Markdown on the Item page.
 - Example value in cell: `Temperatures 85 to 90 in valleys, 70 to 75 ridges. Minimum humidity 15 to 25 percent valleys and 22 to 32 percent ridges. 20 foot winds at lower elevations Northwest, 5 to 15 miles per hour. Ridge top, Northwest, 5 to 15 miles per hour.`
-- Example value in transcript text file: `objects/demo_003.md`
+- Example value in transcript text file: `/objects/demo_003.md`
 
 Preparing transcripts:
 
 - Providing a transcript for audio and video items is an essential accessibility and useability feature to ensure all users can access the information contained in the media. We strongly recommend video items *also* include in video captioning, which can be automatically provided by YouTube or Vimeo.
 - When creating transcripts, consider the information they convey to users. Basic transcripts record the audio information only. Descriptive transcripts also record visual information beyond the speakers. Basic transcripts can be started using automated services or downloading captions from YouTube, and are then often cleaned up and edited. See [WAI transcripts tips](https://www.w3.org/WAI/media/av/transcripts/) for more information.
 - To prepare a transcript text file:
     - Create a ".txt" or ".md" file following the general [filenaming conventions]({{ '/docs/objects/csv-objects/#object-guidelines-for-collectionbuilder-csv' | relative_url }}). It is often desireable to follow a naming convention that links the transcript to the main item, such as using it's objectid.
-    - Add the file to your project's "objects" folder. These can be grouped in a folder inside the "objects" folder if desired, such as "objects/transcripts/".
+    - Add the file to a folder in your project repository (such as the "objects" folder). These can be grouped in a subfolder if desired, such as "/objects/transcripts/".
     - Ensure that the file has YAML front matter at the top of the file so that it will be processed by Jekyll (the front matter can be empty, i.e. `---` line break `---`).
-    - Add the relative path (`objects/`) and filename to the `object_transcript` field, e.g. `objects/demo_003.md`.
+    - Add the relative path (e.g. `/objects/`) and filename to the `object_transcript` field, e.g. `/objects/demo_003.md`.
     - During site build, the transcript text will be retrieved from the file and rendered as Markdown.
 
 ### format: 

docs/software/jekyll.md

@@ -26,10 +26,10 @@ This process will take awhile as Gem installs all the dependencies and builds ex
 On Windows it may appear as if nothing is happening for a very very long time, since the terminal does not provide a progress bar, be patient!
 {:.alert .alert-yellow}
 
+Your dev environment is ready! Give yourself a hand!
+
 **Debugging Note:** 
 if you have **Ruby version 3.0+** and **Jekyll version 4.2.0** or less, when using Jekyll you may encounter an error in your terminal including "cannot load such file -- webrick (LoadError)".
 First, the CB template "Gemfile" includes `webrick`, so make sure you are using `bundle exec jekyll s`.
 If that doesn't help or you are using an older template, please try installing webrick globally using `gem install webrick` *or* adding it to your project Gemfile using `bundle add webrick` in the project directory.
 {:.alert .alert-red}
-
-Your dev environment is ready! Give yourself a hand!

docs/software/ruby.md

@@ -19,10 +19,16 @@ Depending on your operating system (i.e. Mac), this might be the most complicate
 
 These approaches that have worked for us, but you may want to refer to Jekyll's official [installation guides](https://jekyllrb.com/docs/installation/) for more tips!
 
-{:.alert .alert-yellow}
+## Ruby Install Tips 
+
+{:.alert .alert-red}
 Did you install Ruby and Jekyll a long time ago, but never updated it?
 Issues and conflicts with old versions of Ruby and Jekyll are common stumbling blocks we encounter when teaching.
 Although uninstalling your existing versions can be confusing and frustrating process if you don't remember how you installed it in the first place, it is a good idea to get a fresh start to ensure you have working and up to date versions.
 
 {:.alert .alert-purple}
 If you change or update Ruby versions and end up with bundler errors when you try to use Jekyll--deleting the old "Gemfile.lock" in your repository is usually a quick fix.
+
+{:.alert .alert-yellow}
+Gem is a tool to install Ruby Gems packages on your system that comes with Ruby. 
+If you have an existing Ruby install or are encountering errors, it is a good idea to ensure Gem is up to date using: `gem update --system`