The JODSOURCE addon, (a part of the JOD system), contains a handy literate programming tool that enables the generation of beautiful J source code documents.
The Bible, Koran, and Bhagavad Gita of Literate Programming is Donald Knuth's masterful tome of the same name.
Knuth applied Literate Programming to his $\TeX$ systems and produced what many consider enduring masterpieces of program documentation.
jodliterate is certainly not worthy of $\TeX$
level accolades but with a little work it's possible to produce fine documents.
This J kernel notebook outlines how you can install
and use jodliterate. Jupyter notebooks are typically executed but to accommodate J
users that do hot have Jupyter this notebook is also available on GitHub
as a static PDF document.
In [1]:
NB. show J kernel version
9!:14 ''
In [2]:
NB. load JOD in a clear base locale
load 'general/jod' [ clear ''
NB. The distributed JOD profile automatically RESETME's.
NB. To safely use dictionaries with many J tasks they must
NB. be READONLY. To prevent opening the same put dictionary
NB. READWRITE comment out (dpset) and restart this notebook.
dpset 'RESETME'
NB. Converting Jupyter notebooks to LaTeX is
NB. simplified by ASCII box characters.
portchars ''
NB. Verb to show large boxed displays in
NB. the notebook without ugly wrapping.
sbx_ijod_=: ' ... ' ,"1~ 75&{."1@":
To use jodliterate you need to:
jodliterate J script.jodliterate on a JOD group with pandoc compatible document fragments.When presented with long lists of program prerequisites my impulse is to run! Life is too short
for configuration wars. Everything should be easy. Installing jodliterate requires more
work than phone apps
but compared to enterprise installations
setting up jodliterate is trivial. We'll go through it step by step.
J is freely available at jsoftware.com. J installation instructions can be found on the J Wiki on this page.
Follow the appropriate instructions for your OS.
Note: JOD runs on Windows, Linux, and MacOS versions of J, hence these are the only platforms that
currently support jodliterate.
After installing J install the J addons. J addons are installed with the J package manager pacman. Pacman has three IDE flavors: a command-line flavor and two GUI flavors. The GUI flavors depend on JQT or JHS. The GUI flavors of pacman are only available on some versions of J whereas the command line version is part of the base J install and is available on all platforms.
I install all the addons. I recommend that you do the same.
JOD depends on some J modules like jfiles, regex, and task that are
sometimes distributed as addons. If you install all addons JOD's modules
and dependents are both installed.
In [3]:
NB. install J addons with command-line pacman
load 'pacman' NB. load pacman jpkg services
In [4]:
'help' jpkg '' NB. what can you do for me?
In [5]:
NB. install all addons
NB. see https://code.jsoftware.com/wiki/Pacman
NB. uncomment next line if addons not installed
NB. 'install' jpkg '*' NB.
In [6]:
3 {. 'showinstalled' jpkg '' NB. first few installed addons
In [7]:
'showupgrade' jpkg '' NB. list addon updates
I mostly use the Windows JQT version of pacman to install and maintain J addons. You can find pacman on the tools menu.
pacman shows all available addons and provides tools for installing, updating, and removing them.
The GUI version is easy to use. Press the Select All button and then press the Install button to install
all the addons. To update addons select the Upgrades menu and select the addons you want to update.
JOD source code is distributed in the form of JOD dictionary dumps. Dictionary dumps are large J scripts that serialize JOD dictionaries. Dumps contain everything stored in dictionaries. You will find source code, binary data, test scripts, documentation, build macros, and more in typical JOD dictionaries.
jodliterate is stored as a JOD dictionary group. A dictionary group is simply a collection
of J words with optional header and post-processor scripts. JOD generates J scripts from groups.
Before we can make jodliterate we must load the JOD development dictionaries. The JODSOURCE
addon includes a J script that
loads development dictionaries.
Again, start J and do:
In [8]:
require 'general/jod'
In [9]:
NB. set a JODroot user folder
NB. if not set /jod/ is the default
NB. use paths for your OS
UserFolders_j_=: UserFolders_j_ , 'JODroot';'c:/temp'
NB. show added folder
UserFolders_j_ {~ (0 {"1 UserFolders_j_) i. <'JODroot'
In [10]:
NB. load JOD developement dictionaries
load_dev_tmp=: 3 : 0
if. +./ (;:'joddev jod utils') e. od '' do.
'dev dictionaries exist'
else.
0!:0<jpath'~addons/general/jodsource/jodsourcesetup.ijs'
end.
)
load_dev_tmp 0
In [11]:
NB. joddev, jod, utils should exist
erase 'load_dev_tmp'
(;:'joddev jod utils') e. od ''
pandoc is easily one of the most useful markup utilities on the intertubes. If you routinely deal with markup formats like markdown, XML, $\LaTeX$, json and you aren't using pandoc you are working too hard.
Be lazy! Install pandoc.
jodliterate uses the task addon to shell out to pandoc. Versions of pandoc after
2.9.1.1 support J syntax high-lighting.
In [12]:
NB. show pandoc version from J - make sure you are running
NB. a recent version of pandoc. There may be different
NB. versions in many locations on various systems.
ppath=: '"C:\Program Files\Pandoc\pandoc"'
THISPANDOC_ajodliterate_=: ppath
shell THISPANDOC_ajodliterate_,' --version'
In [13]:
NB. make sure your version of pandoc
NB. supports J syntax-highlighting
NB. appends line feed character if necessary
tlf=:] , ((10{a.)"_ = {:) }. (10{a.)"_
NB. J is on the supported languages list
pcmd=: THISPANDOC_ajodliterate_,' --list-highlight-languages'
(<;._2 tlf (shell pcmd) -. CR) e.~ <,'j'
jodliterate uses $\LaTeX$ to compile PDF documents. When setjodliterate runs
it sets an output directory and writes
a $\LaTeX$ preamble file JODLiteratePreamble.tex to it.
It's a good idea to review this file to get an idea of the $\LaTeX$ packages
jodliterate uses. It's possible that some of these packages are not in your $\LaTeX$ distribution
and will have to be installed.
To ease the burden of $\LaTeX$ package maintenance I use freely available $\TeX$ versions that automatically install missing packages.
If your system automatically installs packages the first time you
compile jodliterate output it may fetch missing packages from
The Comprehensive $\TeX$ Archive Network (CTAN).
If new packages are installed reprocess your files a few times to insure all the
required packages are downloaded and installed.
In [14]:
require 'general/jod'
NB. open dictionaries
od ;:'joddev jod utils' [ 3 od ''
In [15]:
NB. generate jodliterate
sbx mls 'jodliterate'
mls creates a standard J load script. Once generated this script can be loaded with the standard
J load utility. You can test this by restarting J without JOD and loading jodliterate.
In [16]:
NB. load generated script
load 'jodliterate'
In [17]:
require 'general/jod'
od 'utils' [ 3 od ''
In [18]:
NB. display short explanations for (sunmoon) words
sbx hlpnl }. grp 'sunmoon'
In [19]:
NB. display part of the (sunmoon) group document header
NB. this is pandoc compatible markdown - note the LaTeX
NB. commands - pandoc allows markdown/LaTeX mixtures
900 {. 2 9 disp 'sunmoon'
In [20]:
NB. run jodliterate on (sunmoon)
require 'jodliterate'
NB. set the output directory - when
NB. running in Jupyter use a subdirectory
NB. of your notebook directory.
ltxpath=: 'C:\Users\john\AnacondaProjects\testfolder\grplit\'
setjodliterate ltxpath
In [21]:
NB. (grplit) returns a list of generated
NB. LaTeX and command files. The *.bat
NB. file compiles the generated LaTeX
,. grplit 'sunmoon'
In [22]:
_250 {. shell ltxpath,'sunmoon.bat'
In [23]:
NB. uncomment to display generated PDF
NB. shell ltxpath,'sunmoon.pdf'
Effective use of jodliterate requires a melange of Markdown, $\LaTeX$, JOD, and J skills combined with a healthy
attitude about experimentation. You have to try things and see if they work!
However, before you can try jodliterate document fragments you have put them in JOD dictionaries.
jodliterate uses two types of document fragments:
Markdown group documents are transformed by pandoc into $\LaTeX$ but the overview macros are not altered in any way. This enables the use of arbitrarily complex $\LaTeX$. The following examples show how to insert document fragments.
In [24]:
NB. create a demo dictionary - (didnum) insures new name
require 'general/jod'
NB. new dictionary in default JOD directory
sbx newd itslit_ijod_=: 'aaa',":didnum_ajod_ ''
In [25]:
NB. 1 if new dictionary created
(<itslit) e. od ''
In [26]:
od itslit [ 3 od '' NB. open only new dictionary
In [27]:
NB. define some words
freq=:~. ; #/.~
movmean=:-@[ (+/ % #)\ ]
geomean=:# %: */
bmi=: 704.5"_ * ] % [: *: [
polyprod=:+//.@(*/)
wlst=: ;:'freq movmean geomean bmi polyprod'
NB. put in dictionary
put wlst
NB. short word explanations
t=: ,: 'freq';'frequency distribution'
t=: t , 'movmean';'moving mean'
t=: t , 'geomean';'geometric mean of a list'
t=: t , 'bmi';'body mass index - (x) inches (y) lbs'
t=: t , 'polyprod';'polynomial product'
0 8 put t
In [28]:
NB. make header and macro groups
grp 'litheader' ; wlst
grp 'litmacro' ; wlst
In [29]:
IFACEWORDSlitheader=: wlst
put 'IFACEWORDSlitheader'
In [30]:
NB. add group header markdown
litheader=: (0 : 0)
`litheader` is a markdown demo group.
This markdown text will be
[transmogrified](https://calvinandhobbes.fandom.com)
by `pandoc` to \LaTeX. A group interface will be
generated from the `IFACEWORDSlitheader`
list. Interface lists are usually, but
not always, associated with a *class group*.
\subsection{\texttt{litheader} Interface}
`{~{insert_interface_md_}~}`
)
NB. store markdown as a JOD group document
2 9 put 'litheader';litheader
In [31]:
NB. run jodliterate on group
ltxpath=: 'C:\Users\john\AnacondaProjects\testfolder\grplit\'
setjodliterate ltxpath
{: grplit 'litheader'
In [32]:
NB. compile latex
_250 {. shell ltxpath,'litheader.bat'
In [33]:
NB. uncomment to show PDF
NB. shell ltxpath,'litheader.pdf'
In [34]:
NB. add a LaTeX overview - this code will not
NB. be altered by jodliterate the suffix
NB. '_oview_tex' is required to associate
NB. the overview with the group 'litmacro'
litmacro_oview_tex=: (0 : 0)
This \LaTeX\ code will not be
touched by \texttt{jodliterate}.
\subsection{Business Babel}
``Truth management is enabled.''
\emph{Excerpt from an actual business document!}
Obviously composed in an irony free zone.
\subsection{Some Complicated \LaTeX}
\medskip
\[
\frac{1}{\Bigl(\sqrt{\phi \sqrt{5}}-\phi\Bigr) e^{\frac25 \pi}} =
1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}}
{1+\frac{e^{-8\pi}} {1+\ldots} } } }
\]
)
NB. store LaTeX as JOD text macro
4 put 'litmacro_oview_tex';LATEX_ajod_;litmacro_oview_tex
In [35]:
NB. run jodliterate on group
{: grplit 'litmacro'
In [36]:
NB. compile latex
_250 {. shell ltxpath,'litmacro.bat'
In [37]:
NB. display PDF
NB. shell ltxpath,'litmacro.pdf'
The main jodliterate verb grplit works with single JOD groups. Larger systems are
typically made from many groups. JOD macro and test scripts are one way to work
around this limitation. The JOD development dictionaries contain several macros that illustrate this approach.
In [38]:
od ;:'joddev jod utils' [ 3 od ''
NB. list macros with substring 'latex'
4 2 dnl 'latex'
In [39]:
NB. display start of macro that
NB. applies jodliterate to JOD code
250 {. 4 disp 'buildjodlatex'
jodliterate is an idiosyncratic anal-retentive software utility; it's mainly for
people that consider source code an art form. Nobody likes ugly undocumented art!
If you have any questions, suggestions, or complaints please leave a comment on this post. To include others join one of J discussion forums and post your queries there.
May the source be with you!