howard/lit-prog-book
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

Bug fix in the rendering code along with minor formatting

Browse source 
Keep in mind that Hyperlinks, while good looking in Org, HTML and
other formats, are displayed inline in Info files, so we may want to
consider ways to have them look good in both.
This commit is contained in:
Howard Abrams 2024-08-03 10:16:07 -07:00
parent be71d9f49a
commit 5de9135575
2 changed files with 16 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
README.org
View file

@ -16,12 +16,12 @@ A question on /interactive-ness/. Since the goal is to teach LP through Emacs (a
To render and read [[file:lp-in-org.org][the book]] in Info, execute the following: To render and read [[file:lp-in-org.org][the book]] in Info, execute the following:
#+begin_src emacs-lisp #+begin_src emacs-lisp :results silent
(progn (progn
(ignore-errors
(kill-buffer "lp-in-org.info"))
(find-file "lp-in-org.org") (find-file "lp-in-org.org")
(find-file (org-texinfo-export-to-info )) (find-file (org-texinfo-export-to-info))
(Info-mode) (Info-mode)
(Info-top-node)) (Info-top-node))
#+end_src #+end_src
#+RESULTS:

18
lp-in-org.org
View file

@ -44,7 +44,7 @@ We assume the reader of this book to be fairly proficient with [[info:Emacs][Ema
As you probably know, Org is large, and the features for writing, evaluating and connecting blocks of source code in a document are extensive, and documenting them all is a daunting task. This book attempts to both guide and inspire a programmer to enjoy coding in a /iterate way/. As you probably know, Org is large, and the features for writing, evaluating and connecting blocks of source code in a document are extensive, and documenting them all is a daunting task. This book attempts to both guide and inspire a programmer to enjoy coding in a /iterate way/.
** Background ** Background
Literate Programming was first invented by Donald Knuth in 1980’s in an attempt to emphasize communication to other members on your team. He [[http://www.brainyquote.com/quotes/authors/d/donald_knuth.html#0RwBBIoWjqiKPb2Y.99][once wrote]]: Literate Programming was first invented by Donald Knuth in the 1980’s in an attempt to emphasize communication to other members on your team. He [[http://www.literateprogramming.com][once wrote]]:
#+begin_quote #+begin_quote
I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming." I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature. Hence, my title: "Literate Programming."
@ -65,7 +65,7 @@ A pre-processing program would then write the code blocks out into a source code
What happened to his concept and why don’t we program this way? What happened to his concept and why don’t we program this way?
After introducing the concept in a white paper, he expanded the idea by publishing an example of how the source code would be written in [[http://en.wikipedia.org/wiki/Jon_Bentley][Jon Bentley]]’s “Programming Pearls” column [Communications of the ACM 29, 5 (May 1986), 364-3691]. After introducing the concept in a white paper, he expanded the idea by publishing an example of how the source code would be written in [[http://en.wikipedia.org/wiki/Jon_Bentley][Jon Bentley]]’s “Programming Pearls” column [Communications of the ACM 29, 5 (May 1986), 364-3691].
[[http://en.wikipedia.org/wiki/Douglas_McIlroy][Doug McIlroy]] added a /rebuttal/ where he boiled Knuth’s example into a single (now famous) shell command: [[http://en.wikipedia.org/wiki/Douglas_McIlroy][Doug McIlroy]] added a rebuttal where he boiled Knuth’s example into a single (now famous) shell command:
#+begin_src bash #+begin_src bash
tr -cs A-Za-z '\n' | tr -cs A-Za-z '\n' |
@ -85,16 +85,22 @@ A wise engineering solution would produce—or better, exploit—reusable parts.
His example proved his point. His example proved his point.
While the resulting source code /tangled/ from a literate programming document, may look the same as a source file coded directly, this idea did not significantly change our industry While the resulting source code /tangled/ from a literate programming document, may look the same as a source file coded directly, this idea did not significantly change our industry
However, given a complex problem without the necessary components, perhaps composing your initial solution in a literate program is helpful? However, given a complex problem without the necessary components, perhaps composing your initial solution in a literate program can be helpful?
Perhaps this process was a bit too much writing for most engineers, who view code comments as unnecessary, oversized baggage that needs to be maintained. Perhaps this process was a bit too much writing for most engineers, who view code comments as unnecessary, over-sized baggage requiring maintenance.
Java's [[http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html][Javadoc]], [[http://www.stack.nl/~dimitri/doxygen/][Doxygen]], [[http://jashkenas.github.com/docco/][Docco]] and other similar projects that can extract an API from the comments of the source code could be viewed as a /step/ toward literate programming. [[https://wiki.haskell.org/Literate_programming][Haskell]] has a partial implementation built into the compiler so that it doesn't require a special comment syntax or an external macro system.
Some projects like:
- [[http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html][Javadoc]] for Java
- [[https://www.sphinx-doc.org][Sphinx]] for Python
- [[http://www.stack.nl/~dimitri/doxygen/][Doxygen]] for C and other languages
Can extract an API from the comments of the source code could be viewed as a /step/ toward literate programming. [[https://wiki.haskell.org/Literate_programming][Haskell]] has a partial implementation built into the compiler so that it doesn't require a special comment syntax or an external macro system.
What most of these systems lack is that the code, not the logic, drives the presentation order. For instance, many languages require imports, variable definitions and functions to be declared before they are used. Knuth's original "WEB" program allowed a code block to refer (include) another code block in no particular order... you could describe your code in any order that made the most sense. What most of these systems lack is that the code, not the logic, drives the presentation order. For instance, many languages require imports, variable definitions and functions to be declared before they are used. Knuth's original "WEB" program allowed a code block to refer (include) another code block in no particular order... you could describe your code in any order that made the most sense.
Knuth's original /literate programming/ approach was text with minimal editor support, as he only wrote the WEB program to create (/weave)/ the documentation and write (/tangle)/ the source code. Knuth's original /literate programming/ approach was text with minimal editor support, as he only wrote the WEB program to create (/weave)/ the documentation and write (/tangle)/ the source code.
From my perspective, literate programming can only be useful with help from an editor, for instance the [[http://ipython.org/notebook.html][iPython's notebook]] (now expanded as the [[https://jupyter.org/][Jupyter Project]]) is quite popular. However, unlike iPython's storage of the files in JSON format, I think a literate file should be readable text, as [[http://transcriptvids.com/v/oJTwQvgfgMM.html][Carsten Dominik]], the creator of Org, wrote: From my perspective, literate programming can only be useful with help from an editor, for example, many scientists use [[http://ipython.org/notebook.html][iPython's notebook]], now expanded as the [[https://jupyter.org/][Jupyter Project]]. However, unlike iPython's storage of the files in JSON format, I think a literate file should be readable text, as [[http://transcriptvids.com/v/oJTwQvgfgMM.html][Carsten Dominik]], the creator of Org, wrote:
#+begin_quote #+begin_quote
“In the third millennium, does it still make sense to work with text files? Text files are the only truly portable format for files. The data will never get lost.” “In the third millennium, does it still make sense to work with text files? Text files are the only truly portable format for files. The data will never get lost.”