WIP: Documentation/citation style (#371)

* Commenting style definition: APA
* Typo-corrections in documentation
* Example citation corrected in doc/commenting.proto
* Citation in README.md corrected
* References must be line seperated for correct displaying
* Line break for references-list changed to adding ' \n ' at the end
* German Umlaute changed for ASCII conformity
* Non-ASCII accent changed in citation
* Accent character changed

Author: PhRosenberger

README.md

@@ -12,7 +12,7 @@ In this context, OSI defines generic interfaces to ensure modularity, integrabil
 
 For more information on OSI see the [official documentation](https://opensimulationinterface.github.io/osi-documentation/) or the [official reference documentation](https://opensimulationinterface.github.io/open-simulation-interface/) for defined protobuf messages. 
 
-[[1]](https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/) *A generic interface for the environment perception of automated driving functions in virtual scenarios.(Dated 03.02.2017) T. Hanke, N. Hirsenkorn, C. van-Driesten, P. Garcia-Ramos, M. Schiementz, S. Schneider, E. Biebl*
+[1] Hanke, T., Hirsenkorn, N., van-Driesten, C., Garcia-Ramos, P., Schiementz, M., Schneider, S. & Biebl, E. (2017, February 03). *A generic interface for the environment perception of automated driving functions in virtual scenarios.* Retrieved January 25, 2020, from https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/ 
 
 ## Usage
 ##### Example of writing and reading an OSI message in `Python`

doc/commenting.rst

@@ -7,9 +7,8 @@ During the building process of open simulation interface (using the `proto2cpp <
 
 For any additional comment styles see `list <http://www.doxygen.nl/manual/commands.html>`_ of doxygen commands.
 
-Reference for writing values and units: ISO 80000-1: 2009, Quantities and units – Part 1: General
-Nice summary: [Rohde & Schwarz: Der korrekte Umgang mit Größen, Einheiten und Gleichungen ](https://karriere.rohde-schwarz.de/fileadmin/customer/downloads/PDF/Der_korrekte_Umgang_mit_Groessen_Einheiten_und_Gleichungen_bro_de_01.pdf
-)
+Reference for writing values and units: ISO 80000-1:2013-08, Quantities and units – Part 1: General
+Nice summary in German: `Rohde & Schwarz: Der korrekte Umgang mit Groessen, Einheiten und Gleichungen <https://karriere.rohde-schwarz.de/fileadmin/customer/downloads/PDF/Der_korrekte_Umgang_mit_Groessen_Einheiten_und_Gleichungen_bro_de_01.pdf>`_
 
 
 Commenting with block syntax
@@ -150,7 +149,7 @@ Then you describe the field by adding an explanation.
     //
     message EnvironmentalConditions
     {
-        // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 Pa).
+        // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa).
         //
         optional double atmospheric_pressure = 1;
     }
@@ -169,7 +168,7 @@ Next you decide the unit of the field.
     //
     message EnvironmentalConditions
     {
-        // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 Pa).
+        // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa).
         //
         // Unit: Pa
         //
@@ -190,7 +189,7 @@ You can optionally add a note to the field to describe the field better.
     //
     message EnvironmentalConditions
     {
-        // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 Pa).
+        // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa).
         //
         // Unit: Pa
         //
@@ -199,7 +198,32 @@ You can optionally add a note to the field to describe the field better.
         optional double atmospheric_pressure = 1;
     }
 
-If you want to provide a reference to a DIN or to web page which helps in understanding the field you can add a reference.
+To help understanding the field, you should add a reference.
+Every OSI message should be defined properly and should have a well cited reference.
+
+**Citation style for different sources:**
+
+- Within the text, the number system is used with the number of the source in brackets [#] for mentioning.
+- We use the so called `"APA style" <https://apastyle.apa.org/>`_ from the American Psychological Association for referencing.
+- In the references list, the number in brackets [#] is followed by a full citation.
+- For writing the title in italic, use <em>title</em>.
+- If the list contains more than one entry, add " \n " at the end of the line to create a line break within the list.
+- Author names are written as <surname>, <initial(s)> like Authorname, A. A.
+- Editor names are written as <initial(s)> <surname> like B. B. Editorname.
+- Naming pages at the end is optional to enable finding in long texts or for direct citations.
+- All citations should be primary citations. Sources like Wikipedia et al. are not allowed.
+- Find filled-out examples under `https://apastyle.apa.org <https://apastyle.apa.org/style-grammar-guidelines/references/examples>`_ and in existing entries.
+- The scheme of popular sources for the reference list is as follows (replace tags with corresponding values):
+
+.. [#] <author1>, <author2>, <author3> & <author4>. (<year>). Contribution in a compilation title. <em><Compilation Title></em>. <edition>. <page(s)>. <publisher>. <location>. <doi>. <page(s)>.
+.. [#] <author1>, <author2> & <author3>. (<year>). <em><book (monograph) title></em>. <edition>. <publisher>. <doi>. <page(s)>.
+.. [#] <author1> & <author2>. (<year>). <book chapter title>. In <editor1> & <editor2> (Eds.), <em><book title></em> (<page(s)>). <publisher>. <doi>. <page(s)>.
+.. [#] <author1> & <author2>. (<year>). <journal article title>. <em><journal title></em>. <page(s)>. <location>. <doi>. <page(s)>.
+.. [#] <author>. (<year>). <em><Phd thesis title></em>. Phd. thesis. <location>. <university>. <doi or url>. <page(s)>.
+.. [#] <author>. (<year>, <month> <day>). <em><internet article title></em>. Retrieved <month> <day>, <year>, from <url>.
+.. [#] <standarding organisation>. (<year>). <em><title of the standard></em>. (<standard identifier>). <location>.
+.. [#] <author>. (<year>). <em><patent title and id></em>. <location>. <organisation>.
+
 
 .. code-block:: protobuf
 
@@ -213,14 +237,15 @@ If you want to provide a reference to a DIN or to web page which helps in unders
     //
     message EnvironmentalConditions
     {
-        // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 Pa).
+        // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa) [1, 2].
         //
         // Unit: Pa
         //
         // \note 100000 Pa = 1 bar
         //
-        // \par Reference:
-        // - [1] [Definition atmospheric pressure](https://en.wikipedia.org/wiki/Atmospheric_pressure)
+        // \par References:
+        // [1] DIN Deutsches Institut fuer Normung e. V. (1982). <em>DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik</em>. (DIN 5031-3:1982-03). Berlin, Germany. \n
+        // [2] Rapp, C. (2017). Grundlagen der Physik. In <em>Hydraulik fuer Ingenieure und Naturwissenschaftler</em> (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105.
         //
         optional double atmospheric_pressure = 1;
     }
@@ -239,14 +264,15 @@ Finally you can provide a set of rules which this field needs to be followed. Th
     //
     message EnvironmentalConditions
     {
-        // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 Pa).
+        // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa) [1, 2].
         //
         // Unit: Pa
         //
         // \note 100000 Pa = 1 bar
         //
-        // \par Reference:
-        // - [1] [Definition atmospheric pressure](https://en.wikipedia.org/wiki/Atmospheric_pressure)
+        // \par References:
+        // [1] DIN Deutsches Institut fuer Normung e. V. (1982). <em>DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik</em>. (DIN 5031-3:1982-03). Berlin, Germany. \n
+        // [2] Rapp, C. (2017). Grundlagen der Physik. In <em>Hydraulik fuer Ingenieure und Naturwissenschaftler</em> (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105.
         //
         // \rules
         // is_optional
@@ -318,8 +344,8 @@ If you want to reference message fields and enums add '#' to the enum/field name
 
     // A reference to a enum e.g. \c #COLOR_GREEN.
 
-Commenting with links
-----------------------
+Commenting with links (e.g. in references)
+------------------------------------------
 With ``[<add name of your link>](<add url of your link>)`` you can integrate a link to a certain homepage while commenting.
 
 Commenting with images

osi_common.proto

@@ -166,8 +166,8 @@ message Dimension3d
 // \attention This definition changed in OSI version 3.0.0. Previous OSI
 // versions  (V2.xx) had an other definition.
 //
-// \par References:
-// - [1] DIN ISO 8855:2013-11
+// \par Reference:
+// [1] DIN Deutsches Institut fuer Normung e. V. (2013). <em>DIN ISO 8855 Strassenfahrzeuge - Fahrzeugdynamik und Fahrverhalten - Begriffe</em>. (DIN ISO 8855:2013-11). Berlin, Germany.
 //
 message Orientation3d
 {

osi_detectedobject.proto

@@ -15,7 +15,7 @@ package osi3;
 message DetectedItemHeader
 {
     // Specific ID of the detected item as assigned by the sensor internally.
-    // Need not match with \c #ground_truth_id.
+    // Needs not to match with \c #ground_truth_id.
     //
     optional Identifier tracking_id = 1;
 
@@ -215,28 +215,28 @@ message DetectedMovingObject
 
     // Additional data that is specific to radar sensors.
     //
-    // \note Field need not be set if simulated sensor is not a radar
+    // \note Field needs not to be set if simulated sensor is not a radar
     // sensor.
     //
     optional RadarSpecificObjectData radar_specifics = 100;
 
     // Additional data that is specific to lidar sensors.
     //
-    // \note Field need not be set if simulated sensor is not a lidar
+    // \note Field needs not to be set if simulated sensor is not a lidar
     // sensor.
     //
     optional LidarSpecificObjectData lidar_specifics = 101;
 
     // Additional data that is specific to camera sensors.
     //
-    // \note Field need not be set if simulated sensor is not a camera
+    // \note Field needs not to be set if simulated sensor is not a camera
     // sensor.
     //
     optional CameraSpecificObjectData camera_specifics = 102;
 
     // Additional data that is specific to ultrasonic sensors.
     //
-    // \note Field need not be set if simulated sensor is not an ultrasonic
+    // \note Field needs not to be set if simulated sensor is not an ultrasonic
     // sensor.
     //
     optional UltrasonicSpecificObjectData ultrasonic_specifics = 103;
@@ -275,36 +275,36 @@ message DetectedMovingObject
         // Pedestrian head pose for behavior prediction. Describes the head
         // orientation w.r.t. the host vehicle orientation.
         // The x-axis of the right-handed head frame is pointing along the
-        // pedestrian's straight ahead viewing direction and the z-axis is
-        // pointing upwards (cranial direction [1] i.e. to pedestrian's skull
-        // cap).
+        // pedestrian's straight ahead viewing direction (anterior), the y-axis lateral to the left,
+        // and the z-axis is pointing upwards (superior) [1].
         //
         // ``View_normal_base_coord_system =
         // Inverse_Rotation(#head_pose)*Unit_vector_x``
         //
         // \note This field is mandatory if the \c CandidateMovingObject.type is
         // \c MovingObject::TYPE_PEDESTRIAN
         //
-        // \par References:
-        // - [1] https://en.wikipedia.org/wiki/Anatomical_terms_of_location
+        // \par Reference:
+        //
+        // [1] Patton, K. T. & Thibodeau, G. A. (2015). <em>Anatomy & Physiology</em>. 9th Edition. Elsevier. Missouri, U.S.A. ISBN 978-0-323-34139-4. p. 1229.
         //
         optional Orientation3d head_pose = 4;
 
         // Pedestrian upper body pose for behavior prediction. Describes the
         // upper body orientation w.r.t. the host vehicle orientation.
         // The x-axis of the right-handed upper body frame is pointing along the
-        // pedestrian's upper body ventral direction [2] (i.e. usually
-        // pedestrian's intended moving direction) and the z-axis is pointing
-        // upwards (to pedestrian's head).
+        // pedestrian's upper body ventral (anterior) direction (i.e. usually
+        // pedestrian's intended moving direction), the y-axis lateral to the left,
+        // and the z-axis is pointing upwards (superior, to the pedestrian's head) [1].
         //
         // ``View_normal_base_coord_system =
         // Inverse_Rotation(#upper_body_pose)*Unit_vector_x``
         //
         // \note This field is mandatory if the \c CandidateMovingObject::type
         // is \c MovingObject::TYPE_PEDESTRIAN
         //
-        // \par References:
-        // - [2] https://en.wikipedia.org/wiki/Anatomical_terms_of_location
+        // \par Reference:
+        // [1] Patton, K. T. & Thibodeau, G. A. (2015). <em>Anatomy & Physiology</em>. 9th Edition. Elsevier. Missouri, U.S.A. ISBN 978-0-323-34139-4. p. 1229.
         //
         optional Orientation3d upper_body_pose = 5;
     }