qmckl/src/README.org

* QMCkl source code

** Introduction

   The main objective of present library is documentation. Therefore,
   literate programming is particularly adapted in this context.
   Source files are written in org-mode format, to provide useful
   comments and LaTex formulas close to the code. There exists multiple
   possibilities to convert org-mode files into different formats such as
   HTML or pdf.
   For a tutorial on literate programming with org-mode, follow
   [[http://www.howardism.org/Technical/Emacs/literate-programming-tutorial.html][this link]].

   The code is extracted from the org files using Emacs as a command-line
   tool in the =Makefile=, and then the produced files are compiled.

   If the name of the file is =xxx.org=, the name of the produced C
   files should be =xxx.c= and =xxx.h= and the name of the produced
   Fortran files should be =xxx.f90=

*** Source code editing

    Any text editor can be used to edit org-mode files. For a better
    user experience Emacs is recommended.
    For users hating Emacs, it is good to know that Emacs can behave
    like Vim when switched into ``Evil'' mode. There also exists
    [[https://www.spacemacs.org][Spacemacs]] which helps the transition for Vim users.

    For users with a preference for Jupyter notebooks, the following
    script can convert jupyter notebooks to org-mode files:

    #+BEGIN_SRC sh tangle: nb_to_org.sh
#!/bin/bash
# $ nb_to_org.sh notebook.ipynb
# produces the org-mode file notebook.org

set -e

nb=$(basename $1 .ipynb)
jupyter nbconvert --to markdown ${nb}.ipynb --output ${nb}.md
pandoc ${nb}.md -o ${nb}.org
rm ${nb}.md
    #+END_SRC

    And pandoc can convert multiple markdown formats into org-mode.

*** Writing in Fortran

    The Fortran source files should provide a C interface using
    iso-c-binding. The name of the Fortran source files should end
    with =_f.f90= to be properly handled by the Makefile.

** Documentation

- [[qmckl_context.org][Context]]