Package: metys
MetysMetys is scientific report generator and a literate programming tool similar to
knitr or Pweave. Like Pweave, Metys uses the Jupyter protocol to run code
embedded in the source document. Unlike Pweave, Metys can access multiple
Jupyter kernels within the same source document and can also create multiple
separate sessions of the same kernel.Metys is currently alpha level software.Processing Metys DocumentsMetys is currently run from the command line by using the following.metysfoo.tmtThere are many command line options available. A short description will be shown
with the following.metys--helpInput FormatsMetys can parse source documents in noweb, Markdown or Metys format. The format
of the source document will be determined by the file extension or by the--parsercommand line option if specified. Source documents with a file
extension ending withnware assumed to be noweb documents. Those with a file
extension ending withmdare assumed to be Markdown documents. All other files
are assumed to be in Metys format.Parsing the source document results in a series of logical chunks. These chunks
are either text, code or group chunks. Text chunks contain text which is copied
verbatim to the output document. Code chunks are evaluated by a Jupyter kernel
and the results are formatted in the output document as per the local and global
options specified. Group chunks are used to set options for a collection of
chunks or to include subfiles which contain more text, code and group chunks.noweb FormatA document in the noweb format can contain text or code chunks, but not group
chunks. Text chunks are preceded by a line containing only an@. Code chunks
are preceded by a line containing<<...>>=, where...represents a list of
key/value options. Both text and code chunks are terminated by a marker starting
a new chunk. The first chunk in a noweb document is assumed to be a text chunk.In the sample document below a Maxima kernel is asked to solve a cubic equation,
some code is sent to Python and then Maxima is asked to plot a function. Please
note that key value options that are missing a value are assumed to a chunk name.
In other words<<foo,kernel=python>>=is equivalent to<<name=foo,kernel=python>>=.Let's ask Maxima to solve a cubic equation.
<<kernel=maxima>>=
solve(x^3+x+1=0,x);
@
Next let Python say hello and have Maxima plot a hyperbolic paraboloid.
<<kernel=python>>=
print('Hello world!')
<<foo, kernel=maxima>>=
plot3d (u^2 - v^2, [u, -2, 2], [v, -3, 3], [grid, 100, 100],
  [mesh_lines_color, false], [svg_plot, "m.svg"]);
@
That's all for now.Markdown FormatSource documents in the Markdown format can contain text or code chunks, but not
group chunks. Code chunks are delimited by a pair of single back-ticks or by a
pair of triple back-ticks. This is the same delimiters that plain Markdown uses
to indicate code, the difference being that Metys expects a set of key/value
options surrounded by curly braces or a set of empty curly braces.The following sample document accomplishes the same tasks as the previous noweb
example. Unlike noweb document key value options without a value are assumed
to be a kernel name, not a chunk name.Let's ask Maxima to solve a cubic equation.

```{maxima}
solve(x^3+x+1=0,x);```Next let Python say hello and have Maxima plot a hyperbolic paraboloid.`{python} print('Hello world!')````{maxima, name=foo}plot3d (u^2 - v^2, [u, -2, 2], [v, -3, 3], [grid, 100, 100],[mesh_lines_color, false], [svg_plot, "m.svg"]);```That's all for now.Metys FormatDocuments in Metys format can contain text, code or group chunks. Like Markdown
the entire document is assumed to be in text mode, so only code and group chunks
have delimiters. Both code and group chunks are started by<|and terminated
by|>. After the opening delimiter key/value options may be specified until a
chunk separator is received. The remainder of the chunk is then either code or
group data. The chunk separators are:,|or@. The:separator is used
for code blocks, the|separator is used for inline code, and the@separator is used for group chunks. For example, the following using a group to
declare Maxima as the default kernel before making calls to a Maxima kernel and
a Python kernel.<|maxima@
Let's ask Maxima to solve a cubic equation.

<|:solve(x^3+x+1=0,x);|>

Next let Python say hello and have Maxima plot a hyperbolic paraboloid.
<|python|print('Hello world!')|>

<|name=foo:
plot3d (u^2 - v^2, [u, -2, 2], [v, -3, 3], [grid, 100, 100],
  [mesh_lines_color, false], [svg_plot, "m.svg"]);
|>
That's all for now.
|>Please note that kernels and sessions are local to the innermost enclosing
group chunk.Chunk OptionsChunk options may be specified in all input formats as a list of key/value pairs
separated by commas. Each key/value pair consists of a name followed by an
equals sign and a value. The absence of an equals sign and a value is treated as
a value to be assigned to a default key. The default key for noweb format isname. For all other formats the default key iskernel.The key name may contain any combination of letters and underscores, along with
a single period used to specify sub-options. For example, the following
specifies a Maxima kernel, with a LaTeX code environment ofVerbatimandframe=singleas a verbatim environment option.<|maxima, code_env=Verbatim, code_env_options.frame=single:
solve(x^3+x+1=0,x);
|>The table below lists the chunk options available along with a short summary of
each option.NameTypeDefaultDescriptioncode_echobooleantrueEnable echo of code input.code_envstringverbatimCode environment for LaTeX.code_env_optionsstring/sub-optionNoneCode environment options for LaTeX.evaluatebooleantrueEnable evaluation of code input.expand_optionsbooleanfalseEnable option expansion in code input.figure_captionstringNoneFigure caption.figure_envstringfigureFigure environment for LaTeX.figure_pathstringfigureFigure directory.figure_env_optionsstring/sub-optionNoneFigure environment options for LaTeX.figure_prefixstringfig:Figure label prefix for LaTeX.formatlatex,markdownNoneFormat of output file.graphics_optionsstring/sub-optionNoneGraphics options for LaTeX.inlinebooleanNoneEnable inline output format.inputstringNonePath of input file for chunk.kernelstringNoneJupyter kernel.math_envstringequationDisplay math environment for LaTeX.math_prefixstringeq:Mathematics label prefix for LaTeX.namestringNoneChunk name. Used for file names and labels.outputstringNonePath of output file for chunk.parsermarkdown,metys,nowebNoneParser to use for input file.resultsbooleantrueEnable output of code results.sessionstringNoneUnique identifier for specific kernel session.stderr_echobooleantrueEnable echo of stderr.stderr_envstringverbatimstderr environment for LaTeX.stderr_env_optionsstring/sub-optionNonestderr environment options for LaTeX.stdout_echobooleanfalseEnable echo of stdout.stdout_envstringverbatimstdout environment for LaTeX.stdout_env_optionsstring/sub-optionNonestdout environment options for LaTeX.wrap_mathbooleantrueEnabling wrapping of math results.Please not that some options are automatically deduced or may have special
behavior. For instance,Theformatoption is automatically set if not specified. Ifparseris
set tomarkdownthen theformatis also. Otherwiseformatis set tolatex.Theinlineoption is automatically set for Markdown and Metys documents, but
not for noweb documents.Theinputoption has a different behavior for text/code chunks versus group
chunks. For group chunks the chunks contents are replaced with the contents
of the file specified byinputafter it has been parsed. For text or code
chunks the contents of the file is included without any parsing.Thekerneloption is not set by default but will be set topythonfor
input files with an extension of.Pmdand set torfor input files with an
extension of.Rmd.Theoutputoption will write any chunk output to the file specified by the
option versus writing the output to main output document.Thesessionoption will allow multiple separate sessions of the same kernel
to exist. For example, the following document will have two separate Python
kernels active. In the default sessionxhas a value of 3, while in thefoosessionxhas a value of 4.Wibble <|python|x=3|>, wibble <|python,session=foo|x=4|>, quux <|python|x|>.