Perspectivia

Editor guide

Introduction. Downloading the basic structure

deutsch This guide describes how you can prepare an edition for publication on the web with the least possible requirements and dependencies, yet without having to do without any of the options offered by the web. Naturally, it does require a little diligence and precision. But these virtues are required anyway in edition philology and you are able to acquire your own set of skills in the world of digital technology in the process. This guide builds on the information provided in the User guide and is followed up by the Developer guide.

The basic structure that can be used for creating your own edition or your own portal of editions can be downloaded. After downloading and unpacking the files, you will have a folder containing the following subfolders:

The folder code contains the code for operating the system. The folder content contains the file glosses.xml and a folder example. The file contains translations and can be supplemented manually in order to obtain a multilingual user interface. The folder represents a set of one or more editions which are served by the same system. Any edition has its corresponding subfolder. The subfolder goethe-schiller represents an example edition. These types of subfolders are named edition folders below. The subfolder portal, on the other hand, represents the portal to all editions with a survey page, a cross-site search and general information.

The edition folders contain files and folders:

Besides, the folder cssjs contains notably CSS files, i.e. formatting instructions. For reasons of simplicity and uniformity, this system uses the same CSS files for all editions. The CSS file cssjs/main.css is particularly relevant for the tasks involved in creating an edition; the formatting information provided in this file can generally be retained.

In order to create a new edition, you change the downloaded basic structure. In particular, the folder goethe-schiller is renamed, files in this folder are changed and, above all, new files are saved to this folder that contain the pages for the relevant edition. When the sections below describe changes to the files, these files can simply be opened and changed in any text editor. However, it is important to ensure in the settings for the relevant text editor that the character encoding is set to UTF-8. UTF-8 is the standard character encoding for XML and the web, as well as often being the standard setting used in text editors and many other programs. – It is especially convenient when the text editor offers syntax highlighting for XML (or HTML), meaning that the text editor will display different types of text highlighted in different colours with matching brackets. It is also helpful if the text editor can check whether the document is well-formed XML and where any errors possibly exist. – Those text editors designed for entering instructions by hand are also the ones required for more or less automatically converting existing data into the desired format e.g. if the data is already saved to a database or exists in the form of word files.

If you have already created your edition or an intermediate work ready for publication, the easiest way to publish it is to copy the edition folder into another copy of this edition portal that is running on a server, or in other words a computer that is connected to the web and can be accessed there via an address. This means that you can work on the edition on your own computer, save it or have it saved to a server and the edition is then visible on the web, not only via the browser on your own computer. More details on this are provided in the next section.

Starting the portal and viewing the example edition in a browser

deutsch This requires Python 3.4 or higher to be installed. The installation files for all standard operating systems can be downloaded here; in the case of some operating systems, an installation using the Python package manager is recommended. Once you have started the installation file (double click), you can simply click on Next, OK or Finish until the installation has been completed. You can then start the portal: Click in the folder code/python/example on the file start_on_localhost.py (double click) and wait until the following is shown as the last line in the message window that opens: Hit Ctrl-C to quit.; then open a browser and enter http://localhost:8080/goethe-schiller in the address field and press Enter. The start page for the example edition will appear and the URL will change to http://localhost:8080/de/goethe-schiller/start :

http
means hypertext transfer protocol and indicates which rules (which protocol) the data transfer is required to follow, namely for transferring websites.
localhost
is the address, or more precisely the domain of your computer in each case. localhost is your computer itself. If you have saved the edition to a server, the domain for this computer will be shown instead, e.g. quellen-perspectivia.net. On a server of this type, the portal will need to be started a little differently; see here. The work involved in creating an edition is not affected by this difference in the domain name.
8080
is one of the input channels (ports) on the computer. If you have saved the edition to a server, it is usually port 80 that is connected to the web; and this port is implied when the port number is missing from the URL. For example, the following URLs http://quellen-perspectivia.net and http://quellen-perspectivia.net:80 are thus equivalent.
de
indicates the language in its standard abbreviated form. The system will automatically use the default language if the URL does not provide information on the desired language or if it states a language that is not available for this edition. (how you define the available languages is described below)
goethe-schiller
is the name of the edition and also the name of the folder that corresponds to this edition.
start
is the name of the web page and also the name of the folder that corresponds to this web page.

