TUTORIAL.md 3.46 KB

A Short Calcyte Tutorial

This is a short tutorial on using Calcyte.

Audience

This tutorial is for people who are capable of:

  • Installing a python3 package
  • Using the commandline

What is Calcyte?

Calcyte is a system to help you manage, describe and document collections of data. so that you, at a much later time, or someone else, can understand what they are and what they contain. It does this by providing you with a simple command line program called calcify.

Calcify can be run over a single directory or recursively descend into directories. It creates simple spreadsheets with fields for describing all your files and directories. You then fill in those spreadsheets with the knowledge that you have about the files and directories.

Calcify can then be re-run and it will create automagically for you HTML pages with links to, and between, files and metadata, and JSON files containing the same information but suitable for parsing by computers or for publishing to the Web.

How to create this HTML file.

pandoc --smart --toc -H TUTORIAL.css -s -o TUTORIAL.html TUTORIAL.md

Installation

Enter a virtual python environment for running Calcyte:

calcyte/$ source ~/virtualenvs/calcyte/bin/activate
(calcyte)calcyte/$

Usage

Show help for Calcyte:

usage: calcify [-h] [--autofill] [--catalog-stem CATALOG_STEM]
    [--recurse] [--yaml]
    dir

required arguments:
  dir                   Directory to search for metadata.

optional arguments:
  --catalog-stem CATALOG_STEM, -s CATALOG_STEM
  --help, -h            Show this help message and exit.
  --recurse, -r         Recurse into sub-directories. Default is not to recurse.

Run calcyte over the current directory:

$ ./calcify Victoria_Arch_mlake_test

Two catalog files and a index.html file will be created if they did not exist before. By default sub-directories will not be recursed into.

CATALOG.xlsx -- A catalog in a spreadsheet format, listing all the files and directories
                together with fields for entering their metadata.
CATALOG.json -- The catalog in JSON format for machine parsing.
index.html   -- A HTML index with useful links to all the files, directories and their metadata.

A newly created catalog file CATALOG.xlsx is just an Excel spreadsheet that has been created with some sheets (Collection & Files) and the "Files" sheet has been pre-filled with the filenames found in the directory. You can edit this and fill it out with more information. This will not be overwritten if it already exists.

The CATALOG.json contains the metadata extracted from the CATALOG.xlsx but in machine parsable JSON format (https://en.wikipedia.org/wiki/JSON). It is updated on each run from the catalog metadata so it's always up-to-date with the information in the catalog files.

An index.html file will also be created. Like the JSON file, it is updated on each run from the catalog metadata.

Run calcyte recursively from a directory:

$ ./calcify -r Victoria_Arch_mlake_test

Configuration Files

Calcify will look for configuration files called calcify.conf. It will look first in the directory to parse i.e. the directory you specified on the command line. Next it will look in the current directory. It will use the first conf file it finds.

If it does not find any configuration files then it will use defaults that are in the source code.

TODO

defaults/CATALOG.xlsx Collection, Items defaults/CATALOG.xlsx Dictionary, Namespaces