WIP:Documentation/citation style #371

PhRosenberger · 2020-01-22T16:11:47Z

Reference to a related issue in the repository

Related to #356

Add a description

This is my proposal for a citation style. Please check before I change all existing citations and add missing ones.

Mention a member

@jdsika could you do the check?

Check the checklist

My code and comments follow the style guidelines and contributors guidelines of this project.
I have performed a self-review of my own code.
I have made corresponding changes to the documentation.
My changes generate no new warnings.
I have added tests that prove my fix is effective or that my feature works.
New and existing unit tests / travis ci pass locally with my changes.

jdsika · 2020-01-22T16:16:17Z

What citation style is this?

jdsika · 2020-01-22T16:16:29Z

doc/commenting.rst

+- For more than 3 authors, place "et al." after the third one
+- For more than 1 editor, place "et al." after the first one
+- Naming pages at the end is optional, to ease finding in long texts or for direct citations
+- Scheme is as follows (replace tags with corresponding values):


PhRosenberger · 2020-01-23T15:47:20Z

What citation style is this?

It is similiar to APA, but not identical. Here, the is at the end, whereas APA defines the in () after the author.

We can go for APA completely to have something standardized.
What do you think?

In the meantime, I continue and try out italic in document title of the reference, so there will be some slight changes.

jdsika · 2020-01-23T17:02:17Z

Complete apa is good.

PhRosenberger · 2020-01-23T22:14:01Z

So we will go for full APA style.

PhRosenberger · 2020-01-24T11:48:22Z

I have pushed the citation style section in the doc.
Next step is to change existing citations and add missing ones.

vkresch · 2020-01-24T14:25:41Z

@jdsika @PhRosenberger Just as side note for checking the sphinx rst syntax I use this site.

vkresch

@PhRosenberger Thank you for the standardization according to DIN overall looks really good. I only found really minor issues and small questions.

vkresch · 2020-01-24T14:23:35Z

doc/commenting.rst

+**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"`link <https://apastyle.apa.org/>`_ from the American Psychological Association for referencing ().


Change the link into "APA style <https://apastyle.apa.org/>_" and remove the brackets at the end.

Thank you for the support, will be changed.

vkresch · 2020-01-24T14:32:13Z

doc/commenting.rst

+- In the references list, the number in brackets [#] is followed by a full citation.
+- For writing the title in italic, use <em>title</em>
+- Author names are written as <surname>, <initial(s)> like Authorname, A. A.
+- Editor names are written as <initial(s)> <surname> like B. B. Editorname


(Minor issue) Decide on consistent period usage for bullet points.

vkresch · 2020-01-24T14:38:03Z

osi_environment.proto

    //
    // \par References:
-    // - [2] SHEPARD, Frank D. Reduced visibility due to fog on the highway.
+    // - [2] SHEPARD, Frank D. <em>Reduced visibility due to fog on the highway.</em>


Should the bullet point here be removed too like in the example in comment.rst?

I am not done with the .proto files, so yes, I will remove the bullet points.

vkresch · 2020-01-24T14:38:43Z

osi_environment.proto

-    // - [2] SHEPARD, Frank D. Reduced visibility due to fog on the highway.
+    // - [2] SHEPARD, Frank D. <em>Reduced visibility due to fog on the highway.</em>
    // Transportation Research Board, 1996.
    // - [3] [StVO 17 chapter


Here, too? (bullet point removal)

PhRosenberger

@jdsika @PhRosenberger Just as side note for checking the sphinx rst syntax I use this site.

I use CLion as IDE, which has y build in interpreter, which is very comfy:-)

PhRosenberger · 2020-01-24T17:15:09Z

doc/commenting.rst

        //
        // \par Reference:
-        // [1] Rapp, C.: Grundlagen der Physik, in: Hydraulik für Ingenieure und Naturwissenschaftler, Springer Vieweg, Wiesbaden, 2017, p. 105
+        // [1] Rapp, C. (2017). Grundlagen der Physik. <em>In Hydraulik für Ingenieure und Naturwissenschaftler</em> (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105.


Actually, I am wondering if the length of the line for the reference in the comments could be to long like this.
@vkresch and @jdsika is there a limitation or style-standard for this?

PhRosenberger · 2020-01-26T16:19:42Z

So, I am done with the existing citations. For adding new citations, where they are missing, I would propose to create a new branch. Actually, it took a lot of time to find a good citation style and especially for correcting the existing ones, so finding missing citations will take probably even more time.

A possible work-around could be to wait for ISO23150 to be publicly available and cite this then. What do you think, @jdsika, @vkresch, and others?

PhRosenberger · 2020-01-26T16:25:37Z

Actually, the line breaking with " \n " from the last commit fails because of the non-ASCII testing.
Should we change the code or the test?

vkresch · 2020-01-27T08:24:27Z

