From 0277318e22aa5d22ed5abcffb61a9feeeea97418 Mon Sep 17 00:00:00 2001 From: NinaBrundke Date: Wed, 6 Nov 2024 09:21:35 +0100 Subject: [PATCH] Manual adaptions and corrections for Entity --- sphinx/source/entity/actor.rst | 34 ++++--- sphinx/source/entity/artifact.rst | 25 +++--- sphinx/source/entity/event.rst | 96 ++++++++++---------- sphinx/source/entity/feature.rst | 18 ++-- sphinx/source/entity/file.rst | 65 +++++++------- sphinx/source/entity/human_remains.rst | 24 ++--- sphinx/source/entity/index.rst | 17 ++-- sphinx/source/entity/navigation.rst | 9 +- sphinx/source/entity/place.rst | 48 +++++----- sphinx/source/entity/reference.rst | 16 ++-- sphinx/source/entity/reference_system.rst | 98 +++++++++++---------- sphinx/source/entity/source.rst | 16 ++-- sphinx/source/entity/stratigraphic_unit.rst | 14 +-- sphinx/source/entity/type.rst | 66 +++++++------- 14 files changed, 294 insertions(+), 252 deletions(-) diff --git a/sphinx/source/entity/actor.rst b/sphinx/source/entity/actor.rst index 018c7f250..f2b0a17a4 100644 --- a/sphinx/source/entity/actor.rst +++ b/sphinx/source/entity/actor.rst @@ -6,9 +6,10 @@ Actor CIDOC documentation: :cidoc_entity:`E21 Person` and :cidoc_entity:`E74 Group` -* **Person** (:cidoc_entity:`E21 Person`) -* **Group** (:cidoc_entity:`E74 Group`) - e - .g. a family, a tribe, Greenpeace or the National Museum of +* **Person** (:cidoc_entity:`E21 Person`) - A single person, + such as Albert Einstein or Queen Victoria +* **Group** (:cidoc_entity:`E74 Group`) - A group of people, + e.g. a family, a tribe, Greenpeace or the National Museum of Denmark .. include:: navigation.rst @@ -19,18 +20,23 @@ Form fields * :doc:`/ui/alias` * :doc:`/ui/date` * :doc:`/ui/description` -* **Residence** - a :doc:`place`, e.g. the location of an institute or the main residence of an actor -* **Born in / Begins in** - the :doc:`place` where a person was born or a group began -* **Died in / Ends in** - the :doc:`place` where a person died or a group ended +* **Residence** - A :doc:`place`, for a group this might be the location of an + institute, for a person for example the main residence +* **Born in / Begins in** - The :doc:`place` where a person was born or a + group came into existence +* **Died in / Ends in** - The :doc:`place` where a person died or a group ended * :doc:`reference_system` Can be linked via tabs to ------------------------- -* :doc:`source` - when it is referenced there -* :doc:`event` - for participation -* **Relation** - to other actors -* **Member of** - the groups it is member of -* **Member** - to actors who are members (only available for groups) -* :doc:`artifact` - owned artifacts and human remains by that actor -* :doc:`reference` -* :doc:`file` +* :doc:`source` - Use, if an actor is mentioned in a source +* :doc:`event` - Use, if an actor participated in an event +* **Relation** - Use to specify relations to other actors such as mother of + or married to +* **Member of** - Use to specify a group an actor is a member of +* **Member** - Link to actors to specify who was a member in a group (only + available for groups) +* :doc:`artifact` - Use to specify which artifacts and/or human remains are + owned by an actor (e.g. human remains that are kept in a museum) +* :doc:`reference` - Use to add citation +* :doc:`file` - Add a file, e.g. a picture of a person or group diff --git a/sphinx/source/entity/artifact.rst b/sphinx/source/entity/artifact.rst index 50e6c54dd..f65f4d6dc 100644 --- a/sphinx/source/entity/artifact.rst +++ b/sphinx/source/entity/artifact.rst @@ -6,7 +6,7 @@ Artifact CIDOC documentation: :cidoc_entity:`E22 Human-Made Object` -Artifact can be entered here, e.g. a coin +Artifact such as coins or pottery can be entered in this form. .. include:: navigation.rst @@ -18,18 +18,19 @@ Form fields * :doc:`/ui/description` * :doc:`/tools/map` * :doc:`reference_system` -* **Super** - a :doc:`place`, :doc:`feature`, :doc:`stratigraphic_unit` or - artifact, which it is a part of -* **Owned by** - the :doc:`actor` who owns the artifact +* **Super** - A :doc:`place`, :doc:`feature`, :doc:`stratigraphic_unit`, or + artifact, which the entered artifact is a part of +* **Owned by** - Link the artifact to an :doc:`actor` (person or group) who + owns it, such as a museum or a collector Can be linked via tabs to ------------------------- -* :doc:`source` - when it is referenced there -* :doc:`event` - acquisition, modification, move or production -* **Artifact** - here sub artifacts or :doc:`human_remains` can be added -* :doc:`reference` -* :doc:`file` +* :doc:`source` - Use, if an artifact is mentioned in a source +* :doc:`event` - Use, if an artifact was part of an event such as its + production +* **Artifact** - Use, to add sub artifacts or :doc:`human_remains` +* :doc:`reference` - Use to add citation +* :doc:`file` - Add a file, e.g. a picture of the artifact -If the artifact is a carrier of information it can be linked to a source. For -this you would have to edit or create the source and choose the artifact within -the source form. +If an artifact is a carrier of information **create or edit a source** and +choose the artifact that carries the source **within the source form**. diff --git a/sphinx/source/entity/event.rst b/sphinx/source/entity/event.rst index 06306109b..4bfbc55c7 100644 --- a/sphinx/source/entity/event.rst +++ b/sphinx/source/entity/event.rst @@ -12,20 +12,21 @@ CIDOC documentation: :cidoc_entity:`E12 Production` and :cidoc_entity:`E65 Creation` -* **Activity** (:cidoc_entity:`E7 Activity`) - - the most common, e.g. a battle, a meeting or a wedding -* **Acquisition** (:cidoc_entity:`E8 Acquisition`) - - mapping a change of property -* **Creation** (:cidoc_entity:`E65 Creation`) - - creation of documents (files) -* **Event** (:cidoc_entity:`E5 Event`) - - used for events not performed by actors, e.g. a natural disaster -* **Modification** (:cidoc_entity:`E11 Event`) - - used for modification of artifacts, e.g. a conservation treatment -* **Move** (:cidoc_entity:`E9 Move`) - - movement of artifacts or persons -* **Production** (:cidoc_entity:`E12 Production`) - - creation of artifacts +* **Activity** (:cidoc_entity:`E7 Activity`) - The most common +form of event, such as a battle, a meeting, or a wedding +* **Acquisition** (:cidoc_entity:`E8 Acquisition`) - Maps a + change of property from one owner to another +* **Creation** (:cidoc_entity:`E65 Creation`) - The creation + of a document (file; for the making of an artifact use production) +* **Event** (:cidoc_entity:`E5 Event`) - Used for events + **without human involvement** such a natural disaster +* **Modification** (:cidoc_entity:`E11 Event`) - Used to track + the modification of artifacts, e.g. a conservation treatment or a change + of parts +* **Move** (:cidoc_entity:`E9 Move`) - Movement of artifacts or + a person +* **Production** (:cidoc_entity:`E12 Production`) - The + creation of artifacts .. image:: event_hierarchy.png @@ -40,29 +41,31 @@ Form fields * :doc:`type` * :doc:`/ui/date` * :doc:`/ui/description` -* **Location** - a :doc:`place` where the event occurred -* **Sub event of** - events can be part of another event, - e.g. a battle as a sub event of a war. -* **Preceding event** - events can follow up other events, useful for e.g. - entering a journey +* **Location** - The :doc:`place` where an event happened +* **Sub event of** - As Events can be part of another event (e.g. a battle as + a sub event of a war), they can be linked here +* **Preceding event** - Events can follow up other events, useful for e.g. + entering a journey, link them here * :doc:`reference_system` Can be linked via tabs to ------------------------- -* :doc:`source` - when it is referenced there -* :doc:`actor` - to add participants, or recipient and donor for an acquisition -* :doc:`reference` -* :doc:`file` +* :doc:`source` - Use this way to link to a source if an event is refered to + in it +* :doc:`actor` - Add participants or recipient and donor in case of an + acquisition +* :doc:`reference` - Add a citation +* :doc:`file` - Add a file such as an image -For step by step instructions have a look at our :doc:`/examples/index`. +For a step by step instructions have a look at our :doc:`/examples/index`. Acquisition *********** -* **Given place** - to select which :doc:`places ` changed ownership. -* **Given artifact** - to select which :doc:`artifacts ` - changed ownership. +* **Given place** - Select which :doc:`places ` changed ownership +* **Given artifact** - Select which :doc:`artifacts ` + changed ownership -To add **recipients** and **donors** go to the **Actor** tab, add actors and +To add **recipients** and **donors** use to the **Actor** tab, add actors and select as activity: * **acquired title through** for **recipients** @@ -70,35 +73,36 @@ select as activity: Creation ******** -* Document (:doc:`file`) - to select files that were created +* Document (:doc:`file`) - Select files that were created -The creators of the document can be added via the **Actor** tab and selecting -the **carried out by** activity while linking them. +The creators of the document can be added via the **Actor** tab; therefore, +select **carried out by** to link Modification ************ -* :doc:`artifact` - to select artifacts that were modified +* :doc:`artifact` - Select artifact(s) that were modified -The creators of the artifact can be added via the **Actor** tab and selecting -the **carried out by** activity while linking them. +The creators of an artifact can be added via the **Actor** tab; therefore, +select **carried out by** to link Move **** -* **From** - a :doc:`place` as a start point -* **To** - a :doc:`place` as a destination point -* Moved :doc:`artifact` - to select moved artifacts -* Moved :doc:`Person ` - to select moved persons +* **From** - :doc:`place` - as a starting point +* **To** - :doc:`place` - as a destination point +* Moved :doc:`artifact` - Select the artifact(s) moved in an event +* Moved :doc:`Person ` - Select the people moved in an event -Unfortunately CIDOC CRM doesn't allows a **moved by** relation for groups. It -is still possible to "move" groups via the actor tab which in the background -creates a more general **participated at** relation between actor and move -event. For more information please take a look at :doc:`/examples/journey` or -:doc:`/examples/move_event` tutorial. +Unfortunately CIDOC CRM doesn't allow for a **moved by** relation for groups. +It is still possible to "move" groups via the actor tab, which in the +background creates a more general **participated at** relation between the +group and the move event. For more information please take a look at +:doc:`/examples/journey` or :doc:`/examples/move_event` tutorial. Production ********** -* :doc:`artifact` - to select artifacts that were produced +* :doc:`artifact` - Select artifact(s) that was/were produced during the + production event -The creators of the artifact can be added via the **Actor** tab and selecting -the **carried out by** activity while linking them. +The creators of an artifact can be added via the **Actor** tab. Therefore, +select **carried out by** to link diff --git a/sphinx/source/entity/feature.rst b/sphinx/source/entity/feature.rst index f4603384e..bbe1fe49c 100644 --- a/sphinx/source/entity/feature.rst +++ b/sphinx/source/entity/feature.rst @@ -6,7 +6,8 @@ Feature CIDOC documentation: :cidoc_entity:`E18 Physical Thing` Features are subunit of a :doc:`place` and used in archaeological data -recording. E.g. graves or buildings of a site would be considered Features. +recording. E.g. graves or buildings of an archaeological site would be +considered features. Form fields ----------- @@ -14,17 +15,18 @@ Form fields * :doc:`type` * :doc:`/ui/date` * :doc:`/ui/description` -* Super - a :doc:`place` which it is a part of +* Super - :doc:`place` the feature is a part of * :doc:`/tools/map` Can be linked via tabs to ------------------------- -* :doc:`source` - when it is referenced there -* :doc:`event` - only for new events. For existing the location at the event - itself can be edited. -* :doc:`reference` -* :doc:`stratigraphic_unit` -* :doc:`file` +* :doc:`source` - use, if a feature is referenced in it +* :doc:`event` - use only for new events. For already existing events link + the location in the event form +* :doc:`reference` can be used to add a citation +* :doc:`stratigraphic_unit` is used to link a subunit of a feature (e.g. a + skeleton (stratigraphic unit) in a grave (feature)) +* :doc:`file` can be used to add files such as pictures Super and subunits ------------------ diff --git a/sphinx/source/entity/file.rst b/sphinx/source/entity/file.rst index d96e6f391..7142d8aa5 100644 --- a/sphinx/source/entity/file.rst +++ b/sphinx/source/entity/file.rst @@ -10,21 +10,23 @@ button to show all files. .. include:: /entity/navigation.rst -If entities are linked to displayable files the first one is shown in the info -tab but can be changed to another one in the files tab of the entity. +If entities are linked to displayable files the first linked file is shown in +the info tab. If another image should be displayed it can be changed in the +files tab of each entity. Files can be uploaded by editors if they don't exceed the upload size limit and -have an allowed extension. Both criteria are displayed at the upload form. It -is possible to upload multiple files in one go. They can either be selected in -the file field or drag and dropped into the specified area. +have one of the allowed extensions. Both criteria are displayed in the +upload form. It is possible to upload multiple files in one go. They can +either be selected via the file field or by drag and drop. Form fields ----------- -* **File** - here you can chose a file from your computer -* :doc:`/ui/name` - if empty it will be prefilled after the file selection with - the filename -* **License** - which works like a :doc:`type`, it is a good practice to define - one +* **File** - choose a file from your computer +* :doc:`/ui/name` - a name is required; if field is left empty, it will be + filled with the file name after file selection +* **License** - files such as images can only be shown on a presentation + site and archived if a license is defined; furthermore it is just good + practice to define licence * :doc:`/ui/description` Form fields important for public sharing @@ -35,7 +37,7 @@ More information is available at :ref:`public_sharing_label` * **Public sharing allowed** - indicates if public sharing is allowed * **Creator** - the creator of the file, e.g. the designer of a logo -* **License holder** - if not the same as creator +* **License holder** - mention if different from creator Can be linked via tabs to ------------------------- @@ -47,10 +49,13 @@ Can be linked via tabs to Settings -------- -* **Maximum file size in MB** - this limits also the total size of multiple - file upload +File settings can be accessed via the Files menu item. Not all users can +change the settings; Options provided are: + +* **Maximum file size in MB** limits the maximum file size; also limits the +total size when multiple files are uploaded together * **Profile image width in pixel** - related to the layout of info tabs -* **Allowed file extensions** +* **Allowed file extensions** - e.g. pdf, jpg, jpeg, svg Images that can be displayed in the browser are defined through their extensions and can be changed in the configuration file @@ -62,9 +67,9 @@ extensions and can be changed in the configuration file Logo ---- -You can chose a custom logo. The file has to be uploaded before and has to have -a display file extension. The displayed logo has a max-height of 120 px. If you -selected a larger one the browser will try to scale it. +You can chose a custom logo. To do so chose an already uploaded file with a +displayable file extension. The displayed logo has a max-height of 120 px. +If you have selected a larger image your browser will try to scale it. Image preview ------------- @@ -72,35 +77,35 @@ If image processing is enabled (default=on, configurable by admins) and user have **Show icons in tables** in their :doc:`/tools/profile` activated, small images of files are shown in tables. -Please be aware with many files and large tables this can impact performance. +**Please be aware many files and large tables can impact performance.** How to make files available for the public ------------------------------------------ -In case it is planned to share files with the public, e.g. at a presentation +In case files are supposed to be shared with the public, e.g. on a presentation site or a public archive, several criteria have to be met. Criteria checked by the software ******************************** * The file must exist * A license has to be specified -* It has to be marked with **public sharing allowed** +* **Public sharing allowed** has to be marked In case these criteria aren't met, a file won't be: * Shared via the :doc:`/technical/api` * Won't show up on presentation sites developed by the OpenAtlas team -* Won't be included in case the long time archiving -system `ARCHE `_ is used +* Won't be included in long time archiving if + `ARCHE `_ is used Criteria checked by managers and users ************************************** -* The linked license is the correct one and allows public sharing +* The linked license is correct and allows public sharing * Other license specific criteria, e.g. specifying the creator, are met -There are many licenses with many different criteria, e.g. a -CC-BY 4.0 license requires the attribution to the creator. Because it is not -possible to check these automatically, it is the responsibility of -the project management to ensure that all necessary requirements -are met and to indicated it via setting the **public sharing allowed** flag. +A automatic check for those specifics is not possible as there are many +licenses with numerous different criteria. Therefore it is the +responsibility of the project management to ensure that all necessary +requirements are met. To indicate this use the **public sharing +allowed** flag. -Be aware that licenses can be linked to an external reference (e.g. an URL) -which might be informative for other users or viewers. +**Used licenses should linked to an external reference (e.g. an URL) were +possible as it is informative for other users and viewers.** diff --git a/sphinx/source/entity/human_remains.rst b/sphinx/source/entity/human_remains.rst index 17eff31f6..73869364a 100644 --- a/sphinx/source/entity/human_remains.rst +++ b/sphinx/source/entity/human_remains.rst @@ -6,8 +6,8 @@ Human remains CIDOC documentation: :cidoc_entity:`E20 Biological Object` -Human remains are used to record anthropological data based on single human -bones. They are subunits of a :doc:`stratigraphic_unit` which itself is a +"Human remains" is used to record anthropological data based on each human +bone. They are subunits of a :doc:`stratigraphic_unit` which itself is a subunit of :doc:`feature`. Please note that information on the biological sex, gender, and age of an individual can be entered in the stratigraphic unit entry mask. For an archaeological workflow example see @@ -21,21 +21,25 @@ Form fields * :doc:`/ui/description` * :doc:`/tools/map` * :doc:`reference_system` -* **Super** - a :doc:`place`, :doc:`feature`, :doc:`stratigraphic_unit` or +* **Super** - a :doc:`place`, :doc:`feature`, :doc:`stratigraphic_unit`, or human remains, which it is a part of -* **Owned by** - the :doc:`actor` who owns the artifact +* **Owned by** - the :doc:`actor` (person or group) who owns the remains + such as museum Can be linked via tabs to ------------------------- -* :doc:`source` - when it is referenced there -* :doc:`event` - acquisition, modification, move or production -* :doc:`artifact` - here sub artifacts or human remains can be added +* :doc:`source` - if the remains are mentioned in a source +* :doc:`event` - acquisition, modification, move, and/or production can be + linked +* :doc:`artifact` - artifacts or human remains can be added * :doc:`reference` * :doc:`file` Super and subunits ------------------ In the OpenAtlas database Human remains can be subunits of a -:doc:`stratigraphic_unit`. A Stratigraphic unit can consist of one or more -Human remains (e.g. femur, humerus and first molar of the same individual, -etc.) as well as finds (see :doc:`artifact`). +:doc:`stratigraphic_unit` (e.g. a human femur (human remains) of a skeleton +(stratigraphic unit) in a grave (feature)). A +Stratigraphic unit can consist of one or more Human remains (femur, +humerus and first molar of the same individual etc.) as well as finds (see +:doc:`artifact`). diff --git a/sphinx/source/entity/index.rst b/sphinx/source/entity/index.rst index a668ec569..ef16264ef 100644 --- a/sphinx/source/entity/index.rst +++ b/sphinx/source/entity/index.rst @@ -1,14 +1,17 @@ Entity ====== -Most information that historians work with comes from historical documents. Usually, the first step -is to digitize the **sources** so that they are easier to work with. Often the next step is to -identify bits of information like **persons**, **events** and **places** and map them so that you -can ask questions like: *Where was this person in the course of his life?* or -*Who participated at an event?* +Most information that historians work with comes from historical documents. +Usually, the first step is to digitize the **sources** to facilitate working +with them. +Often the next step is to identify bits of information like **actors**, +**events**, and **places** and map them so that you can ask questions like: +*Where was this person in the course of his life?* or *Who participated in +an event?* -For archaeologist the first step of workflow is to create a new :doc:`/entity/place` and link subunits -e.g. :doc:`/entity/feature` and :doc:`/entity/stratigraphic_unit` to it. For a detailed workflow example see +For archaeologists a first step is to create a new :doc:`/entity/place` and +link subunits such as a :doc:`/entity/feature` and a +:doc:`/entity/stratigraphic_unit`. For a detailed workflow example see :doc:`/examples/archaeological_data`. The :doc:`/ui/menu` structure reflects that workflow. diff --git a/sphinx/source/entity/navigation.rst b/sphinx/source/entity/navigation.rst index bf4a5cd09..15c62d1ea 100644 --- a/sphinx/source/entity/navigation.rst +++ b/sphinx/source/entity/navigation.rst @@ -1,5 +1,6 @@ -On the index page already entered entities are listed in a :doc:`/ui/table`. +At the index page already entered entities are listed in a :doc:`/ui/table`. -* Click on the **+** button to enter a new one. -* Click on the **name** of an entry in the list to access the **detail view**. -* To edit or delete an entry click on the **Edit** button in the **detail view.** +* Click on the **+** button to enter a new one +* Click on the **name** of an entry in the list to access the **detail view** +* To edit or delete an entry, click on the **Edit** button in the **detail + view.** diff --git a/sphinx/source/entity/place.rst b/sphinx/source/entity/place.rst index 35f70558a..968fb6ccf 100644 --- a/sphinx/source/entity/place.rst +++ b/sphinx/source/entity/place.rst @@ -7,7 +7,7 @@ CIDOC documentation: :cidoc_entity:`E18 Physical Thing` and :cidoc_entity:`E53 Place` -A place can be e.g. a continent, a city or a graveyard. +A place can be e.g. a continent, a city, or a graveyard. For step by step instructions have a look at our :doc:`/examples/places`. .. include:: navigation.rst @@ -24,13 +24,13 @@ Form fields * **Historical Place** * :doc:`reference_system` -You can edit administrative units and historical places at **Types** in the +You can edit administrative units and historical places under **Types** in the **Places** tab. Administrative Unit ******************* Hierarchy of administrative units in which the place is located, e.g. Austria, -Italy and their respective subunits like Lower Austria, Styria. +Italy and their respective subunits like Lower Austria or Styria. Historical Place **************** @@ -39,35 +39,37 @@ which the place is located e.g. Duchy of Bavaria or Lombard Kingdom. Can be linked via tabs to ------------------------- -* :doc:`source` - when it is referenced there -* :doc:`event` - link new events. It's not possible to link to existing events - from here, this has to be done from the events itself +* :doc:`source` - if a source refers to a place +* :doc:`event` - you can link a place to a newly created event. It's not + possible to link to existing events in this way; you can link a place to + an existing event via the event's form though * :doc:`reference` * :doc:`artifact` -* :doc:`actor` - only creation of new actors (using the place as a residence) - is supported here because for linking to existing actors there would be too - much possibilities -* :doc:`feature` - its subunit +* :doc:`actor` - you can link a place to a newly created actor. It's not + possible to link to existing actors in this way; you can link a place to + an existing actor via the actor's form though +* :doc:`feature` - as subunit of a place (for more information see below) * :doc:`file` Places and their subunits ------------------------- -In OpenAtlas a place is a physical thing that has a certain position and/or -extends in space that can be connected to various other information (temporal, -spatial, events, sources etc.). Furthermore, places can be divided into -multiple subunits to record archaeological information. For more information -on those subunits see :doc:`feature`, :doc:`stratigraphic_unit`, -:doc:`artifact`, and :doc:`/entity/human_remains` as well as a detailed workflow example -(:doc:`/examples/archaeological_data`). +In OpenAtlas a place is a "physical thing" (CIDOC CRM +:cidoc_entity:`E18Physical Thing`) that has a certain +position and/or extends in space. It can be connected to various +other information (temporal, spatial, events, sources, etc.). Furthermore, +places can be divided into multiple subunits to record archaeological +information. For more information on subunits see :doc:`feature`, +:doc:`stratigraphic_unit`, :doc:`artifact`, and :doc:`/entity/human_remains` +as well as a detailed workflow example (:doc:`/examples/archaeological_data`). -An example of a place would be a graveyard. That place is the superior unit. +An example of a place would be a graveyard. The place is the superior unit. Each grave of this cemetery is considered a :doc:`feature` that forms the cemetery. Each of those graves is composed of one or many subunits -(:doc:`stratigraphic_unit`). This would be the burials in the very grave -(e.g. a primary and a secondary burial) and the back filling. Each -stratigraphic unit may have associated :doc:`artifact` belonging to the -respective unit: e.g. the grave goods of one of the burials, the artifacts -found in the back filling. Anthropological information can be added via +(:doc:`stratigraphic_unit`)such as burials in the very grave +(e.g. a primary and a secondary burial) and its back filling. Each +stratigraphic unit may have associated :doc:`artifact`, e.g. the grave goods +of one of the burials or artifacts found in the back filling. +Anthropological information can be added via :doc:`/entity/human_remains` - another subunit of stratigraphic unit. .. image:: sub_unit.jpg diff --git a/sphinx/source/entity/reference.rst b/sphinx/source/entity/reference.rst index 11b04bc4e..a6d0d7522 100644 --- a/sphinx/source/entity/reference.rst +++ b/sphinx/source/entity/reference.rst @@ -5,9 +5,9 @@ Reference CIDOC documentation: :cidoc_entity:`E31 Document` -* **Bibliography** - e.g. book, inbook or article +* **Bibliography** - add book, inbook, or article * **Edition** - e.g. charter editions or chronicle edition -* **External Reference** - e.g. URLs of websites or DOIs +* **External Reference** - such as URLs of websites or DOIs .. include:: navigation.rst @@ -19,8 +19,9 @@ Form fields Citation example ---------------- -At :doc:`/admin/content` an example citation can be defined which will be displayed under the -form at insert/update of an edition or a bibliography. +Via :doc:`/admin/content` an example citation can be defined which will be +displayed under the form during the insert/update of an edition or a +bibliography. Can be linked via tabs to ------------------------- @@ -30,7 +31,8 @@ Can be linked via tabs to * :doc:`place` * :doc:`file` -When linking a **Bibliography** or **Edition** a **page** can be defined. +While linking a **Bibliography** or **Edition** a **page** can be defined. -When linking an **External Reference** a **link text** can be specified which be shown on the -info page of referenced entities. In case no link text was provided the URL will be shown instead. +While linking an **External Reference** a **link text** can be specified which +be shown on the info page of referenced entities. In case no link text is +provided the URL will be shown instead. diff --git a/sphinx/source/entity/reference_system.rst b/sphinx/source/entity/reference_system.rst index f161706e7..d681bc3d6 100644 --- a/sphinx/source/entity/reference_system.rst +++ b/sphinx/source/entity/reference_system.rst @@ -6,33 +6,35 @@ Reference System CIDOC documentation: :cidoc_entity:`E32 Authority Document` -Reference systems can be used to link entities to external sources. You can -see a list of available systems by clicking the **Reference system** button on -the start page. - -Linking entities to external reference systems has many advantages like -being able to find or provide more information from other sources and it makes -it a lot easier to merge/compare data from other projects using the same -reference systems. - -For step by step instructions to add a reference system have a look at our +Reference systems can be used to link entities to external sources. A list with +available reference systems is provided when clicking the +**Reference system** button on the start page. + +Linking entities to external reference systems has many advantages such as +being able to find or provide more information from other sources. Futhermore, +they facilitate the merge of data sets. By using reference systems LOD (Linked +Open Data) can be created. +Furthermore, analogue reference systems such as library catalogues or +inventory numbers of a museum can be used in this way. + +For step by step instructions how to add a reference system have a look at our :doc:`/examples/reference_systems` example. Included by default ------------------- -These systems are included in the default application. Furthermore, -it was made use of their APIs to provide search functionality inside of -OpenAtlas and display their information about already linked entities at the -corresponding entity detail view. +The following reference systems are pre-installed. By using their provided +APIs, OpenAtlas can provide search functionality in the respective form fields +and display information about already linked entities in the corresponding +entity detail view. Wikidata ******** `Wikidata `_ is a collaboratively edited multilingual knowledge graph hosted by the Wikimedia Foundation. It is a common source of -open data that Wikimedia projects such as Wikipedia, and anyone else, is able -to use under the CC0 public domain license. +open data for Wikimedia projects such as Wikipedia. Everyone is able +to use the information under the CC0 public domain license. -By default it is usable for **places, persons and groups**. +By default it is usable for **places, persons and groups** within OpenAtlas. GeoNames ******** @@ -41,20 +43,21 @@ database available and accessible through various web services, under a Creative Commons attribution license. The GeoNames database contains over 25,000,000 geographical names corresponding to over 11,800,000 unique features. -For GeoNames the search is integrated in the map search field and it is also -possible to take over their coordinates for specific places. +The GeoNames search functionality is integrated in the map search field. +This enables users to automatically use the provided coordinates and +identifiers for specific places. -By default it is usable for **places**. +By default it is usable for **places** in OpenAtlas. GND *** The `GND `_ or Gemeinsame Normdatei (translated as Integrated Authority File) is an international authority -file for the organisation of personal names, subject headings and corporate +file for the organisation of personal names, subject headings, and corporate bodies from catalogues. It is used mainly for documentation in libraries and increasingly also by archives and museums. -By default it is usable for **persons**. +By default it is usable for **persons** in OpenAtlas. Usage ----- @@ -63,47 +66,50 @@ adding or updating an entity. ID ** -The identifier of the entity in the external reference system. For GeoNames -and Wikidata it will be checked for a valid format. +The identifier of an entity in the external reference system. For GeoNames +and Wikidata IDs will be checked for a valid format. Precision ********* When linking to an external reference a precision is required. Available options are the `SKOS `_ based definitions -of the confidence degree that concepts can be used interchangeable. +of confidence degree. -* **Close match**: Concepts are sufficiently similar that they can be used - interchangeably in some information retrieval applications -* **Exact match**: High degree of confidence that the concepts can be used +* **Close match**: Concepts (here a dataset in OpenAtlas and a dataset in an + external reference system) are sufficiently similar, therefore they can be + used interchangeably in some information retrieval applications +* **Exact match**: High degree of confidence that the concepts (a dataset in + OpenAtlas and a dataset in an external reference system) can be used interchangeably -E.g. if a historical project links the city of Vienna to Wikidata, a -**close match** would be more suitable, because the Wikidata entry is more -about the current city and not the historical one. +E.g. if a historical project links the city of Vienna in Wikidata, a +**close match** would be more suitable, as the Wikidata entry deals +primarily with the current city Vienna and not the historical place. Configuration ------------- -Admins and manager can add, update and delete external reference systems. - -* **Name** - e.g. Wikipedia; can not be changed for Wikidata or GeoNames -* **Website URL** - an URL to the project site of the reference system -* **Resolver URL** - an URL that can be linked to in combination with an ID, - e.g. the resolver URL **https://www.wikidata.org/wiki/** would create - together with a **Q123** - identifier the external link: https://www.wikidata.org/wiki/Q123 -* **Example ID** - an example id to show the desired format e.g. Q123 - for Wikidata +Admins and manager can add, update, and delete external reference systems. + +* **Name** - e.g. Wikipedia; the name can not be changed for the + pre-installed reference systems Wikidata and GeoNames +* **Website URL** - URL of the reference system (e.g. + `Wikidata `_ for Wikidata) +* **Resolver URL** - URL that - in combination with the ID - links to an + entity in the reference system (e.g. the resolver URL + **https://www.wikidata.org/wiki/** in combination with the ID **Q123** + creates the external link: https://www.wikidata.org/wiki/Q123 (September) +* **Example ID** - an example id to show the desired format (e.g. Q123 + for Wikidata) * **External reference match** - default precision selected in forms * **Description** - a short description, shown in forms when mouse over the **i** icon * **Classes** - a checkbox list of available classes, for GeoNames only place is available -Classes can be removed from a system by clicking on the tab with the +Classes can be removed from a reference system by clicking on the tab with the corresponding class name and clicking the **Remove** button. This button is -only available if there are no entities of this class linked to the reference -system. +only available if there are no entities of this class linked to it yet. Reference systems can be deleted only if no classes are attached to it. -Wikidata and GeoNames are integrated and cannot be deleted but if desired they -can be disabled by removing the classes. +Wikidata and GeoNames are integrated into OpenAtlas and cannot be deleted but, +if desired, can be disabled by removing the classes. diff --git a/sphinx/source/entity/source.rst b/sphinx/source/entity/source.rst index 3234ac070..9ae977b1b 100644 --- a/sphinx/source/entity/source.rst +++ b/sphinx/source/entity/source.rst @@ -6,8 +6,8 @@ Source CIDOC documentation: :cidoc_entity:`E33 Linguistic Object` -Written sources, like for example medieval charters or letters, can be entered -in OpenAtlas at the **Source** menu item. +Written sources, for example medieval charters or letters, can be entered +via the **Source** menu item. .. include:: navigation.rst @@ -15,16 +15,14 @@ Form fields ----------- * :doc:`/ui/name` * :doc:`type` -* :doc:`/entity/artifact` - if the artifact contains the source -* **Content** - a source content usually contains a summary or the whole text - of the source +* :doc:`/entity/artifact` - use if the source is part of an artifact +* **Content** - a summary or the whole text of the source Can be linked via tabs to ------------------------- * :doc:`event`, :doc:`actor`, :doc:`artifact`, :doc:`place`, and subunits it references -* :doc:`reference` - where it is documented in, e.g. in various editions of - charters or secondary sources -* **Translation** - respectively to the text in the original language - (e.g. Latin), can be a comment too +* :doc:`reference` - link to the literature the source is documented in, e.g. + editions of charters or secondary sources +* **Translation** - add translations of the source or a comment * :doc:`file` diff --git a/sphinx/source/entity/stratigraphic_unit.rst b/sphinx/source/entity/stratigraphic_unit.rst index eabc06543..891f23b07 100644 --- a/sphinx/source/entity/stratigraphic_unit.rst +++ b/sphinx/source/entity/stratigraphic_unit.rst @@ -5,9 +5,10 @@ Stratigraphic unit CIDOC documentation: :cidoc_entity:`E18 Physical Thing` -Stratigraphic units are used to record archaeological data. They are subunits -of a :doc:`feature` which itself is a subunit of a :doc:`place`. For an -archaeological workflow example see :doc:`/examples/archaeological_data`. +Stratigraphic units are primarily used to record archaeological data. They are +subunits of a :doc:`feature` which itself is a subunit of a :doc:`place`. +For an archaeological workflow example see +:doc:`/examples/archaeological_data`. Form fields ----------- @@ -20,9 +21,10 @@ Form fields Can be linked via tabs to ------------------------- -* :doc:`source` - when it is referenced there -* :doc:`event` - only for new events. For existing the location at the event - itself can be edited. +* :doc:`source` - link if a stratigraphic unit is referenced in a source +* :doc:`event` - you can link a stratigraphic subunit to a newly created + event. It's not possible to link to existing events in this way; you can + link a place to an existing event via the event's form though * :doc:`reference` * :doc:`artifact` * :doc:`human_remains` diff --git a/sphinx/source/entity/type.rst b/sphinx/source/entity/type.rst index 0fa40d2c2..ada1c0610 100644 --- a/sphinx/source/entity/type.rst +++ b/sphinx/source/entity/type.rst @@ -9,51 +9,57 @@ Types are used to add information or group entities. They are hierarchical and can be accessed and edited via the **Types** :doc:`/ui/menu` item. With this feature the user interface can be adapted for specific research interests. -* Types can be added dynamically in forms (with at least editor permission) - with basic information like name, description and super type +* Types can be added dynamically in forms (for users with editor status or + higher) with basic information like name, description and super type * The root type description is shown in forms as a mouse over text at the **i** icon -* **Untyped entities** can be checked at the type overview -* **Multiple linked entities** can be checked at the type overview, useful if - switching to single -* Types (except value types) can be **Set unselectable**, e.g. to enter - sub categories, via the corresponding button at a type view. But only if not - already used by entities and at least editor permissions are needed. +* **Untyped entities** can be checked via type overview +* **Multiple linked entities** can be checked at type overview, useful if + a type should be switched to single choice +* Types (except value types) can be **Set unselectable** via the + corresponding button in a type view. If selected only the type's + sub-categories can be selected in a form. Set unselectable can only be + selected if the type is not already used for entities. You need editor + permission or higher to make this change * A more detailed description on how to enter new types can be found :doc:`here` Standard types -------------- -Standard types are already present in the default installation with a few -examples. +Some standard types are pre-installed in every OpenAtlas instance. These types * Cannot be deleted or renamed (but subtypes of them can) * Are single select only -* In forms they appear with a **Type** label +* Appear in forms with a **Type** label * Are displayed in entity tables Custom types ------------ Custom types can be created, deleted and renamed. The default installation -comes with one example custom type **Sex** which is used for actor. +comes with one example custom type **Sex** which is used for actors. Custom +types -* Can be set to allow single or multiple choices -* Can be used for multiple classes, e.g. a hierarchy "case study" for places, - actors and events +* Can be single or multiple choices +* Can be used for multiple classes, for example the type "case study" and its +sub-types can be used in forms for places, actors, and events If you want to change an existing **multiple type to single** but the -multiple checkbox is greyed out and not selectable it means that at least one -entity already used multiple. You can check these entries at the type overview -at **multiple linked entities**. +multiple checkbox is greyed out and not selectable, the multiple option is +used for at least one entity already. Check entries in type overview at +**multiple linked entities** and make changes if necessary. Value types ----------- -Value types can be created, deleted and renamed. The default installation comes -with an example value type **Dimensions** with the sub types **Height** and -**Weight** which are used in the form for artifacts. +Value types can be created, deleted, and renamed. They are used to add +values in form of decimals to an entity. The default installation +comes with an example value type **Dimensions** with the sub-types +**Height** and **Weight** which are used in the form for artifacts. Value +types * Can be used for multiple classes * Values can be entered as decimals in forms +* A unit such as centimetre, gram, or percentage can be specified + Form fields ----------- @@ -61,7 +67,7 @@ Form fields * :doc:`/ui/description` * :doc:`reference_system` * :doc:`/ui/date` -* A super (type) if it is a sub type of another type +* A super (type) if it is a sub-type of another type Can be linked via tabs to ------------------------- @@ -70,13 +76,13 @@ Can be linked via tabs to Making types required --------------------- -It is possible making specifying of types required. This can be done at the -type overview in the right information display of the respective type by users -who have at least manager permissions. +It is possible to make certain types required. To make a type required, go +to type overview. Mark it as required in the display on the right. You have +to have manager or higher status to do this. -Be careful with making types required, especially when there are users who -aren't permitted to create new ones. It may put them in an awkward situation at -data entry and, as a result, may even reduce the data quality. +Please keep in mind that not all users can add new types when making a type +required. This might lead to situations where a user is unable to choose a +fitting type for an entity and might therefore reduce data quality. -Also keep in mind, that existing entries which haven't set this type, will than -not be possible to update, without setting the required type. +Existing entries that were entered before a typ was set to required and have +no set values for this specific type can not be updated anymore afterwards.