Package: pnw
Latest version seeBitbucket.pnw is a text processing tool with a wide range of applications. It can
be used to compile chunks of text from various sources into a new text
file. The advantage over cut-and-paste techniques is that changes in the
source file are automatically followed. Secondly, we provide a thin
wrapper around the pandoc document converter. Therefore, chunks of text
can be converted from and to a wide range of lightweight markup
languages as well as html and tex/latex. Although literate programming
has become a little out of fashion, pnw can be used as a literate
programming tool, too. Not surprisingly, pnw itself and its
documentation is written using pnw. pnw is remotely inspired by noweb
and heavily inspired by (even borrowing part of the syntax from)antiweb. An important
feature of pnw, which is not present in antiweb, is the support of
namespaces. This allows to create reusableblock librarieswhich can
be imported and addressed in adot-notation syntaxsimilar to python
modules.A pnw file is a text file with tags defining named blocks of text. In a
way this is similar to an xml file. Tags may be hidden behind comment
characters, such that the file remains processable by another program.
The blocks of text from various pnw files can be processed and rendered
by another pnw file.DocumentationThe documentation is written inlatex. To compile the
pdfpnw-doc.pdfrun:make docfrom the command line. You can also find pnw on the
python package index. There pnw-doc.pdf is provided. I don’t
put it under version control because it will unnecessarily
inflate the repo.ExampleAssuming that pnw is installed, from the main directory of the pnw
package open an interactive python session, I recommend to useipython, and writeimport pnw
pnw.pnwimport('pnw.pnw','')Now you can explore the pnw document tree of thepnw.pnwsource file
by inspecting the dictionarypnw.chunksTo see the structure of a block, just print its reprpnw.chunks['moduledoc']To render it, tryprint pnw.chunks['moduledoc'].render(indent=0,depth=2,toformat='rst')The pnw source consists of one filepnw.pnw. It is a working python
file containing pnw tags hidden behind the#comment character. To
produce a clean python file we invoke (compare the makefile in the main
directory)python ./pnw.pnw  -F pnw.pnw > pnw.pyThe-Fdirective means that the whole file is treated as one block
namedu''. The previous command is used when installing pnw for the
first time.The main driver file for the documentation ispnw-doc.pnwin thedocdirectory. Here is the head of this file#@chunk(main,format=latex)
#@path(../..)
#@path(..)
#@import(latex-blocks.tex)
#@import(md-blocks)
#@import(pnw.pnw)
#@include(ltxheader)First the whole file is declared to be a block namedmainwhich islatexformatted. Then we add the first two parent directories to the
search path for imports. Then the fileslatex-blocks.tex,md-blocks,pnw.pnware included into the main namespaceu''.
The blockltxheader, which contains what its name says, and which
can be found inlatex-blocks.texis included.pnw-doc.pnwcontains a little of the documentation written inlatex. Mostly, it includes blocks from other files. The bulk of the
documentation, written inmarkdown, can be found inmd-blocks.Finally, an executablelatexfile is produced by invokingpnw -Rmain pnw-doc.pnw > pnw-doc.texpnw is onBitbucketand onPyPi.