News for hackers. Stuff that matters.
Re:Literate Programming: Empower Your Writing with Emacs Org... by jpfr on Sunday July 08, 2018 @02:23PM (#17485277)
Jupyter notebooks seem to be the modern form for literate programming.

People are writing entire books in the literate style:

http://nbviewer.jupyter.org/github/rlabbe/Kalman-and-Bayesia...

The style is similar to literate classics like "Structure and Interpretation of Computer Programs" and "Structure and Interpretation of Classical Mechanics".

The only downside is version control. Jupyter uses a custom file format. It is difficult to work with colleagues on the same notebook, since we cannot use the usual code-versioning tools (git/diff/etc.) to manually merge together concurrent changes.

Anybody knows a good solution for this?

Re:Literate Programming: Empower Your Writing with Emacs Org... by sasvari on Sunday July 08, 2018 @03:09PM (#17485526)
You can use a filter in your gitconfig to strip away the outputs, and thus make it play nicer with git [0].

gitconfig:

  [filter "nbstrip_full"]
      clean = "jq --indent 1 \
              '(.cells[] | select(has(\"outputs\")) | .outputs) = []  \
              | (.cells[] | select(has(\"execution_count\")) | .execution_count) = null  \
              | .metadata = {\"language_info\": {\"name\": \"python\", \"pygments_lexer\": \"ipython3\"}} \
              | .cells[].metadata = {} \
              '"
      smudge = cat
      required = true

gitattributes:

  *.ipynb filter=nbstrip_full

[0] http://timstaley.co.uk/posts/making-git-and-jupyter-notebook...
Re:Literate Programming: Empower Your Writing with Emacs Org... by make3 on Sunday July 08, 2018 @02:35PM (#17485344)
> Jupyter uses a custom file format

For those curious, the ipynb files are json files, and the code is stored in an array of cells, as string entries

Re:Literate Programming: Empower Your Writing with Emacs Org... by avodonosov on Sunday July 08, 2018 @03:20PM (#17485597)
README files on higher level (modules, subsystems), comments on the level of individual files.
Re:Literate Programming: Empower Your Writing with Emacs Org... by yug_blop on Tuesday July 17, 2018 @08:21AM (#17549157)
Re:Literate Programming: Empower Your Writing with Emacs Org... by cup-of-tea on Monday July 09, 2018 @03:14AM (#17488482)
> Anybody knows a good solution for this?

It's right here where you're commenting: org-mode.