Schema View Ontology View

Editing these Guidelines

How it works

These guidelines are fed by a Github webhook pushing into the web application at http://betamasaheft.eu/Guidelines/ data from the guidelines repository, the Beta maṣāḥǝft schema repository and the Beta maṣāḥǝft ontology (this is not via webhook).

If you edit and push (or make a pull request) to the above repositories, the XML files will be sent to the application and go live so that you can see them, search, browse, read, etc.

All edits to the guidelines should be made as a pull request, and not be pushed directly to the main branch. This is to ensure that the guidelines do reflect the entire team's decisions and that everyone is aware of any changes made to them. It is not necessary to assign all team members as reviewers, but do assign those who seem to you the most competent to check the particular edit. The reviewers should then check that the text of the guidelines reflects the decision taken, that the English is correct and understandable and that all useful linkage is present.

Editing the XML

You can use any editor you like to edit the XML files. This page describes only the editing of the guidelines, for the editing of the schema see editing the Schema.

There is a Beta maṣāḥǝft Guidelines Schema which validates the files you are pushing to the app when editing the guidelines and will notify you if anything goes wrong. There are processing instructions in every single file that should allow your editor to validate your XML BEFORE you push it to the repository.

Principles

In principle, given that the information is displayed together, what is already specified in the schema should not need further clarification, so, e.g. there is no need to repeat a list of values for an attribute if this is in the schema.

Besides the schema folder (which is the Beta maṣāḥǝft Guidelines Schema), the guidelines folder contains subfolders for pages, elements, the table of contents (toc) and the user guide:

  1. Pages are descriptive pieces like this one, trying to explain how to encode something.
  2. Tables of Contents (toc) are simply lists, organizing pages in meaningful ways based on type of user, kind of task, etc.
  3. Elements describe one element: They link to the page of the respective element in the TEI guidelines, fetch from the Beta maṣāḥǝft schema any further specification and link back to all guideline pages mentioning this element.

Documentation Tags

We use the TEI Documentation Elements.

The application will use the @xml:id in <body>↗ to identify the pages and elements, so, please take care not to duplicate @xml:ids if you are creating a new page. The application will use the <title>↗ inside <titleStmt>↗ as a label for that resource. This means that you can have a page and an element called "person" but these will need two different @xml:id in <body>↗

We use <div>↗ elements to structure the contents. These should have

  1. A @type with level2 where the digit is a number from 2 to whatever the deepness of sections required is.
  2. A child <head>↗ with the title of the subsection.

You can use <table>↗ and <list>↗ and their children as specified in TEI.

Links are encoded using <ref>↗ with @target:

  1. You can enter in @target simply the ID of any of the pages in the guidelines: 
    
                                for the editing of the schema see <ref target="editingSchema">editing the Schema</ref>

    Example 1

  2. You can add a @type with bm and your @target can simply be the ID of any of the entities in Beta maṣāḥǝft. This is useful to link to examples: 
    
                                special cases like <ref target="BNFet45" type="bm">BNFet45</ref>

    Example 2

  3. If you enter a URL, this will become an external link: 
    
                                entering data in the <ref target="https://www.zotero.org/groups/ethiostudies/items">Zotero Group Library.</ref>

    Example 3

Please always use <gi>↗, <tag>↗, <att>↗ and <val>↗ to mark up respectively element names, tags, attributes names and values. Only in case the value is a class or property with a prefix, then use <code>↗, e.g. foaf:member.You do not need to type angle brackets and escape them or to add @ in front of every attribute, this will be done during the visualization. For elements a link will also be given to the page for that element.

To add examples of XML markup, use the <egXML>↗ element, always with its namespace so, <egXML xmlns="http://www.tei-c.org/ns/Examples">↗. This allows the validation to skip the contents (i.e. do not add again the TEI namespace in the examples).

Good practice should be always used in providing examples, which should not be made up but reflect the encoding in a currently existing file. It is also good practice to add a <ref>↗ with a link to the file where this is to be found.

You can use <cit>↗ and <quote>↗ for quotations.

If you want to make something bold or italics use <hi rendition="simple:bold">↗ and <hi rendition="simple:italic">↗

In a Table of contents file, please only use <list>↗ and enter as content of the <item>↗s only the ID of the page you want the ToC to point to.

Figures

You can add figures like in the following example, adding the info.json URL of any IIIF available image on the web.

For images published by the project, i.e. the Ethio-SPaRe manuscript images, the format of these URLs is always as the one in the example.


              <figure>
                  <graphic xml:id="g1" url="http://betamasaheft.eu/iiif/KAE/011/KAE-011__005.tif/info.json">
                      <desc>Caption of the image</desc></graphic>
              </figure>

Example 4

Fig. g1. This is a test image from BM IIIF server.

You can use <ref type='figure'>↗ with a @target pointing at the image ID like in the following example, used here Fig. g1.


              <ref type="figure" target="#g1"></ref>

Example 5

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
    • Dorothea Reule on 2018-05-14: Edited and added examples
    • Dorothea Reule on 2018-11-06: Added paragraph on pull requests
    • Pietro Maria Liuzzo on 2018-12-05: Added support for Figures