Setup

This page is intended to guide team members to a stable setting to work for the project

You will need:

  1. an account in GIT (github.com)
  2. Atom (or oXygen with a licence for it)
  3. an account in Zotero

GITHUB

Git is a shared repo, public on the web, where we keep our project files and code. Our organization in GitHub.com contains several repositorires, which are just like folders from a user perspective. Here are the files we work on and the documentation, such as guidelines and issue tracking. You will use this to:

  1. Keep your files in sync with others

  2. Point out issues, problems requests

You will want to be always up to date. Here is what to do:

  • After you created and verified your account, you will need to be added to the group; email Pietro to get this done.

  • Install Github desktop

  • Prepare in your computer, in a location of your choice, a folder called BetMas

  • Open Gihub desktop

  • Login with your Github user name and password

  • Clone repositories from the application, if you are logged and have accepted the invitation to the group, the software will know that you are part of the Beta Masaheft organization and offer that among your possibilities.

  • Select the group Beta Masaheft organization

  • Select the schema repository

  • Click CLONE below

  • Select the folder BetMas on your machine as target location and say ok

  • This will create a folder called schema into your BetMas folder which is identical to that in Git and can be synced with it if you are online

  • Repeat the same operation for the repositories with the data that you need, most typically Manuscript, Persons, Places, Institutions and Works

If you use the new version GitHub beta:

  • After you created and verified your account, you will need to be added to the group. email Pietro to get this done.

  • Install Github desktop

  • Prepare in your computer in a location of your choice a folder called BetMas

  • Ppen Gihub desktop

  • Login if you aren't automatically logged in

  • Click "file" on the top left corner

  • Select "clone repository"

  • In your browser, go to https://github.com/BetaMasaheft

  • Click on "Manuscripts"

  • Add the URL (https://github.com/BetaMasaheft/Manuscripts) to Github Desktop

  • In "Local path", select the folder BetMas

  • Click CLONE below

  • This will create a folder called schema into your BetMas folder which is identical to that in Git and can be synced with it if you are online.

  • repeat the same operation for all other BetaMasaheft repositories you might need

Let's say you have a new manuscript file or you have edited one from the newly cloned repository. To add a new file to the Manuscript folder, simply put it in the manuscript folder which you have in BetMas.

  • Open Gihub Desktop and select the Manuscripts repository on the left

  • Click the CHANGE tab and you will see that it has recorded the fact that you have added such file to the folder (or modified it)

  • Below the list of changes there is a Commit field enter a name such as "new manuscript ready for review" and a description about what you have done e.g. "entered catalogue entry 1234 from Catalogue X" Please see also this page on revisions history.

  • Click commit

  • Once it has committed the changes on the top right corner click SYNC (old version of github desktop) or PUSH. This will look for anything that has changed online and update your files locally, then will upload your file or update the online version from yours.

  • N.B. THERE IS NO RISK of data to be overwritten or lost.

If you have not updated in the last two or three days, it is advisable to Sync/fetch all your repo before you begin a work session.

The Documentation repo contains instead two important parts, beside some code used locally for the project, the Wiki and the Issues

Issues

Let's say something goes wrong. e.g. I cannot see anymore the values from the schema! or the text displayed is the wrong one!. Open an issue for that here and give as much detail as possible.

Atom

You can use Atom to edit files, but to validate and get schema related support (like autocompletion) you will need to install a package.

linter-autocomplete-jing

once you have Atom installed, inside Atom, go to settings (or preferences on mac), then click on + install on the left and search the above string.

It will find the package. Click on install and say yes to dependencies installation requests.

You will then see errors messages and will get the autocompletion. it works very well!

Note also that if you open a folder as project in atom, which is a git repository, you will be able to pull and push directly in ATOM, using the Github package which is shipped with it. It is awesome.

Just click on the arrows pointing up and down in the bottom right corner and you will have really all in one place.

oXygen

oXygen is a text editor which is very smart with XML. oXygen is designed to help you write XML and it does it in a wonderful way, with all possible tools to help you in your workflow. Very often you will only use a few of the options provided. Some things you might find useful to know:

You can create a project and add to it your folders, so you can open files from oXygen directly.

  1. click on PROJECT, then on NEW project. call the file BetMas and save it into your BetMas folder, where you cloned the repositories from GIT.
  2. once created the project will open in oXygen in a side bar on the left.
  3. click with the secondary button on the icon of the project and select "add Folder"
  4. select the folders in the BetMas folder and add them all.
  5. They will appear under the Project icon. try to open manuscripts and click on a file to open it.

While editing your file you might start from one of the models.

  1. once you start typing a name of an element, oxygen will suggest you which elements can be used there.
  2. you can also use the elements and attributes view to select from a sidebar the element to add
  3. once you have an element and you want to add an attribute, type the space separating the element name from the future attribute and oXygen will pull up a list of attributes from which you can select. If an attribute is compulsary, is bold.
  4. also values for attributes are suggested by oXygen based on the schema.
  5. to enter a element you can either start typing it, or you can select a portion of text to tag and click CTRL+E which will open a small window where you can type the first letters of an element's name and select.
  6. you might need to repeatedly enter the same element. you can do the repeat with CTRL+/

You will often have to enter the the current date, for example when you describe your work in <change>. To facilitate this you can use the Code Templates function in oXygen. Set a Code Template for the XML Editor and assign it the current date value. Then, while editing to enter today's date open Document/Content Completion, start the assistant and enter the date.

There is a green light on top right corner of your document. If it is red, it means something is not valid. click on the small red bar along the side of the document to go to that point and read the message. Often this is enough, if you don't understand where is the problem, ask Pietro.

Special Characters and letters with diacritics

You might need to type one of the following

  • Ā ā (long a)

  • Ē ē (long e)

  • Ī ī (long i)

  • Ō ō (long o)

  • Ū ū (long u)

  • Ǝ ǝ (schwa)

  • ʾ (glottal stop)

  • ʿ (ʿayn)

  • Š š (sh)

  • Ś ś (lateral s)

  • Ṣ ṣ (emphatic s)

  • Ḍ ḍ (emphatic d)

  • Ḏ ḏ (dh, Arabic)

  • Ṭ ṭ (emphatic t)

  • Ṯ ṯ (th, Arabic)

  • Ṗ ṗ (emphatic p)

  • Ḥ ḥ (pharyngeal h)

  • Ḫ ḫ (kh)

  • Ž ž (zh, Amharic)

  • Ẓ ẓ (emphatic z, Arabic)

  • Ǧ ǧ (dj)

  • Ġ ġ (gh, Arabic)

  • Č č (ch)

  • Č̣ č̣ (emphatic ch)

  • Ḵ ḵ (kh, Tigrinya)

  • Q̲ q̲ (qh (Tigrinya)

  • Ḳ ḳ (emphatic k)

  • Ñ ñ (gn, Amharic)

You can use oXygen Content Completion. To do this make sure you sync this repo. in the folder codetemplates there is all you need. Open oxygen, go to Preferences and search "Code Templates". click on it on the menu list on the left. Once the list on the right appears, click IMPORT in the lower right corner. select the codetemplates.xml file from the codetemplates folder. Apply and close.

To use this code templates while editing click Document/ Content Completion, then "show content completion" and then select from the list what you need to type.

Zotero

Please check the Zotero guidelines for working with the group bibliography.

This page is referred to in the following pages

Revisions of this page

  • Pietro Maria Liuzzo on 2018-04-30: first version of guidelines from Wiki