# HG changeset patch
# User Ashwin Vishnu <avmo@kth.se>
# Date 1517496253 -3600
#      Thu Feb 01 15:44:13 2018 +0100
# Node ID 0b1029993881e4d9dc6d361af740bc139f037c6e
# Parent  6321fada4a28600dcfbb9ab3e239d327fb23b685
A lot of rephrasing and some new content

diff --git a/bib.bib b/bib.bib
--- a/bib.bib
+++ b/bib.bib
@@ -141,3 +141,33 @@
   author={Burns, KJ and Vasil, GM and Oishi, JS and Lecoanet, D and Brown, BP and Quataert, E},
   publisher={preparation}
 }
+
+
+@techreport{hooton_christopher_refreshing_2017,
+	title = {Refreshing {Our} {Understanding} of the {Internet} {Economy}},
+	url = {https://internetassociation.org/reports/refreshing-understanding-internet-economy-ia-report/},
+	abstract = {Internet Association's first economic white paper takes a closer look at the size of the internet economy, both in the U.S. and abroad.},
+	language = {en-US},
+	urldate = {2018-02-01},
+	author = {Hooton, Christopher},
+	month = jan,
+	year = {2017},
+}
+
+@article{wilson_best_2014,
+	title = {Best {Practices} for {Scientific} {Computing}},
+	volume = {12},
+	issn = {1545-7885},
+	url = {http://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.1001745},
+	doi = {10.1371/journal.pbio.1001745},
+	abstract = {We describe a set of best practices for scientific software development, based on research and experience, that will improve scientists' productivity and the reliability of their software.},
+	language = {en},
+	number = {1},
+	urldate = {2018-02-02},
+	journal = {PLOS Biology},
+	author = {Wilson, Greg and Aruliah, D. A. and Brown, C. Titus and Hong, Neil P. Chue and Davis, Matt and Guy, Richard T. and Haddock, Steven H. D. and Huff, Kathryn D. and Mitchell, Ian M. and Plumbley, Mark D. and Waugh, Ben and White, Ethan P. and Wilson, Paul},
+	month = jan,
+	year = {2014},
+	keywords = {Computer software, Computers, Open source software, Programming languages, Research validity, Scientists, Software development, Software tools},
+	pages = {1--7},
+}
diff --git a/fluiddyn/Makefile b/fluiddyn/Makefile
--- a/fluiddyn/Makefile
+++ b/fluiddyn/Makefile
@@ -22,6 +22,7 @@
 
 vimtex:
 	gvim $(name).tex --servername GVIM &
+	# xterm -class GVIM -e vim $(name).tex --servername GVIM &
 
 doit: vimtex $(name).pdf
 	zathura $(name).pdf &
diff --git a/fluiddyn/fluiddyn_paper.tex b/fluiddyn/fluiddyn_paper.tex
--- a/fluiddyn/fluiddyn_paper.tex
+++ b/fluiddyn/fluiddyn_paper.tex
@@ -64,28 +64,31 @@
 % architected, where it is stored, and its reuse potential.}
 
 \href{http://fluiddyn.readthedocs.io}{FluidDyn} is a project to foster
-open-science and open-source in the fluid dynamics community.  It is thought as
-a research project on how to use open-source dynamics, methods and tools to do
+open-science and open-source in the fluid dynamics community.  It is thought of
+as a research project to channel open-source dynamics, methods and tools to do
 better science.
 %
 We propose a set of Python packages forming a framework to study fluid dynamics
 with different methods, in particular laboratory experiments (package
 \fluidpack{lab}), simulations (packages \fluidpack{fft}, \fluidpack{sim} and
-\fluidpack{foam}) and data processing (package \fluidpack{image}).  In this
-article, we give an overview of the specialized packages of the project
-(\fluidpack{fft} and \fluidpack{sim} are described more precisely in two
-companion papers) and then focus on the base package called \fluidpack{dyn},
-which contains common code used in the specialized packages.
+\fluidpack{foam}) and data processing (package \fluidpack{image}). 
+In the present article, we review the recent advancements in web-based software
+development tools and Python which facilitated the execution of this project.
+We give an overview of the specialized packages of the project and then
+focus on the base package called \fluidpack{dyn}, which contains common code
+used in the specialized packages.  Packages \fluidpack{fft} and \fluidpack{sim}
+are described with greater detail in two companion papers, \citet{fluidfft,
+fluidsim}.
 %
-With the projet FluidDyn, we demonstrate that specialized scientific code can
+With the project FluidDyn, we demonstrate that specialized scientific code can
 be written with methods and good practices of the open-source community. The
-Mercurial repositories are available in bitbucket
+Mercurial repositories are available in Bitbucket
 (\url{https://bitbucket.org/fluiddyn/}). All codes are documented using Sphinx
-and Readthedocs, and tested with continuous integration run on Bitbucket
-Pipeline and Travis.
+and Read the Docs, and tested with continuous integration run on Bitbucket
+Pipelines and Travis.
 %
-To improve the reuse potential, the codes are as modular as possible taking
-advantage of the simple object-oriented programming model of Python.
+To improve the reuse potential, the codes are as modular as possible, leveraging
+the simple object-oriented programming model of Python.
 %
 All codes are also written to be highly efficient, using C++, Cython and
 Pythran to speedup the performance of critical functions.
@@ -112,94 +115,107 @@
 \href{https://en.wikipedia.org/wiki/%
 Standing_on_the_shoulders_of_giants}{``standing on the shoulders of giants''}
 (and of a huge number of technicians and scientists).  Science is a lot about
-how to build new knowledge from the work of others so of course, the exchange
+how to build new knowledge from the work of others and hence, the exchange
 of ideas is a fundamental aspect.
-
-These last decades, we have lived a revolution on how people exchange ideas.
+%
+In the last decades, we have lived through a revolution on how people exchange
+ideas.
 %
 Computers of all kinds (from smartphones to HPC clusters) connected by a world
 wide web are used for human communication and also for many other applications.
 %
-It has become very easy to reproduce and exchange ideas and data.
+It has become nearly effortless to reproduce and exchange ideas and data.
 %
-The set of things that you can give without loosing them, as knowledge and
-love, has been somehow extended.
+The set of intangibles that grows when shared and degrades when hoarded, such as
+knowledge and love, has been somehow extended.
+% Relevant quote: 
+% O Goddess Saraswati, your Treasure is unique in nature.  It increases when it
+% is freely spent and gets destroyed if it is hoarded (and not shared with
+% others).
 %
 The information technology revolution opens fantastic opportunities for human
-collaboration and of course for science.
+collaboration, and of course, for science.
 
-The web related activities represent in 2017 approximately 5\% of GDP in the
-USA!  
-% reference?
-A huge amount of money (and work) is spent for the related technologies.  We
-all know the most powerful and famous companies involved in this dynamics
-(Google, Facebook, ...), but there are several other companies smaller and less
-known. Most of these companies base part of their work on the open-source
-paradigm and use and contribute to open-source languages, libraries, software
-and operating systems.
+Web related activities alone account for atleast 5\% of GDP in the USA and the
+European Union\footnote{See the report by Internet Association titled
+\href{https://internetassociation.org/reports/refreshing-understanding-internet-economy-ia-report/}
+{``Refreshing Our Understanding of the Internet Economy''}}.
+% \cite{hooton_christopher_refreshing_2017}.
+A huge amount of money (and work) is invested on the related technologies. We
+are familiar with the most prominent companies involved in this dynamics
+(Google, Facebook, etc.), but there are also several smaller and sometimes
+lesser known organizations.  Most of these companies base part of their work on
+the open-source paradigm contributing to open-source languages, libraries,
+software and operating systems, while also using them --- a win-win situation
+for both the corporations and the community.
 %
 This has lead to deep changes in software engineering, with a massive use of
-open-source methods and tools, for example distributed source management tools
-and web-based source development tools.
+open-source methods and tools, for example
+\href{https://en.wikipedia.org/wiki/Distributed_version_control}{distributed
+version control systems (DVCS)} and web-based source development platforms.
 
-The computer performance still increases exponentially, now also with the help
-of Graphical Processing Units (GPU).  This has allowed a big boom in practical
-uses of data science and machine learning, which drives a strong research on
-artificial intelligence.  This dynamics contributes to progresses in
-open-source software.
+The computer performance continues to
+\href{https://en.wikipedia.org/wiki/Moore\%27s_law}{increase exponentially},
+now also with the help of Graphical Processing Units (GPU). This gave way to a
+big boom in practical uses of data science and machine learning, which drives a
+strong research on artificial intelligence.  This dynamics contribute to
+progresses in open-source software.
 
-These dynamics are changing our world and also the way science is done.
+These changes in our world also reflect in the way science is done.
 %
-Software and programming in science take a much bigger place than before.
+Software and programming in science occupy a much bigger place than before.
 %
 % see http://sciencecodemanifesto.org/
 % http://lorenabarba.com/gallery/reproducibility-pi-manifesto/
 % https://www.numfocus.org/
 %
-The status of software has changed.  Before coding was sometimes badly
-considered by some scientists.  It is thought that a mathematical
-demonstration has to be elegant and that it is normal to included it in a
-paper.  In contrast, it was normal to write crappy code and to just show the
-results. Now, codes tend to be much more at the center of research.
+The role of software in science has changed. In the past, coding was sometimes
+considered as an inferior activity by some scientists.  The focus was on the
+theory and the mathematical demonstration, which had to be elegant as it gets to
+included in a paper.  In contrast, it was normal to write crude code
+% av: crappy = shitty!
+% alternatives: shabby, inelegant, amateurish, unpolished, clumsy
+% https://en.oxforddictionaries.com/thesaurus/amateurish
+and to just show the results. Nowadays, codes tend to be at the heart of research.
 
-``Open-science'' is a new trend taking advantage of these new facts.  Pioneers
-try to do better science, improving reproducibility and collective efficiency,
-by using the open-source methods and tools for science and sharing and
-collaborating via the world wide web.
+``Open-science'' is a new trend taking advantage of these new facts.  Pioneering
+attempts are being made to do better science, improving reproducibility and
+collective efficiency, by using the open-source methods and tools for science
+and sharing and collaborating via the world wide web.
 
 % http://www.nature.com/news/interactive-notebooks-sharing-the-code-1.16261
 
 This paper presents FluidDyn: a project to foster open-science and open-source
-in fluid mechanics. This first section ``Overview'' is organized in two large
+in fluid mechanics. The first section ``Overview'' is organized into two large
 parts.  A long introduction presents the context and describes our motivations
-and the concept of the project FluidDyn.
+and the concept behind the project FluidDyn.
 %
 The second subsection called ``Implementation and architecture'' is devoted to
 present the organization of the packages of the project and to describe in more
-details the base package \fluiddyn\footnote{We use FluidDyn (with capital
+detail the base package \fluiddyn\footnote{We use FluidDyn (with capital
 letters) to name the project and \fluiddyn for the base package.}.
 
-The following of this introduction is organized as follow.
+The following introduction is organized as follows
 \begin{itemize}
-\item A scientific project based on the collaboration through open-source as
-FluidDyn is possible only thanks to the recent developments in methods and
+\item A scientific project based on the collaboration through open-source, such
+as FluidDyn, is only possible thanks to the recent developments in methods and
 tools for open-source software engineering. We start by presenting these
 developments and discuss the implications for the scientists.
 
-\item FluidDyn is based on the language Python. Moreover, these are the
-characteristics of Python which make possible the possible success of such
-project.
+\item FluidDyn is based on the language Python. Incidently, it is the defining
+characteristics of Python which make the eventual success of such a
+project realizable.
 
 Python is a very important tool in recent open-source dynamics and in
 particular in science (see \href{https://stackoverflow.blog/2017/09/06/%
-incredible-growth-python/}{this article of the Stackoverflow blog} and
+incredible-growth-python/}{this blog post by Stack Overflow} and
 \href{https://spectrum.ieee.org/computing/software/%
 the-2017-top-programming-languages}{this analysis on the top programming
-languages 2017}).
+languages of 2017}).
 %
-Python in fluid mechanics is growing fast but is still only weakly used. It is
-thus still useful to present its characteristics for readers potentially not
-specialist in programming.
+Python in fluid mechanics is growing fast, but is yet to reach widespread
+adoption as the language of choice. Therefore, it is useful to present its
+characteristics for readers who are unacquainted with its nuances.
 
 \item We will discuss about the possible contradiction between productivity of
 individuals and productivity at the community level.
@@ -207,73 +223,100 @@
 \item We will establish a picture of software engineering in fluid mechanics
 and present some of the main tools commonly used.
 
-\item The introduction finally ends by a summary of the motivations for the
+\item The introduction finally ends with a summary of the motivations for the
 project FluidDyn and a presentation of its principles.
 \end{itemize}
 
 
 \subsection*{Methods and tools for open-source software engineering}
 
-\subparagraph{Distributed source management tools and web-based source
-development tools.}  The collective collaboration on development has been
-greatly eased with the apparition of distributed source management programs (in
-particular Git and Mercurial) and web-based source development tools like
-Github, Bitbucket and more recently Gitlab.
+\subparagraph{Distributed version control systems (DVCS) and web-based source
+development platforms.} The collective collaboration on development has been
+greatly eased with the emergence of DVCS (especially, Git and Mercurial) and
+web-based source development platforms like Github, Bitbucket and more recently
+Gitlab.
 %
-These tools are designed to work collectively on text files so they could also
-be very useful to collectively write scientific documents.
+These tools are designed to work on any kind of text files, not just codes, so
+they could even be utilized to write scientific documents with multiple authors.
 %
-These tools are so useful for collective work that a young scientific of today
-should now master them and be aware of the notions of repository,
-changeset, commit, clone, pull, push, fork and pull request.
+These tools are so useful for work, that mastering DVCS and the notions of
+repository, changeset, commit, clone, pull, push, fork and pull request shall
+reap benefits in terms of productivity for today's young scientists in the long
+run~\cite{wilson_best_2014}.
 
-Git has become the \textit{de facto} standard for source management. However, for the
-FluidDyn project, we prefer to use Mercurial because we consider that it is
-simpler for the beginners and as powerful for the expert users. The simplicity
-for the scientists who are not expert in development is especially important
+Git has become the \textit{de facto} standard for source management. However,
+for the FluidDyn project, we prefer to use Mercurial because we consider it to
+be simpler for the beginners and just as powerful for expert users\footnote{See
+\href{https://github.com/sympy/sympy/wiki/Git-hg-rosetta-stone\#Rosetta\_Stone}{``Git
+hg rosetta stone''} on Sympy wiki.}. Simplicity and lowering the learning
+barrier for scientists who are not experts in software development is crucial
 for our project.
 %
-Note that it is now possible to use Mercurial to work with Git repositories
-hosted for example in Github and Gitlab\footnote{By using the Mercurial
+Note that, it is now possible to use Mercurial to work with Git repositories,
+for example hosted in Github and Gitlab\footnote{By using the Mercurial
 extension hg-git.}.
 
-%todo
-\subparagraph{Third-party software repositories.} Python Package Index
-(Pypi). Started with the Comprehensive Perl Archive Network (CPAN) for the
-language Perl... The Comprehensive R Archive Network (CRAN) for R is also
-important.
+\subparagraph{Third-party software repositories.} Python as a medium for
+scientific computing owes its success to a rich ecosystem of third-party
+packages.  Smooth deployment of these packages requires a package manager and a
+supported repository. A credible hub to upload source codes as compressed
+archives or as pre-compiled binary packages was therefore indispensable. The use
+of repositories started with the conception of CPAN and CRAN repositories for
+the languages Perl and R in 1993 --- based on the Comprehensive TeX Archive
+Network (CTAN) model for \TeX\ packages. 
 
-%todo
-Remark Conda...
+Today, \href{https://pypi.org}{Python Package Index (PyPI)} and
+\href{https://anaconda.org}{Anaconda Cloud} are major repositories for
+delivering and downloading Python packages, assisted by package managers
+\pack{pip} and \pack{conda} respectively.
+% Almost all major 
+% languages\footnote{\href{https://stackoverflow.com/questions/1693529/list-of-top-repositories-by-programming-language}{https://stackoverflow.com/questions/1693529/list-of-top-repositories-by-programming-language}}
+% have similar repositories, with exceptions such as Fortran and Matlab.
 
-\subparagraph{Continuous integration.} The need of strong reliability of
-programs of increasing complexity has forced the developers to use continuous
+\subparagraph{Continuous integration (CI).} The need for strong reliability of
+programs with increasing complexity has forced developers to use continuous
 integration.
 %
-A set of unit tests are run for each commit (modification of the code) to check
-that no bug have been introduced.
-%
-Unit testing and continuous integration are specifically important for
-dynamical languages and open-source code since it allows open-source projects
-to welcome participation from many people while keeping a high reliability.
+In CI, firstly the code is \emph{built} against a known, repeatable emulation
+environment on a server. Thereafter, a set of \emph{unit tests} are run for
+each commit (modification of the code) to check that no bugs have been
+introduced. It is also important to analyse what portion of the source code
+is covered by these unit tests --- a method referred to as \emph{code
+coverage}\footnote{For FluidDyn, the code coverage results are displayed at
+\href{https://codecov.io/gh/fluiddyn}{https://codecov.io/gh/fluiddyn}}. In
+FluidDyn project we stop at this level, but it is possible to further enhance
+it by adding code style checks by running linters alongside unit tests;
+and also to add \emph{continuous delivery} of documentation and package
+releases.
 
-%todo
-Remark codecov... and other similar tools for quality control.
+Almost all CI platforms are free for open-source projects --- Travis CI,
+CircleCI and Appveyor % (sic) av: I have double checked the official names
+to name a few. Bitbucket and Gitlab have built-in CI
+implementations.  Websites such as Codecov and Coveralls help to chart and
+analyse the code coverage history, viewable by anyone.
+
+When the code depends on a wide variety of external dependencies, CI is useful
+to avoid \href{https://en.wikipedia.org/wiki/Software\_rot}{software rot},
+i.e.\ to avoid becoming obsolete with newer versions of the compiler or its
+dependencies.  CI is specifically important for dynamical
+languages and open-source code since it allows open-source projects to welcome
+participation from many people while maintaining a high degree of reliability.
 
 \subparagraph{Websites to share knowledge.}  Learning programming and computer
 science is now greatly helped by web tools like the community driven
 encyclopedia \href{https://www.wikipedia.org/}{Wikipedia} or the community
-driven site \href{http://stackoverflow.com/}{Stackoverflow}, where people write
-thousands of questions and answers on programming each week.
-
-%todo For Ashwin! :-)
-IRC, Slack, Riot, 
+driven forum \href{https://stackoverflow.com/}{Stack Overflow}, where people
+write thousands of questions and answers on programming each week. IRC protocol
+has continued to sustain the test of time and channels such as
+\codeinline{\#python} on Freenode facilitate interactive discussions and a form
+of community-level support system --- a role which used to be filled by mailing
+lists alone in the past. Alternatives such as Riot (Matrix protocol), Gitter,
+and Slack have gained traction offering different integrations solutions.
 
+\subparagraph{Automatic web documentations built on servers.}
 %todo
-\subparagraph{Automatic web documentations built on servers.}
-
-Doxygen, Sphinx, Readthedocs...
-
+Doxygen, Sphinx, Read the Docs...
+%fixme:bookmark
 \subsection*{Python, a programming language adapted for open-science}
 
 The Python language has been designed to boost the communication of technical
@@ -1045,10 +1088,7 @@
 %
 The packages of the FluidDyn project are also part of this trend.
 
-
-
-
-\subsection*{FluidDyn project}
+\subsection*{FluidDyn project: Breaking the status quo}
 
 We have seen that there is a strong dynamics around the use of computers (in
 particular with the web) and that this creates very efficient tools and methods
@@ -1083,7 +1123,7 @@
 matters\footnote{\url{http://www.cecill.info/licences.en.html}}.
 \item Documentation produced with the standard and up-to-date tools: Sphinx,
 Anaconda and Jupyter. Built and hosted online at
-\href{https://readthedocs.org/}{Readthedocs}. Can also be generated offline.
+\href{https://readthedocs.org/}{Read the Docs}. Can also be generated offline.
 \item Unittest and continuous integration with Bitbucket Pipeline and Travis.
 \end{itemize}
 We hope that such clean framework will allow contributions from scientists in
@@ -1114,11 +1154,11 @@
 (\url{http://fluiddyn.readthedocs.io}) and some prominent features are
 presented in the following of this paper.
 
-\item fluidfft \cite[see the companion paper][]{fluidfft}: a library which
+\item fluidfft~\cite[see the companion paper][]{fluidfft}: a library which
 provides C++ and Python classes useful to perform Fast Fourier Transform (FFT)
 in sequential and in parallel.
 
-\item fluidsim \cite[see the companion paper][]{fluidsim}: Numerically oriented
+\item fluidsim~\cite[see the companion paper][]{fluidsim}: Numerically oriented
 framework to run sequential and parallel Computational Fluid Dynamics (CFD)
 simulations and on-the-fly post-processing for a variety of problems
 (Navier-Stokes, Shallow Water, F\"oppl von K\'arm\'an equations, to name a
@@ -1440,7 +1480,7 @@
 On our side, we have also positive points.
 %
 The quality of the tools we use (Python and its scientific ecosystem,
-Mercurial, Readthedocs, Jupyter, ...) is impressive.
+Mercurial, Read the Docs, Jupyter, ...) is impressive.
 %
 Scientific code is done to be read and to transmit ideas. Technically, Python
 is among the best languages for this point of view.
diff --git a/fluiddyn/notes.md b/fluiddyn/notes.md
--- a/fluiddyn/notes.md
+++ b/fluiddyn/notes.md
@@ -77,10 +77,6 @@
 - av: By choosing mercurial, we hope to lower the barrier for a newcomer to
   actively participate in our project.
 
-- av: Mention package hosting platforms: PyPI and Anaconda?
-
-  pa: Yes, but where? Maybe rather in "Websites"?
-
 - av: Since the code depends on a wide variety of external dependencies, CI is
   useful to avoid software-decay
   https://en.wikipedia.org/wiki/Software_rot. That is when the code becomes
diff --git a/fluidsim/Makefile b/fluidsim/Makefile
--- a/fluidsim/Makefile
+++ b/fluidsim/Makefile
@@ -21,8 +21,8 @@
 	evince $(name).pdf &
 
 vimtex:
-	# gvim $(name).tex --servername GVIM &
-	gnome-terminal -- nvim $(name).tex
+	gvim $(name).tex --servername GVIM &
+	# gnome-terminal -- vim $(name).tex --servername GVIM
 
 doit: vimtex $(name).pdf
 	zathura $(name).pdf &
diff --git a/jors.cls b/jors.cls
--- a/jors.cls
+++ b/jors.cls
@@ -111,4 +111,6 @@
 
 \newcommand{\pack}[1]{\codeinline{#1}}
 
+% \newcommand{\annotate}[1]{\marginpar{\textcolor{red}{#1}}}
+
 \endinput