In order to gain an initial impression of the system and its pages, you can firstly switch the language to english, click on some of the menu items and watch how this changes the URL.

When the example edition is changed in the following sections, these changes can also be immediately viewed in the browser. In general, it is sufficient to update the page in the browser by pressing the F5 button in order to view the change. However, sometimes it is necessary to restart the system: Close the message window described above to ensure that the program ends, restart the file portal.py and wait as described above; then press F5. – A restart is necessary when you have added a new project or the files _config or glosses have been changed. (More information on these changes is provided below.)

If something is not displayed as expected, it is often helpful to view the HTML document that is the basis for what is displayed in the browser. You can do this in Firefox, for example, using the key combination Ctrl u. It is also possible to right click on a questionable section of the page and select Inspect element: The section of the HTML file that belongs to this precise section of the web page will be displayed together with the standard formatting instructions from the CSS files being used.

Defining logos, the title image, languages and menu items

Marked sections from top to bottom: shortcut icon, project logo and logo for the organisation, menu items, language selection.

deutsch In order to define the languages, logos, title image and menu items, it is necessary in the folder goethe-schiller to change the file _config, replace the images in the subfolder icons and in certain circumstances to amend or have the file glosses amended in the superordinate folder portal. The individual steps will now be described below.

Replacing images

deutsch In the subfolder icons, the following images should be replaced with those images required for your own edition:

cover.png
is the title image on the start page. The width and height of the image should be about the same as the image in the example: Images that are much smaller will be enlarged and will then look pixelated; images that are much larger will slow down the transfer of the page to the user over the web.
main.png
is the first of the two logos displayed in the top left of the page. This is the logo for the edition itself. It can be produced e.g. by using an image processing program such as GIMP to select a suitable section of the title image and reducing it in size where necessary.
main_org.png
is the second of the two logos. It is the logo for the umbrella organisation for this edition.
shortcut.ico
is the small image in the top left of the browser tab. The file format must be .ico and the size should be 16 x 16 pixels. It can be produced e.g. by reducing the size of the logo for the edition, simplifying it where necessary, and saving it as a .ico file.

The easiest approach is to keep the same names for your own new files and save them over the old files. The new images can be seen on the page by switching over to the browser and pressing the F5 button. However, sometimes the images are saved by the browser and are not downloaded again; in this case you need to press the F5 button multiple times or empty the browser cache: in Firefox this can be done in German under Einstellungen – Netzwerk – Jetzt leeren, or in English under: Options – Network – Clear Now. However, sometimes only a restart will help.

If you want to use a different name other than cover.png. You need to change the information in the file for the start page; and naturally it is also necessary to change the text for the title page – as well as the description of the image that appears when you move the mouse pointer over it. We will come back to this below.

If you want to use more or less logos, a link, a slightly different design or another file name for the logos then you need to change the information in the file _config. More information on this is provided in the next section.

Changing the file _config. Defining the languages

Introduction

deutsch The file _config can also be viewed in the browser under http://localhost:8080/goethe-schiller/_config. Despite its special functions, it is still a HTML5-XML file, is saved in an edition folder just like the other web page files and when a browser requests the URL stated above it is thus converted into a HTML5 document and sent to the browser. This uniformity is generally a positive aspect because the file can be conveniently viewed without any extra effort and without having to update data in two different locations. However, this type of configuration page is generally of no interest to a normal reader of the edition, which is why there is no link to it in the menu or the table of contents. The keys to the tables can be best read in the browser. If the portal system is upgraded, it is possible to also change these entries in the browser; in this current version this process is carried out in the file goethe-schiller/_config itself. The first table is for the languages; it starts with the tag <table class="mapping" id="lang_ids"> and ends with the tag </table>.

