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 repos, the XML files will be sent to the application and go live so that you can see them, search, browse, read, etc.

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. Actually, there are processing instructions in every single file that should allow your editor to validate your XML BEFORE you push it to the repo.

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. 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 really 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.

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