@PhRosenberger it's mostly because of the character "ß" in "Straßenverkehrs-Ordnung" and "ü" in "für". So basically we need to decide if we want to cite only in english or only in german. If we decide on german then we need to remove the non-ascii test. This could cause some bugs/erros in the doxygen generation since this is the reason behind the test. This should be tested accordingly.
To stay with german we could also use "ue" instead of "ü" and "ss" instead of "ß".
@jdsika what do you think?

jdsika · 2020-01-27T09:42:37Z

I would go for an "english only" style

PhRosenberger · 2020-01-31T15:27:11Z

I would go for an "english only" style

Does this mean only English sources?
Could be difficult regarding e.g. DIN standards..

I prefer to change writing into "ss", "ue", "ae", and "oe".

PhRosenberger · 2020-01-31T16:49:22Z

Ready for merge into master now.

PhRosenberger · 2020-02-05T13:55:02Z

@jdsika and @vkresch can we merge this branch now?
Still open:

Is there a limitation on line legth for the citations as comments?
Is writing the German letters ü, ä, ö, ß with ue, oe, ae, ss fine for everybody?

jdsika · 2020-02-05T14:33:21Z

I am fine with ö as oe!
@vkresch please review

vkresch

Looks good to me. I'm not sure if the line length influences the doxygen ouput. Normally it shouldn't.

jdsika · 2020-02-05T15:15:08Z

@PhRosenberger thank you very much - good job!

PhRosenberger added 2 commits January 21, 2020 19:44

referencing work ongoing

620a19b

citation style added for commenting

41d26a7

PhRosenberger mentioned this pull request Jan 22, 2020

Citation style #356

Closed

jdsika added this to the v3.1.3 milestone Jan 22, 2020

jdsika requested a review from vkresch January 22, 2020 16:14

jdsika added the Documentation Everything which impacts the quality of the documentation and guidelines. label Jan 22, 2020

jdsika reviewed Jan 22, 2020

View reviewed changes

ongoing work

ef1ca1a

PhRosenberger changed the title ~~Documentation/citation style~~ WIP:Documentation/citation style Jan 23, 2020

Commenting style definition done.

3dc8c3f

vkresch requested changes Jan 24, 2020

View reviewed changes

PhRosenberger commented Jan 24, 2020

View reviewed changes

PhRosenberger added 2 commits January 24, 2020 16:00

Typo-correction on doc/commenting.proto

ab3e4a9

Example citation corrected in doc/commenting.proto

19fcacd

PhRosenberger commented Jan 24, 2020

View reviewed changes

PhRosenberger added 5 commits January 24, 2020 19:49

Typos in doc/commenting.rst

2472d27

All existing citations are now correct.

c08a2f2

Citation in README.md corrected

3a12987

References must be line seperated for correct displaying.

e72ff5e

Line break for references-list changed to adding ' \n ' at the end.

c478a88

PhRosenberger and others added 5 commits January 31, 2020 16:42

German Umlaute changed for ASCII conformity.

c41f71d

Merge branch 'master' into documentation/citation-style

ef1ac4c

still existing non-ASCII changed.

57a156f

Non-ASCII accent changed in citation.

66cc11f

Accent character changed

6a514a2

jdsika requested a review from vkresch February 5, 2020 14:32

vkresch approved these changes Feb 5, 2020

View reviewed changes

jdsika merged commit b64133d into master Feb 5, 2020

pmai deleted the documentation/citation-style branch April 27, 2020 11:41

WIP:Documentation/citation style #371

WIP:Documentation/citation style #371

Uh oh!

Conversation

PhRosenberger commented Jan 22, 2020

Reference to a related issue in the repository

Add a description

Mention a member

Check the checklist

Uh oh!

jdsika commented Jan 22, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PhRosenberger commented Jan 23, 2020

Uh oh!

jdsika commented Jan 23, 2020

Uh oh!

PhRosenberger commented Jan 23, 2020

Uh oh!

PhRosenberger commented Jan 24, 2020

Uh oh!

vkresch commented Jan 24, 2020

Uh oh!

vkresch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PhRosenberger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PhRosenberger commented Jan 26, 2020

Uh oh!

PhRosenberger commented Jan 26, 2020

Uh oh!

vkresch commented Jan 27, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdsika commented Jan 27, 2020

Uh oh!

PhRosenberger commented Jan 31, 2020

Uh oh!

PhRosenberger commented Jan 31, 2020

Uh oh!

PhRosenberger commented Feb 5, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdsika commented Feb 5, 2020

Uh oh!

vkresch left a comment

Choose a reason for hiding this comment

Uh oh!

jdsika commented Feb 5, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vkresch commented Jan 27, 2020 •

edited

Loading

PhRosenberger commented Feb 5, 2020 •

edited

Loading