layout	default
nav_exclude	true
search_exclude	true
permalink	/README

Archive of Pittsburgh Language and Speech (APLS)

The GitHub repository djvill/APLS hosts documentation and files for users of the Archive of Pittsburgh Language and Speech aka APLS (pronounced like apples). It powers the website djvill.github.io/APLS and APLS 'splash page' apls.pitt.edu, both of which are hosted by GitHub Pages. This repository (unlike APLS itself) is licensed CC BY-NC-SA 4.0.

If you're looking for the APLS homepage, please visit apls.pitt.edu. The APLS corpus is at apls.pitt.edu/labbcat. This README page describes the repository itself, which may be of interest to developers.

This repo is still very much a work in progress. However, I anticipate it'll contain info for not only end-users, but also transcribers and corpus maintainers.

GitHub Pages/Jekyll

The public-facing pages are built and deployed to djvill.github.io/APLS using GitHub Pages. The page source is built from the main branch's root directory, using the "deploy from a branch" workflow. This repo uses the just-the-docs theme.

This repo only contains a few Jekyll files for customizing just-the-docs (e.g., overwriting _config.yml). As a result, the repo doesn't have all the files to preview the page locally (i.e., with bundle exec jekyll serve). I decided this limitation was worth not clogging up the repository with a ton of Jekyll code.

Pre-commit hook

This repo works best with a pre-commit hook that does two things:

• Populates/modifies the last_modified_date YAML parameter for Markdown files that have this parameter in their headers
  • Rendered pages include this date in their footer
  • To suppress this for a given page, just don't add last_modified_date to the header.
• Throws an error if the Jekyll theme is set incorrectly in _config.yml, to catch an un-runnable commit before it gets pushed to GitHub
  • If building locally, theme parameter needs to be set and remote_theme cannot be set
  • If building on GitHub Pages, it's the opposite

This hook does not get cloned with the repo. If you clone this repo, copy the following into .git/hooks/pre-commit:

#!/bin/sh
# Pre-commit hook for https://github.com/djvill/APLS

# Replace `last_modified_date` timestamp with current time
# Credit: https://mademistakes.com/notes/adding-last-modified-timestamps-with-git/
timestamp () {
  # If there are unstaged changes (i.e. from git add -p), stash them first, then unstash them after adding last_modified_date
  patched=$(git diff --name-status | grep $1)
  [ "$patched" ] && git stash push -kq -m "Pre-commit hook - $1" -- $1
  # Change last_modified_date in staged version of file
  cat $1 | sed -b "/---.*/,/---.*/s/^last_modified_date:[0-9Tz: -]*\(\r\?\)$/last_modified_date: $(date "+%Y-%m-%dT%H:%M:%S%:z")\1/" > tmp
  mv tmp $1
  git add $1
  # Unstash if needed
  [ "$patched" ] && git stash pop -q
}
# Added/modified files
git diff --staged --name-status | egrep -i "^(A|M).*\.(md)$" | while read a b; do
  if grep -q ^last_modified_date $b ; then
    timestamp $b
  fi
done
# Renamed files
git diff --staged --name-status | egrep -i "^R.*\.(md)$" | while read a b c; do
  if grep -q ^last_modified_date $c ; then
    timestamp $c
  fi
done

# Ensure *staged version* of _config.yml has Jekyll theme options set correctly
theme=$(git show :_config.yml | grep ^theme)
remotetheme=$(git show :_config.yml | grep ^remote_theme)
if [ -n "$theme" ] || [ -z "$remotetheme" ] ; then
  echo "ERROR: Commit not completed."
  echo "  Ensure _config.yml has theme commented-out and remote_theme uncommented."
  echo "  Then try committing again."
  exit 1
fi

# N.B. From https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_client_side_hooks:
#   It’s important to note that client-side hooks are not copied when you clone a 
#   repository. If your intent with these scripts is to enforce a policy, you’ll 
#   probably want to do that on the server side; see the example in An Example Git-
#   Enforced Policy. (https://git-scm.com/book/en/v2/Customizing-Git-An-Example-Git-Enforced-Policy#_an_example_git_enforced_policy)

Solution courtesy of https://mademistakes.com/notes/adding-last-modified-timestamps-with-git/.

Sass deprecation patch

As of just-the-docs version 0.10.0, building the site locally will yield deprecation warnings about Sass darken(): just-the-docs/just-the-docs#1541. As a patch for these deprecation warnings, modify Gemfile.lock so it pins the sass-embedded gem to version 1.78.0.

Repo contents

• _includes/: Content stubs (see Jekyll doc)
• _layouts/: Page layouts (see Jekyll doc)
• _sass/: Sass partials (see Jekyll doc)
• assets/: Site assets (CSS, JavaScript, image files)
• doc/: Documentation---the meat of the public-facing website
• files/: Files relevant to the corpus
  • custom-dictionary/: Custom dictionary entries
  • layer-scripts/: Script files for APLS layers annotated by Python layer manager
• ./ (this folder):
  • .gitignore: For Git version control
  • _config.yml: Site configuration file (see Jekyll doc)
  • _todo.md: Site maintenance to-do list
  • 404.md: Custom "Page not found" error page (see Jekyll doc)
  • LICENSE.md: Markdown conversion of legal code for CC BY-NC-SA 4.0 license
  • README.md: What you're reading right now!
  • SPLASH.md: APLS homepage (aka splash page), injected via <iframe> into apls.pitt.edu