Additional information: XML basics

deutsch The following section deals with the recently opened file _config and provides an overview of the most important XML rules for editing this file, yet also takes account of questions that may arise later when entering other text. This section can thus be skimmed over a little.

  1. A section that is demarcated by tabs is called an element. In this case, the element is a table. Tags are not displayed by the browser but rather evaluated in order to correctly display the actual text.
  2. The tags contain the name of the element, in this case table.
  3. A tag is surrounded by the characters < > and as such stands out from the actual text.
  4. The character / turns the tag into an end tag.
  5. Elements can be empty: <td></td> is an empty cell in a table. Important for using the system: In order to ensure that the entered XML is also a piece of valid HTML, certain empty elements (and only these elements) are written as abbreviations, where the closing tag is missing and the opening tag is closed with a / at the end. These are HTML elements that are always empty: <area/> <base/> <br/> <col/> <embed/> <hr/> <img/> <input/> <keygen/> <link/> <meta/> <param/> <source/> <track/> <wbr/>.
    Only <br/> and <img/> are important for the work involved in creating an edition.
    A clear distinction must be made for <br/> : In a case such as para-<br/>
    graph     it is not permitted for there to be a space before the <br/>; in a case such as change of <br/>
    line    , there must be a space. This is because if the line break is removed (e.g. for a full text search), the first example must produce para-graph (from which paragraph is formed), yet in the second example it is critical that the following is formed change of line, and not change ofline.
  6. Elements can contain other elements and the tags are then nested accordingly. See <table><caption>information</caption></table>; here the caption element is contained within the table element. The table for the language selection contains a caption element (which is the key), a thead element (the header with the column headings) and a tbody element (the body with the actual content).
  7. The nesting must be carried out without overlapping in accordance with XML syntax rules, meaning that an element must either be completely contained within another or not at all; thus both tags are contained within this element or both are outside the element.
  8. There must be precisely one element that contains all of the other ones, meaning that its tags surround all of the others. In the example using the file _config, this element is the article element.
  9. Line breaks and indents – as displayed by the file _config – serve to improve the readability of the content for the human eye but are either not taken into account at all by machines or (if they are immediately next to or within the actual text) they are replaced by a single space. An example: 
    
