yade-dev team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 2842
committer: Bruno Chareyre <bruno.chareyre@xxxxxxxxxxx>
branch nick: trunk
timestamp: Wed 2011-04-27 19:21:19 +0200
message:
  - more explicit notes on citing (I realized it was not clear while reviewing a paper citing yade ;-))
  - again small fixes in the "development tools" section
modified:
  doc/sphinx/citing.rst
  doc/sphinx/prog.rst


--
lp:yade
https://code.launchpad.net/~yade-dev/yade/trunk

Your team Yade developers is subscribed to branch lp:yade.
To unsubscribe from this branch go to https://code.launchpad.net/~yade-dev/yade/trunk/+edit-subscription

=== modified file 'doc/sphinx/citing.rst'
--- doc/sphinx/citing.rst	2011-02-14 13:35:11 +0000
+++ doc/sphinx/citing.rst	2011-04-27 17:21:19 +0000
@@ -6,26 +6,30 @@
 
 In order to let users cite Yade consistently in publications, we provide a list of bibliographic references for the different parts of the documentation, as in the citation model pushed by `CGAL <http://www.cgal.org/bibliography.html>`_. This way of acknowledging Yade is also a way to make developments and documentation of Yade more attractive for researchers, who are evaluated on the basis of citations of their work by others. We therefore kindly ask users to cite Yade as accurately as possible in their papers. A more detailed discussion of the citation model and its application to Yade can be found `here <https://yade-dem.org/w/images/c/c9/AcknowledgingYADE.pdf>`_.
 
-If new developments are presented and explained in self-contained papers, we will be glad to include them in the documentation and to reference them in the list below. Any other substantial improvement is welcome and can be discussed in the `yade-dev <https://www.yade-dem.org/wiki/Contact>`_ mailing list.
+If new developments are presented and explained in self-contained papers (at the end of a PhD, typically), we will be glad to include them in the documentation and to reference them in the list below. Any other substantial improvement is welcome and can be discussed in the `yade-dev <https://www.yade-dem.org/wiki/Contact>`_ mailing list.
 
 Citing chapters of Yade Documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The first edition of Yade documentation is seen as a collection with three volumes (or "chapters"), also provided as `bibtex entries <http://bazaar.launchpad.net/~yade-dev/yade/trunk/view/head:/doc/citing_yade.bib>`_:
-
-* The reference documentation includes details on equations and algorithms found at the highest levels of Yade. Citation of, namely, contact laws, boundary conditions controllers, pre- and post-processing modules, is using `(pdf version) <https://yade-dem.org/w/images/9/98/YadeRefDoc.pdf>`_:
+The first edition of Yade documentation is seen as a collection with the three volumes (or "chapters") listed below, also provided as `bibtex entries <http://bazaar.launchpad.net/~yade-dev/yade/trunk/view/head:/doc/citing_yade.bib>`_. Please cite the chapter that is the most relevant in your case. For instance, a paper using one of the documented contact laws will cite the reference documentation [yade:reference]_; if programing concepts are discussed, Yade's manual [yade:manual]_ will be cited; the theoretical background [yade:background]_ can be used as the refence for contact detection, time-step determination, or periodic boundary conditions.
+
+If it is not possible to choose the right chapter (but please try), you may cite the documentation [yade:doc]_ as a whole.
+
+* The reference documentation includes details on equations and algorithms found at the highest levels of Yade (contact laws, boundary conditions controllers, pre- and post-processing modules,...) `(pdf version) <https://yade-dem.org/w/images/9/98/YadeRefDoc.pdf>`_:
 	V. Šmilauer, E. Catalano, B. Chareyre, S. Dorofeenko, J. Duriez, A. Gladky, J. Kozicki, C. Modenese, L. Scholtès, L. Sibille, J. Stránský, and K. Thoeni, “Yade Reference Documentation,” in Yade Documentation (V. Šmilauer, ed.), The Yade Project, 1st ed., 2010. http://yade-dem.org/doc/.
 
 * Software design, user's and programmer's manuals are in `(pdf version) <https://yade-dem.org/w/images/0/09/YadeManuals.pdf>`_:
 	V. Šmilauer, A. Gladky, J. Kozicki, C. Modenese, and J. Stránský, “Yade Using and Programming,” in Yade Documentation (V. Šmilauer, ed.), The Yade Project, 1st ed., 2010. http://yade-dem.org/doc/.
 
 * Fundamentals of the DEM as implemented in Yade are explained in `(pdf version) <https://yade-dem.org/w/images/e/e0/YadeFormulation.pdf>`_:
-	V. Šmilauer and B. Chareyre, “Yade Dem Formulation,” in Yade Documentation (V. Šmilauer, ed.), The Yade Project, 1st ed., 2010. http://yade-dem.org/doc/formulation.html.
+	V. Šmilauer and B. Chareyre, “Yade Dem Formulation”, in Yade Documentation (V. Šmilauer, ed.), The Yade Project, 1st ed., 2010. http://yade-dem.org/doc/formulation.html.
 
+* The documentation as a whole:
+	V. Šmilauer, E. Catalano, B. Chareyre, S. Dorofeenko, J. Duriez, A. Gladky, J. Kozicki, C. Modenese, L. Scholtès, L. Sibille, J. Stránský, and K. Thoeni, Yade Documentation (V. Šmilauer, ed.), The Yade Project, 1st ed., 2010. http://yade-dem.org/doc/.
 
 
 Citing Yade a a whole
 ^^^^^^^^^^^^^^^^^^^^^
-If you want to cite the Yade project as whole, use this reference (not recommended in scientific papers):
+If you want to cite the Yade project itself, use the reference below. It is not recommended in scientific publications, since it doesn't point to a specific document and it doesn't define any authorship:
 
 “Yade: Open source discrete element method.” http://yade-dem.org.
 

=== modified file 'doc/sphinx/prog.rst'
--- doc/sphinx/prog.rst	2011-04-27 13:58:19 +0000
+++ doc/sphinx/prog.rst	2011-04-27 17:21:19 +0000
@@ -212,7 +212,7 @@
 ----------------------
 The Yade project is kindly hosted at `launchpad <https://launchpad.net/yade/>`__, which is used for source code, bug tracking, planning, package downloads and more. Our repository `can be http-browsed <http://bazaar.launchpad.net/~vcs-imports/yade/trunk/files>`__.
 
-The versioning software used is `Bazaar <http://www.bazaar-vcs.org>`__, for wich a short tutorial can be found in a `Yade's wiki pages <https://yade-dem.org/wiki/Quick_Bazaar_tutorial>`__. Bazaar is a distributed revision control system. It is available packaged for all major linux distributions.
+The versioning software used is `Bazaar <http://www.bazaar-vcs.org>`__, for which a short tutorial can be found in a `Yade's wiki pages <https://yade-dem.org/wiki/Quick_Bazaar_tutorial>`__. Bazaar is a distributed revision control system. It is available packaged for all major linux distributions.
 
 Build robot
 -----------