Design Spec: LP tool
====================
Felix currently sports a simple LP format, namely fdoc.
Within limits this allows code to contain HTML headings and
formatted commentary, and one additional feature: the ability
to test the code.
The Felix compiler can compile and run restricted fdoc files directly.
The flx tool allows checking for expected output. A tool called
flx_tangle can extract a single program file and expected output
from an fdoc, which combined with flx allows one to write
simple tutorial pages for which the examples can be verified.
However the mechanism supports at most one program and one
expect file, gleaned using flx_tangle by concatenating the contents
of @felix and @expect constructs respectively.
By comparison my old LP software interscript could do anything.
Interscript commands were arbitrary Python. Special builtin
commands allowed tangling multiple files of any kind from
a document, including shell scripts to do stuff with them.
Currently I want to test tutorials on separate compilation but
this requires writing multiple files which flx_tangle can't
handle. The webserver can include external files, but not
cope with multiple embedded files.
The original concept of interscript was a filename.pak file
that represented a discrete package: sources for a library,
header files, unit tests, documentation, scripts to
build and install it.
One of the core problems with LP is that IDE's and editors don't
support syntax highlighting very well. In theory Vim can handle
embedded code but in practice I'd hate to write the highlighting
scripts required!
So perhaps one of the core requirements is support for
invertible transforms: unpack (tangle) the code, edit
the resulting files, and repack (untangle).
The issue is that I, as a tutorial writer, or as a library
author, really want to write a single document. I don't want
to write multiple files and "imagine" the web page resulting from
inclusion.
However even for the simple tutorial format there are significant
obstacles. It's a bit hard to read and it forces many tricks
when one tutorial page expands on a previous one: we have to clutter
the code with "include" directives.
I know no good answer.
A simple answer is this:
@tangle filename.flx
...
@tangle filename.expect
...
@tangle weirdo.ccc as C++
...
@tangle makeit.sh
...
@exec build filename.flx
...
This is basically a cut down version of interscript.
@tangle says to emit a file with the given name AND display
it with the type suggested by the extension or forced by the "as"
keyword to be a particular type. The display for each type would be
handled by a dynamically loaded plugin in the webserver.
The @exec actually runs something. For example if you say
flx_tangle --run=build filename.fdoc
then it tangles out the code files, then executes @exec scripts
marked "build". This would compile the package. Another script
might install it. The script would be written in Felix, C++,
or bash, or anything for which flx_tangle can load a run plugin.
With some hackery .. flx_tangle can be merged into flx.
Comments appreciated. Searching for some way to automate
verification of tutorial correctness, document libraries
and programs, install packages, etc etc .. all with the one
system.
--
john skaller
skal...@users.sourceforge.net
http://felix-lang.org
------------------------------------------------------------------------------
Rapidly troubleshoot problems before they affect your business. Most IT
organizations don't have a clear picture of how application performance
affects their revenue. With AppDynamics, you get 100% visibility into your
Java,.NET, & PHP application. Start your 15-day FREE TRIAL of AppDynamics Pro!
http://pubads.g.doubleclick.net/gampad/clk?id=84349831&iu=/4140/ostg.clktrk
_______________________________________________
Felix-language mailing list
Felix-language@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/felix-language