<i>one
	two</i>
    (with a change of line and indentation) will simply appear in the browser as: one two (on one and the same line).
  10. Opening tags can contain additional information about the element – so-called attributes. class="mapping" e.g. is an attribute with the name class and the value mapping. (Inheritance:) An attribute for an element is also valid for all other elements contained within this element. However, if an element contained within another element has its own attribute of the same name then this value is naturally applied.
    class attributes
    A browser takes the value as a keyword that can be found in the CSS formatting template where the formatting instructions are saved. The value can also give multiple keywords at once, each separated by a space. See class="index non-source".
    Making an edition, it should be noted that the edition text and the source text must be entered in a uniform manner and explicitly differentiated from one another: Edition text must be contained within an element that is distinguished either itself or inherits this distinction from another element with the attribute class="non-source"; in the case of source text, the attribute should be class="source".
    href attribute
    The value is understood as a URL; e.g. <a href="user_guide">Link</a> creates a link to this guide, which is displayed by the browser as: Link. It is necessary to differentiate here between the following types of URL (For general information on URLs see here):
    http://… URLs
    such as http://d-nb.info/gnd/118540238 are the most detailed URLs and are used to link to a page that is located in another domain than the one with the page containing the link.
    /… URLs
    such as /de/goethe-schiller/start contain no information about the domain and are used to link to pages within the same domain. This is necessary so that you do not have to change the links depending on whether you are testing the page on localhost or on the server. An example:
    href="/de/goethe-schiller/start" means the same as
    href="http://localhost:8080/de/goethe-schiller/start", when it is found on a page whose URL starts with
    http://localhost:8080/.
    …URLs
    such as those like the user_guide example above do not start with / and are used to link to pages relative to the page on which the URL is found: In the URL for this page, everything after the end / is replaced by the relative URL. This is necessary to retain settings given by the path e.g. the language. An example:
    href="user_guide#rdfa" means the same as
    href="http://localhost:8080/de/portal/user_guide#rdfa, when it is found on the page
    http://localhost:8080/de/portal/editor_guide.
    id attribute
    The attribute id="lang_ids" e.g. gives the element an ID. It can be used in URLs to not only link to a page in general but rather to link to a certain element on this page. This type of URL is formed using the URL for the page plus # plus the ID. See http://localhost:8080/goethe-schiller/_config#lang_ids. The ID can be freely assigned but must be unique for the whole document and may only contain characters that are permitted in URLs (which will be explained later).
    Breaking down the page using the id attribute is especially important for precise linking or referencing, particularity for citations and full text searches. It is then usually necessary to make the id attribute visible. On this page, this is achieved by entering <a class="local" href="#…"></a> immediately after the tag with the attribute id="…" (the … should be replaced here by the actual ID).
    lang attribute
    Please refer here to the information on translations.
    property attribute
    about attribute
    are used for the RDFa markups. See here.
  11. For the purposes of clarity, certain characters should be converted into a different form when they appear in the actual text:
    • Instead of < you write &lt;.
    • Instead of > you write &gt;.
    • Instead of & you write &amp;.
    An example:
    &c<etera> would be written as:
    &amp;c&lt;etera&gt;
    In the case of attribute values, the following is also true:
    • Instead of " you write &quot;.
    • Instead of ' you write &apos;.
    All other characters can be written as themselves, whereby the correct coding must be set in the text editor: UTF-8.
    Incidentally, these characters can also be converted into a numerical form, using either a decimal or a hexadecimal number (the numbers can be found e.g. here):
    • Decimal &#8239; or hexadecimal &#x202F; stands for a narrow non-breaking space. It is to be used in i. e., e. g. etc.
    • &#160; or &#xa0; stands for a normal non-breaking space. It is to be used in word1 / word2 before the forward slash.
    • &#8209; or &#x2011; stands for a non-breaking hyphen.
    • &#8211; or &#x2013; stands for an n-dash.
    • &#8220; or &#x201c; stands for “ (opening quotation marks)
    • &#8221; or &#x201d; stands for ” (closing quotation marks)
    • &#8216; or &#x2018; stands for ‘ (opening quotation mark)
    • &#8217; or &#x2019; stands for ’ (closing quotation mark and apostrophe)
    For the purpose of good typography, these characters are used frequently but cannot be entered via a normal keyboard. Moreover, the spaces are difficult to differentiate from one another. In these cases, it is recommended that the numerical form is entered.

Continuation

deutsch The language selection is changed in the tbody element of the table lang_ids; rows are trelements, cells are td elements. Every row contains two cells: The first contains the language using the ISO-639-1abbreviation; the second can contain the comment default. The old status is:


<tbody>
	<tr><td>ar</td><td></td></tr>
	<tr><td>de</td><td>default</td></tr>
	<tr><td>en</td><td></td></tr>
	<tr><td>fr</td><td></td></tr>
	<tr><td>it</td><td></td></tr>
	<tr><td>ja</td><td></td></tr>
	<tr><td>pl</td><td></td></tr>
	<tr><td>ru</td><td></td></tr>
	<tr><td>tr</td><td></td></tr>
</tbody>

This means that the nine languages Arabian, German, English, French, Italian, Japanese, Polish, Russian and Turkish are provided as options for the user; German is the default language that will be selected if no choice is made and the URL does not contain any information about the language. If you want to only offer German, English and French as options and set French as the default language, the table needs to be changed as follows:


<tbody>
	<tr><td>de</td><td></td></tr>
	<tr><td>en</td><td></td></tr>
	<tr><td>fr</td><td>default</td></tr>
</tbody>

