Digital Edition of Fernando Pessoa
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
app
scripts
.gitignore
README.md
build.xml
collection.xconf
conf.xml
gulpfile.js
notinDRAE.xml
package.json

README.md

Digital Edition of Fernando Pessoa

Projects and Publications

This is the Github repository accompanying the Digital Edition of Fernando Pessoa's Projects and Publications.

Resulting from a collaboration between researchers of the Estranging Pessoa research project, based in IELT (Institute for the Study of Literature and Tradition), New University of Lisbon, and the CCeH (Cologne Center for eHumanities), University of Cologne, the digital edition aims at offering a unique access to the documents of Fernando Pessoa’s work.

The results of this work will be published on http://pessoadigital.pt in 2017.

Workflow

Development for the Pessoa edition is done using a local eXist instance. You will work on a local copy of the source code which is deployed to your local eXist after every change you want to test. Please do not use the eXist feature of the Oxygen editor to directly modifiy the files inside the database as this will inevitably lead to chaos when working collaboratively using git.

By using the gulp watch task as described below, this is really more convenient than it sounds.

Setting up the development environment

Install git

  • On Linux: Use your package manager
  • On Mac: git comes pre-installed
  • On Windows: Install (Git for Windows)[https://git-scm.com/download/win] and preferably choose "Use Git from the Windows Command Prompt" during installation

Install eXist-db

You will need to have installed Java 7 or higher.

Get eXist-db 2.2 from here. For Mac, run the installer in the .dmg file. For Windows and Linux, get the .jar, open up a terminal and run

java -jar exist-db-setup-2.2.jar

Install Node.js

The Node.js package manager npm is used to manage the development tools.

On Windows:

Get it here and install the package.

On Mac:

The preferred way:

  1. Install the Homebrew package manager

  2. Install node:

    brew install node

The other way:

  • Download it from here and install the package

On Linux

You are using Linux. You'll find out how to install node.js

Getting the source code

git clone https://github.com/cceh/pessoa

Installing the development tools

We are going to install gulp which will be our build and deployment tool, and bower, which will manage the dependencies of our webapp like bootstrap and jquery.

cd pessoa

# globally install gulp and bower
npm install -g gulp

# locally install development dependencies
npm install

The last command will read the dev dependencies specified in package.json and install them inside node_modules.

Configuring deployment to eXist

Copy the deployment configuration from the internal Wiki and save it as exist-secrets.js

If your local eXist configuration differs, adjust accordingly.

Deploying the app to your local eXist

Now you should have everything together to deploy the pessoa app to your local eXist

gulp deploy-local

Creating the index

The Pessoa app needs a working database index. Use

gulp update-index

to create it.

Everytime there is a change in collection.xconf, (e.g. after a git pull), you need to update the index using this command.

If there was no error, you should have a working pessoa instance at http://localhost:8080/exist/apps/pessoa (or similar).

Working with gulp

During development, you will be using the gulp build tool to run common tasks.

Watchers

This is a huge time saver during development. Open up a terminal and run

gulp watch

Now edit a source file, save it and watch it magically being uploaded to eXist! This will also work for SCSS files, which are automatically compiled and then uploaded.

Deployment

Everytime you edited something (and you are not using the watcher) or pulled new code from git, you need to deploy it to your local eXist instance by running

gulp deploy-local

This will process everything in the ./app folder and copy the resulting files to ./build. Only files that are newer than the ones already in the eXist database are uploaded. If you desperately want to re-upload a file, you can use (on Mac or Linux or Windows with bash):

touch path/to/file.xml
gulp deploy-local

Note: eXist 2.2 has an annoying bug that causes it to freeze occasionally when uploading an XQuery file. If you see an upload taking a unusually long time, kill and restart eXist-db. Then get some coffee while eXist will run its recovery and reindex all database files. You also need to restart gulp watchif that happens.

Indexing

Use

gulp update-index

to re-create the index when you have modified collection.xconf.

Creating a XAR archive

In case you want to build a xar archive that can be imported into eXist using the package manager, use

gulp xar