On 22/12/2012, at 11:28 AM, GitHub wrote:
>
> Log Message:
> -----------
> Tee in spipes. Tangler program.
PART1: STATUS QUO
==================
Ok so this now works: you write a file:
tut.fdoc
and you can use the tangler program to make
tut.flx
tut.expect
So you can now browse the tutorial page with the webserver
and also run the code and check it. This new tool is designed
for simple tutorial pages and documented regression tests (NEW!).
The rules for this simple version are simple: at most one
program and one expect file. The tangler does a timestamp
check before processing. The command is:
flx_tangle --indir=indir --outdir=outdir regex regex ....
where regex is an Perl (RE2) regular expression to match the
basename (i.e without the .fdoc extension). for example:
flx_tangle tut
Note Perl regex on command line usually need quoting
on bash in single quotes. Note wildcard '.*' and not *,
this is Perl not Glob. Of course '.*' matches all .fdoc files
in the indir, recursively descending the tree.
SO now we have the main problem again: how to organise
the tutorial. In particular the problem is hyperlinking:
* cross refs between docs
* index/contents
At present I have a convention, from the Makefile:
tutindex:
build/release/bin/mktutindex tut Tutorial tutorial.fdoc
build/release/bin/mktutindex fibres Fibres tutorial.fdoc
build/release/bin/mktutindex objects Objects tutorial.fdoc
build/release/bin/mktutindex polymorphism Polymorphism tutorial.fdoc
build/release/bin/mktutindex pattern Patterns tutorial.fdoc
build/release/bin/mktutindex literals Literals tutorial.fdoc
build/release/bin/mktutindex cbind "C Binding" tutorial.fdoc
build/release/bin/mktutindex streams Streams tutorial.fdoc
build/release/bin/mktutindex array "Arrays" tutorial.fdoc
build/release/bin/mktutindex garray "Generalised Arrays" tutorial.fdoc
build/release/bin/mktutindex uparse "Universal Parser" uparse.fdoc
The mktutindex tool and the webserver both follow a convention that
any fdoc file named like
stuff-99.fdoc
where 99 is 01, 02, 03 etc, is a sequence of pages of a single
tutorial set. The mktutindex program generates the index page
for such a set given the base part of the name, 'stuff'
in this case, using the topic heading given and the "home"
index page as the third argument.
The webserver automatically detects this format as well and
adds "Next" and "Prev" buttons as well as a link to the index page.
There's a tool
rentut dir base 25 35
which looks for all the files in dir of shape base-99.fdoc and renames
them so all the ones with sequence numbers starting with 25+
get renumbered to 35+. This allows inserting a new page.
This whole mechanism is a pain, but it automates the indexing.
[A GUI tool would be better, for example a wiki]
PART 2: WHERE TO GO NOW?
=========================
The whole mechanism above is really clumsy. It works, but only just!
To take advantage of the tangling stuff I have to "rewrite" the tutorial,
and rewrite or at least rewrap the regression tests.
I am thinking to change the tutorial approach.
Instead of teaching Felix the Language, take an
implementation viewpoint and show how to bind to
C code right from the start.
Any which way the super ad-hoc way the stuff is organised
and managed is a real impediment. Flx_tangle helps a bit.
There's an interesting option here: allow the "flx" tool
to process *.fdoc files. In other words just consider the fdoc
to be felix code by ignoring the docs. That way there's no
need to run flx_tangle explicitly.
You should also note that once the tangling tool is built it can
be used to generate libraries, allowing the library code to be
documented. The generated library code for the core has to be put
in the repository too (since the library is needed to build the tangler
tool .. :)
Libraries are more problematic, because visual tools (editors)
will have trouble with the format. I don't have a way to colour
the felix code inside an fdoc (it can be done but it's yet another
job). LP of this form is easy with a decent editor (folding away
the docs), but I use Vim and doing the folds is a serious
pain in the keyboard (even if the code to do it works).
For libraries the answer is to change the fdoc/flx format
to a single format with proper syntax. Something like:
publish """ ... """;
works but is too ugly to use (I tried it).
I really need some design help here.
As well as tut/test writing help :)
--
john skaller
skal...@users.sourceforge.net
http://felix-lang.org
------------------------------------------------------------------------------
LogMeIn Rescue: Anywhere, Anytime Remote support for IT. Free Trial
Remotely access PCs and mobile devices and provide instant support
Improve your efficiency, and focus on delivering more value-add services
Discover what IT Professionals Know. Rescue delivers
http://p.sf.net/sfu/logmein_12329d2d
_______________________________________________
Felix-language mailing list
Felix-language@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/felix-language