Which languages and how many languages should you offer? The language selection affects, on the one hand, individual words and short phrases in the menu, short title, search table and search form, and, on the other hand, complete sections of text in the main content of the page:

  1. Translations for individual words and short phrases can be found in the file glosses in the folder portal. In this version, this file contains translations for all of the nine languages named above for all previously used menu items, short titles and inscriptions. If you require more translations then it is necessary to add them or have them added to the file. (see here.) If there is no translation entered in the file for the selected language, the entry for the default language for the portal will be used; if there is no entry for the default language then the keyword itself for which the translation was unsuccessfully searched is used.
  2. Translations for complete sections of text must be provided yourself. The texts for the different languages are simply entered next to one another in the edition folder and differentiated from one another using an ISO-639-1abbreviation e.g. start+de, start+en and start (the text for the default language, in this case French, can be designated using the abbreviation or it can be omitted). If no text can be found for a selected language, the default text is used.
    It is important that the language designations are correct: If a piece of text in a file has another language than the file name would suggest then the element within which this different language text is located must be given the attribute lang="_" and instead of _ the language abbreviation according to ISO 639-1 is entered. If the language is changed too often (such as in a directory) or it is questionable (such as with proper names), write lang="" and leave the attribute blank; the language then remains undefined. You can also do this for the element that contains all other elements; the language for the entire document will then remain undefined.
    If you have translated a complete text but the menu offers a lot more languages than required, it is sensible to enable the user to not only access the translation via the normal language selection but also via a link in the text itself. It then becomes clear whether a translation and which translations are available and it is not only possible to link to the entire page but also to certain sections in the translation. See here.

The next two tables enable you to define the number and sequence of the logos, as well as any links and shadowing, and where desired to enter any other file names. Precise instructions can be found in the relevant keys (the caption element) for the tables.

Changes to the file _config only become effective after the system has been restarted.

deutsch In the last table, it is possible to define the entries in the menu on the left-hand side of the page, meaning which web pages are linked through the menu items. Precise instructions can be found in the key for the table. You can try this out by copying one of the pages already available in the example, e.g. the file introduction, saving it under a different name in the same folder and then adding the new name to the menu items.

When you have completed these entries, you will possibly want to also add them to the translations section so that there is a translation based on the language selected by the user instead of just a single language file name. More details on this are provided in the next section.

Adding translations

deutsch In the folder portal, there is the file glossesthat contains the translations for individual words and short phrases, as described above. The content of this file is contained in a table, which you should already be familiar with from the file _config (see here) and incidentally can also be viewed in a browser. In order to add translations, you add rows according to the following structure:


<tr><td>1</td><td>2</td><td>3</td></tr>

For 1 add the keyword: In the case of menu items, this is simply the name of the file to which the menu item links; while in the case of short titles, it is the name of the edition folder as we shall see below. For 2 add the two letter language abbreviation in accordance with ISO 639-1 and for 3 add the translation that matches the keyword and the language. You will find enough examples in the file itself.

Defining the URL and the short title

deutsch In order to replace the sample name goethe-schiller in the URL for this page and in the short title under the logo, you firstly need to rename the edition folder. The new name of the edition folder will be used in the URL for the web page. Therefore, you can only use those characters in the name that are permitted for URLs. These are more or less the same characters that are permitted for folder and file names: basic Latin letters, numbers and letters from other writing systems. Spaces and all punctuation marks are excluded except the following four characters: - . _ ~ Or to put it more precisely: The so-called iunreserved charactersthat are defined in RFC 3987 on page 7 are permitted. Furthermore, it is recommended that you refrain from the use of upper case letters for this portal in order to reduce the risk of confusion and guarantee that two different names are always different file names (because some operating systems do not distinguish between upper and lower case characters in the file names).

Once you have renamed the folder, it is necessary to restart the system and instead of http://localhost:8080/goethe-schiller you now need to enter http://localhost:8080/[new name here] in the browser. As the URL only includes the name of the edition and does not include any information on individual pages in this edition or the language, the system will enter the default language and the default page into the URL as they are defined in the file _config. A reader can thus also access the edition with this type of shortened URL and is directed to the default page (which is then the start page) in the default language.

However, it is possible to add translations in advance to include the new name of the folder: This is carried out as described above, whereby the folder name is used as the keyword. Below is an example, although with the special feature that a return character has been added to the translations (after Briefwechsel, Correspondence and Correspondance):


<tr><td>fantin-scholderer</td><td>de</td><td>Briefwechsel
Fantin-Latour und Scholderer</td></tr>
<tr><td>fantin-scholderer</td><td>en</td><td>Correspondence
Fantin-Latour and Scholderer</td></tr>
<tr><td>fantin-scholderer</td><td>fr</td><td>Correspondance
Fantin-Latour et Scholderer</td></tr>

The return character is implemented on the browser and this makes the short title easier to read. See here.

Accessibility of the pages. Table of contents

deutsch There are three special options available that ultimately enable readers to access all pages of the edition from the start page: the first option is via the menu, as described above, the second is via a table of contents and the third via indices. The menu only includes a few main pages. In principle, the table of contents can include all pages; although a very long series of pages – e.g. hundreds of letters – are better entered in an index that can be sorted and filtered. Firstly, we will describe how to set up a table of contents: The page for the table of contents in the example folder is called table_of_contents and it is also entered as a menu item. However, the corresponding file only contains a reference to the template with which the table of contents is actually automatically created. This requires a list of pages that should appear in the table of contents; this list can be found in the file _table_of_contents_ids. It can be viewed in a browser just like the file _config and also uses the familiar table structure. In the rows of the table, enter the names for every file that should be included in the table of contents. The system will then automatically provide space for: translations of the file names based on the language of the text contained within them, the heading in the files, indentations based on the heading levels and links to the relevant page or heading. If you have a lot of pages to add, it may also be preferable to automatically create the table rows. For example, the following Python script will create a file _table_of_contents_ids in the folder FOLDERPATH in which all of the pages in this folder will be included. You can then delete all of those pages in this file that you do not want in the table of contents by hand, such as the files _config, _table_of_contents_ids, table_of_contents and the title page(s). Here is the script: You can copy the rows into an empty text file, close the text file, change the file ending from .txt to .py and then start the script with a double click (when Python 3.4 is installed, as stated above). For /path/to/the/folder/of/the/edition, you firstly need to enter the correct path to the edition folder. 


import os

FOLDERPATH = '/path/to/the/folder/of/the/edition'
RESULTNAME = '_table_of_contents_ids' 

DOC_TEMPLATE = '''
<article class="index non-source">
	<table class="mapping">
		<!-- Ensure, that every table_of_contents_id
		     is the name of a webpage-file. -->
		<thead>
			<tr><th>table_of_contents_id</th></tr>
		</thead>
		<tbody>
{}
		</tbody>
	</table>
</article>
'''

doc = DOC_TEMPLATE.format(
        os.linesep.join(
            '\t\t\t<tr><td>{}</td></tr>'.format(name)
            for name in os.listdir(FOLDERPATH)
            if os.path.isfile(os.path.join(FOLDERPATH, name))))

with open(
        os.path.join(FOLDERPATH, RESULTNAME),
        'w',
        encoding = 'utf-8') as file:
    file.write(doc)

Title page. Bibliographical metadata. RDFa

deutsch The title page is the start page of an edition. Examples for start pages can be found in the edition folder: the files start and start+en; the latter is the English version of the former. (It is not necessary in this case to add a +de because the default language is German) The easiest way to create your own start page is to follow this template and replace all of the text that is visible in the browser, not forgetting the caption for the image that appears when you move the mouse pointer over the background image. (For changing the background image see here.)

When entering information into the file, the rules stated above must be strictly followed.

A user must be able to find all bibliographic metadata on the title page. A list of these can be found here. This list also includes the expression that is used in each case for the RDFa markup. About RDFa in general here. The markups that already exist in the two template files start and start+en can generally be retained. Please note:

Other pages. More about RDFa

deutsch You can now created other files based on the template already used for the title page: