example literate program in Forth using LyX

forth

    Sponsored Links

    Next

  • 1. Trees
    Strange, but I can't find any simple tree algorithms in Forth. The shootout has some (binary-trees), but they are very specific for that benchmark. I am looking for routines to initialize, search, insert into, print, and destroy trees. The data to be stored is a single number per node. Nothing fancy is needed, at this point speed etc. is not important yet. -marcel
  • 2. Problem compiling pfe-0.9.14
    Hello all, I am trying to compile pfe-0.9.14 on an oldish emcahines etower e366c running Crux Linux 2.2. I get several errors from core.c, all relating to: <snip> error: invalid lvalue in increment [or decrement] warning: computed value is not used </snip> for fragments like: { COMMA (*sp++) } Anyone know what gives? Many aplogies for such an enviroment/OS/C specific question. Thanx, Tarkin

example literate program in Forth using LyX

Postby Krishna Myneni » Thu, 24 Feb 2011 02:48:08 GMT

I have rewritten a decade old Forth program, to combine newly created
documentation along with existing documentation (in the form of source
comments) and the actual source code into a single LyX file. The
original program, sl.4th, is a very domain specific program. As such,
the documentation needed to understand and use the program exceeds the
actual source code, and much of it was never actually written because
there were only a few users. The new LyX file is considerably better
documented, and, I hope, should enable users with sufficient technical
knowledge to do meaningful calculations with it.  For our purpose here
in c.l.f., I want to use sl.lyx, which can now be considered the Forth
source file also, as an example for comparing the benefits/drawbacks
of literate programming with LyX to traditional ways of creating
source code and documentation.

It took considerable effort to create the LyX file, because writing
useful and comprehensive documentation is rarely easy, and requires a
lot of thought and attention to detail. However, I think it was worth
the effort. Just a few observations from me:

1) Being able to explicitly write out the equations in LyX helped me
to find a minor, decade old bug in the code, which affected the
accuracy of the calculation.

2) Ordering the source code to the logical flow of the documentation
took some getting used to --- I was fighting my natural tendency as a
Forth programmer to define things before their use. However, the
organization of the entire program is more easily understandable now,
I believe.

Other observations will come to mind, but I'm too tired to ponder them
now.

The  sl.lyx file may be found at,

ftp://ccreweb.org/software/lyx/forth/sl.lyx

For comparison, the original Forth source file may be found at,

ftp://ccreweb.org/software/kforth/examples/fsl/demo/sl.4th

The .lyx file may be loaded directly into a Forth system using the lyx-
included.fs utility at,

ftp://ccreweb.org/software/gforth/lyx-included.fs

The LyX generated pdf document, from sl.lyx, may be viewed at,

ftp://ccreweb.org/software/lyx/forth/sl.pdf

There appears to be a problem with the page layout in the pdf file.
The file is quite readable but does not seem to use the page real
estate wisely.

Krishna

Re: example literate program in Forth using LyX

Postby stephenXXX » Thu, 24 Feb 2011 03:45:49 GMT

On Tue, 22 Feb 2011 09:48:08 -0800 (PST), Krishna Myneni




We regularly find bugs when upgrading a file for DocGen.


Yes, you do need to be able to reorder the output.


In DocGen we deliberately designed the system so that only normal 
Forth comments are used to contain DocGen elements. This allows Forth
source code for *any* Forth compiler to be ugraded to DocGen. This
matters to us because we want to document code for embedded systems as
well as hosted systems. Cross compilers don't have
  lyx-included


When dealing with the TeX personality for DocGen, we quickly moved
away from raw TeX. Most of the time we use Texinfo. For packages
that need a lot of mathematical handling, you should be able to
find a suitable equation package.

Stephen

-- 
Stephen Pelc,  XXXX@XXXXX.COM 
MicroProcessor Engineering Ltd - More Real, Less Time
133 Hill Lane, Southampton SO15 5AF, England
tel: +44 (0)23 8063 1441, fax: +44 (0)23 8033 9691
web:  http://www.**--****.com/  - free VFX Forth downloads

Re: example literate program in Forth using LyX

Postby Bernd Paysan » Thu, 24 Feb 2011 21:31:54 GMT




Yes, very good example.  I'm quite astonished how good you master literate 
programming after being introduced to it just last week.  And all I had to 
do to teach you is to insist that you use the right tools the way they are 
intended.

-- 
Bernd Paysan
"If you want it done right, you have to do it yourself!"
 http://www.**--****.com/ ~paysan/

Re: example literate program in Forth using LyX

Postby Krishna Myneni » Fri, 25 Feb 2011 00:23:46 GMT

n Feb 22, 12:45m, XXXX@XXXXX.COM (Stephen Pelc) wrote:

Is DOCGEN a literate programming facility? Or is it a way of including
documentation, which may have formatting markup, in the form of
comments within a Forth source file in a sequential way? From reading
the description of DOCGEN at

http://www.complang.tuwien.ac.at/anton/euroforth/ef00/pelc00b.pdf

it wasn't obvious to me that DOCGEN had features such as being able to
associate named sections of code which may appear in any order in the
source file, be referenced by those names, and then reconstructed by
the loading facility.


Nor do they need them. lyx-included is an external utility which
assembles the Forth source (well, actually the noweb tools assemble
the source, but lyx-included provides an interface to noweb). I assume
your embedded code is developed on a regular desktop type of platform
and not on the target. The tools needed to compose the integrated
document/source file and generate the code for the target need to work
on the desktop, most of the time. Whether your target file is a Forth
source file, assembly code file, or something like an Intel hex file,
is irrelevant. The cross-compiler does not need to implement lyx-
included.

Now, LyX may not be the right tool to edit source plus documentation
for your particular needs. But, it seems to me that, whatever editing
facility you choose to use, a noweb-like literate programming tool is
far more powerful than just introducing Forth style comments in a
source file, even if complex text formatting is allowed within the
comments. It also separates the source extraction to an external
utility, and does not burden the compiler with that task, which seems
much more appealing to me.
>>>>The LyX generated pdf document, from sl.lyx, may be viewed at, >> >>>>ftp://ccreweb.org/software/lyx/forth/sl.pdf >> >>>>There appears to be a problem with the page layout in the pdf file. >>>>The file is quite readable but does not seem to use the page real >>>>estate wisely. >> >> When dealing with the TeX personality for DocGen, we quickly moved >> away from raw TeX. Most of the time we use Texinfo. For packages >> that need a lot of mathematical handling, you should be able to >> find a suitable equation package. >>

I think I've found the right tool to suit my needs, at present.
Thanks.
>> Stephen >> >> -- >> Stephen Pelc, XXXX@XXXXX.COM >> MicroProcessor Engineering Ltd - More Real, Less Time >> 133 Hill Lane, Southampton SO15 5AF, England >> tel: +44 (0)23 8063 1441, fax: +44 (0)23 8033 9691 >> web:http://www.mpeforth.com- free VFX Forth downloads


Regards,
Krishna

Re: example literate program in Forth using LyX

Postby Krishna Myneni » Fri, 25 Feb 2011 00:45:26 GMT





I'm grateful for your prompting, and for your b16 example! I think LyX
+ noweb is going to work well for some of my Forth programming needs.
I've been in a quandry for some time about how to handle documentation
for my Forth programs. If I created an OpenOffice document for use by
myself and others, it would quickly get out of sync with the actual
code. As a result, I often postponed writing the documentation
indefinitely, and just relied on comments within the source.

For this illustration, I purposely chose the sl.4th example to show
how difficult it would be to convey the documentation in a human
readable way using only text comments. Mathematical formatting is
essential to expressing precisely the program's function. Being able
to view the formatted text, while editing, is key. I think the
literate programming aspect of the composition greatly improves the
comprehensibility of the source as well. LyX itself is far better for
editing the documentation than for editing the source code. It is
certainly not a programmer's editor. But, while I appreciate features
like syntax highlighting, I find it to be of less concern for my
needs. Usually, discerning the comments from the source is the most
useful part of syntax highlighting (for me), and one of the things
that combining formatted documentation and source does is to remove
some of the need for the source level comments, particularly when the
source is broken down into small chunks surrounded by descriptive
text.

Personally, this is a big leap forward for me. Thanks, Bernd.

Krishna

Re: example literate program in Forth using LyX

Postby stephenXXX » Fri, 25 Feb 2011 02:20:01 GMT

On Wed, 23 Feb 2011 07:23:46 -0800 (PST), Krishna Myneni




DocGen is not as glitzy as a full literate programming system, but
then it doesn't claim to be one. The current state of DocGen
is in any VFX Forth manual, which is entirely produced by
DocGen from the VFX Forth source code.

What do you mean by the loading facility?


If you mean that there's a tool that extracts the Forth source before
compilation then we're going to disagree fundamentally. We tried that
route many years ago. In thrash mode, a programmer *will* edit the 
extracted source. Once that happens, you are stuffed (to use a 
technical term). We tried whatever was around a while back for a
project. It failed for us. DocGen has never failed for us, even in
thrash mode.

One major point of DocGen is that it is completely source-centric.
Everything comes from the source code.


That's precisely what's wrong with it in a production environment.
Extracting the source code is a disaster waiting to happen. Extracting
the documentation can always be re-run. That is why the C people use
Doxygen.

It's like backup. Until you have experienced the disaster, you 
won't believe that you need backup.

Stephen


-- 
Stephen Pelc,  XXXX@XXXXX.COM 
MicroProcessor Engineering Ltd - More Real, Less Time
133 Hill Lane, Southampton SO15 5AF, England
tel: +44 (0)23 8063 1441, fax: +44 (0)23 8033 9691
web:  http://www.**--****.com/  - free VFX Forth downloads

Re: example literate program in Forth using LyX

Postby BruceMcF » Fri, 25 Feb 2011 02:40:18 GMT





Exactly. Having the source in load order and markup within rich text
block comments that can specify whatever desired order *when
documentation is extracted* is far more secure.

If the markup within rich text comments allows the editor being used
to hop around in that sequence, that is even better.

Re: example literate program in Forth using LyX

Postby Krishna Myneni » Fri, 25 Feb 2011 06:35:20 GMT

n Feb 23, 11:20m, XXXX@XXXXX.COM (Stephen Pelc) wrote:

Well, if you're going to characterize the literate programming method
as "glitz", we probably already have a fundamental disagreement. I'm
not an expert at literate programming, having produced a total of one
program thus far. However, when Donald Knuth claims that literate
programming was the most important result of the TeX project, I've got
an open mind to explore its potential. The following quote from the
website of Norman Ramsey, the creator of noweb, seems relevant:

"Without wanting to be elitist, the thing that will prevent literate
programming from becoming a mainstream method is that it requires
thought and discipline. The mainstream is established by people who
want fast results while using roughly the same methods that everyone
else seems to be using, and literate programming is never going to
have that kind of appeal. This doesn't take away from its usefulness
as an approach."
atrick TJ McPhee



I'm not claiming that LyX or a tool such as noweb is relevant for all
environments. In this thread I've given an example of an application
which benefits from this particular toolset. I really don't know
anything about software development in an environment where the
software is the end product, although I have worked in an industry in
which software was a service.


I won't debate the underlying issues of sloppy processes vs.
restrictive tools. Every environment has its needs, and DocGen sounds
like its appropriate for your environment. That doesn't mean it is the
best tool for all situations.


Krishna

Re: example literate program in Forth using LyX

Postby Albert van der Horst » Fri, 25 Feb 2011 06:38:35 GMT

In article < XXXX@XXXXX.COM >,



I find that my assembler/disassembler needs tons of documentation
before it is useful. Maybe this is the way to go.

By the way, my glossary for ciforth is documented word by word,
in the assembler source.
It is preprocessed by m4 and sorted, into wordset then alphabetic.
It was some work to set up, but now I'm happy.
(The output is texinfo/html/ps, texinfo to info and pdf).

<SNIP>




Re: example literate program in Forth using LyX

Postby stephenXXX » Fri, 25 Feb 2011 07:25:01 GMT

On Wed, 23 Feb 2011 13:35:20 -0800 (PST), Krishna Myneni




Yes, a bad choice of wording. However, I'll sacrifice features for
security.


No disagreement. The problem is "what is literate programming?".

All the cross-referencing facilities and so on are of far less
importance than ensuring that the design is documented and that
the code is documented. This attitude comes from 15 years of using
these tools.


I'm arguing from experience that noweb and friends have a fatal
user-interface flaw - they break under pressure because programmers
will abandon the model. Under pressure, you *need* a tool that
will not break in that way.

Stephen


-- 
Stephen Pelc,  XXXX@XXXXX.COM 
MicroProcessor Engineering Ltd - More Real, Less Time
133 Hill Lane, Southampton SO15 5AF, England
tel: +44 (0)23 8063 1441, fax: +44 (0)23 8033 9691
web:  http://www.**--****.com/  - free VFX Forth downloads

Re: example literate program in Forth using LyX

Postby Krishna Myneni » Fri, 25 Feb 2011 22:11:14 GMT





Do you also believe that the "rm" command has a "fatal user-interface
problem" because it allows users to inadvertently delete files? I
can't understand how the tool is to blame for misuse by the user.

In any case, there are a couple of steps you can take for added
safety, if that's necessary due to the training/maturity of your
users:

1) use the OPEN-PIPE method in lyx-included to avoid creation of the
intermediate forth source file.

2) Explicitly remove the source file using DELETE-FILE after loading,
in lyx-included.

3) make the intermediate forth source read only.


Of course, you can make the argument that, "my programmers will just
enter all of the commands manually to generate an editable forth
source, and then edit that file instead of the actual source file."
Don't know how to help you there.

Krishna

\ From lyx-included.x
\ ...

: lyx-included ( alyx u asrc u -- )
  \ s" filename" set-macro
  \ s" lyx -e literate %filename%.lyx; notangle -R%filename%.fs
%filename%.nw"
  \ substitute

  strpck count s" .fs" strcat src_name 2!
  strpck count lyx_name 2!
  s" rm " lyx_name $@ strcat s" .nw" strcat shell drop
  s"  lyx -e literate " lyx_name $@ strcat s" .lyx" strcat shell
  abort" Unable to extract a noweb file from lyx file!"
  s"  notangle -R" src_name $@ strcat s"  " strcat
  lyx_name $@ strcat s" .nw > " strcat
  src_name $@ strcat shell
  abort" Unable to extract Forth source file!"
  src_name $@ included
  src_name $@ DELETE-FILE drop         \ <== Add this to guard against
novice programmers!
;



Re: example literate program in Forth using LyX

Postby Krishna Myneni » Fri, 25 Feb 2011 22:12:57 GMT

On Feb 22, 11:48m, Krishna Myneni < XXXX@XXXXX.COM >


....
....

The .lyx (and .pdf) files have been updated to fix minor typos and
punctuation errors.

Krishna


Re: example literate program in Forth using LyX

Postby stephenXXX » Fri, 25 Feb 2011 22:31:16 GMT

On Thu, 24 Feb 2011 05:11:14 -0800 (PST), Krishna Myneni




Commissioning embedded systems can produce extreme programming
conditions. I (and another on this group) have been debugging
equipment at 4a.m. in a barn next to a pig farm. The truck is
going to take the equipment away in a few days.

Under these conditions, we do whatever will get the code working
in the shortest possible time. We're way beyond anything that
noweb and friends will survive. Doxygen and DocGen do survive
these conditions. Doxygen and DocGen were designed with 
people in mind.

"People are part of the design. It's dangerous to forget that."

Stephen

-- 
Stephen Pelc,  XXXX@XXXXX.COM 
MicroProcessor Engineering Ltd - More Real, Less Time
133 Hill Lane, Southampton SO15 5AF, England
tel: +44 (0)23 8063 1441, fax: +44 (0)23 8033 9691
web:  http://www.**--****.com/  - free VFX Forth downloads

Re: example literate program in Forth using LyX

Postby Krishna Myneni » Fri, 25 Feb 2011 23:34:00 GMT




That's a much better argument for your preferred tools than saying
that noweb is a fatally flawed tool.

Thanks for your story. It brings back to mind a time or two of similar
examples for me. One time I was sitting on the steps of the entrance
door of a U.S. Forest Service fire mapping jet, parked at the airfield
in Albequerque, NM. I was working a laptop, debugging and patching
code in the fire mapping software. The jet had a mission in a couple
of hours to map the fires surrounding Albequerque.

Krishna

Re: example literate program in Forth using LyX

Postby Paul E. Bennett » Sat, 26 Feb 2011 03:38:12 GMT





Sadly this is forgotten by some equipment manufacturers in the food 
industry. Ended up completing the programming on a system in temperatures 
below 10C as the equipment maker shipped the machine (untested) without the 
software being complete. Long hours at low temp don't make clear thinking a 
happy bedfellow.

-- 
********************************************************************
Paul E. Bennett...............<email:// XXXX@XXXXX.COM >
Forth based HIDECS Consultancy
Mob: +44 (0)7811-639972
Tel: +44 (0)1235-510979
Going Forth Safely ..... EBA. www.electric-boat-association.org.uk..
********************************************************************


Similar Threads:

1.example literate program in Forth using LyX

I have rewritten a decade old Forth program, to combine newly created
documentation along with existing documentation (in the form of source
comments) and the actual source code into a single LyX file. The
original program, sl.4th, is a very domain specific program. As such,
the documentation needed to understand and use the program exceeds the
actual source code, and much of it was never actually written because
there were only a few users. The new LyX file is considerably better
documented, and, I hope, should enable users with sufficient technical
knowledge to do meaningful calculations with it.  For our purpose here
in c.l.f., I want to use sl.lyx, which can now be considered the Forth
source file also, as an example for comparing the benefits/drawbacks
of literate programming with LyX to traditional ways of creating
source code and documentation.

It took considerable effort to create the LyX file, because writing
useful and comprehensive documentation is rarely easy, and requires a
lot of thought and attention to detail. However, I think it was worth
the effort. Just a few observations from me:

1) Being able to explicitly write out the equations in LyX helped me
to find a minor, decade old bug in the code, which affected the
accuracy of the calculation.

2) Ordering the source code to the logical flow of the documentation
took some getting used to --- I was fighting my natural tendency as a
Forth programmer to define things before their use. However, the
organization of the entire program is more easily understandable now,
I believe.

Other observations will come to mind, but I'm too tired to ponder them
now.

The  sl.lyx file may be found at,

ftp://ccreweb.org/software/lyx/forth/sl.lyx

For comparison, the original Forth source file may be found at,

ftp://ccreweb.org/software/kforth/examples/fsl/demo/sl.4th

The .lyx file may be loaded directly into a Forth system using the lyx-
included.fs utility at,

ftp://ccreweb.org/software/gforth/lyx-included.fs

The LyX generated pdf document, from sl.lyx, may be viewed at,

ftp://ccreweb.org/software/lyx/forth/sl.pdf

There appears to be a problem with the page layout in the pdf file.
The file is quite readable but does not seem to use the page real
estate wisely.

Krishna

2.literate programming in Forth using LyX

Following up on our discussion in the thread originated by Brad about
using OpenOffice as a Forth editor/documentation system, I followed
through on Bernd Paysan's suggestion for using LyX with noweb to
provide the capability of extracting and including Forth source from a
LyX document. It works, with the restriction that there should be no
Forth source line containing a "@" by itself.

First, my version of the Forth source to enable loading a LyX file
containing a "literate" Forth program may be found at,

ftp://ccreweb.org/software/gforth/lyx-included.fs

I renamed Bernd's "literate-included" to "lyx-included" since it is
specific to a LyX document. I also did not use the macro and
substitution words, being more comfortable with my dynamic strings
package (strings.fs). The file is gforth specific, but hopefully we
can generalize it to most Forth-94 compliant systems. The above file
also includes instructions, from my notes, on configuring LyX to be
used for literate programming in Forth. The instructions are specific
to Linux.

Second, I tested "lyx-included" with a LyX document I generated, to
both illustrate literate programming (as I crudely understand it, at
present), and to provide actual Forth code examples which will be
loaded and run by "lyx-included". My sample LyX document may be found
at,

ftp://ccreweb.org/software/lyx/forth/lpforth.lyx

One may treat the .lyx file as Forth source when loaded with "lyx-
included". However, the .lyx file contains documentation and
structures the code differently than would be done in an ordinary
Forth source file.

Krishna


3.Literate Programming Tools in Forth?

Has anyone written a literate programming tool in Forth?  Or for Forth?

I'm looking for something to use for a Forth project.  I have used noweb
in the past, as I like the simplicity of its notation.  But this time I
would really like at least basic prettyprinting of the source (emphasize
definition names, control-flow structures, that sort of thing).  I know
that is possible with noweb, but I have never been able to follow its
implementation well enough to write it myself.

So I was thinking about writing a tool, but it seems simple enough that
someone might have already done it.  I really just want flexible order
of elaboration and some sort of typesetting (HTML or LaTeX, preferably
both).  Some brief web searching and grepping through the 20+
implementations I currently have in my src/forth/systems directory
didn't turn up anything (except Peter Knaggs' paper "Literate
Programming in Forth").  So I thought I'd ask here.

--Josh

4.Question about using emacs Muse as literate programming environment

Okay, so a little background.

I'm working on my PhD and I'm finding that while I code, I tend to write 
out a lot of the meat of my papers while coding and experimenting. 
Usually, I use a separate window, but lately, I've been finding that I 
write little code and a lot of text (explaining, referencing, and 
testing brand new algorithms tends to do this to one).  So I got into 
literate programming.

Of course I use Emacs/Slime as my programming environment, but I 
discovered "muse" the other day, and it does most of what I need without 
me having to fly 13 hours to Sri Lanka to tap rubber trees by hand (I 
place writing LaTeX at about the same hassle level as going through 
airport security and flying overnight to some distant country, and if 
you missed the obtuse joke, ah well).

The only thing I now wonder is:

Has anyone written macros to do this already in elisp?  All I think 
needs to be done is to write a short elisp file that has one function to 
take a Lisp source, strip the semicolon from beginning-of-line comments, 
and either wrap <code> tags around the lisp source or drops it depending 
on the value of a parameter, then writes it to another buffer or a file.

I know there are caveats that would make it more general, for example 
maybe avoiding the assumption that all beginning of line comments are 
meant for the text (perhaps only two-semicolon beginning of line 
comments, or a semicolon-dash on the first and last lines of a 
document-destined comment).  Are there any other things I should keep in 
mind?  Does anyone else think this is a good idea?

I'm thinking the function will be

muse-publish-lisp-source

I don't suppose there's any real practical way to hybrid-ize the major 
editing modes so my muse font-lock bindings hold inside the comments?

-- Jeff

5.Error compiling example program with gfortran using lapack95 on win32

Dear NG,

for quite some time I'm trying to compile one of the example programs 
from lapack95 (la_gesv_example.f90 to be precise) with gfortran on 
Windows XP. I have successfully compiled BLAS, LAPACK and LAPACK95 with 
gfortran before, so the needed libraries are there. For simplicity, I 
copied the four mod files (f77_lapack.mod, f95_lapack.mod, la_auxmod.mod 
and la_precision.mod) and la_gesv_example.f90 in a new directory and 
created a subdirectory "lib" where I placed the *.a files. If I try to 
compile the example, the following error is thrown:

----
H:\Test\>d:\Programme\gfortran\bin\gfortran.exe -I./ la_gesv_example.f90 
-o gesv.exe lib\lapack95.a lib\tmglib.a lib\lapack.a lib\libblas.a
la_gesv_example.f90:42.27:

       CALL LA_GESV(  A, B )
                           1
Error: There is no specific subroutine for the generic 'la_gesv' at (1)
la_gesv_example.f90:49.46:

       CALL LA_GESV(  AA, BB(:,1), IPIV, INFO )
                                              1
Error: There is no specific subroutine for the generic 'la_gesv' at (1)
----

As far as I understand, this means that the interface is present but not 
the corresponding subroutine (that is part of LAPACK). So what's wrong 
with this?

Thank you for your help,

  Harald Breitkreutz

-- 
Forschungsneutronenquelle Heinz Maier-Leibnitz (FRM II)
Technische Universit Mchen
Lichtenbergstr. 1, D-85747 Garching

Phone: +49 (0)89 289-14758
Fax: +49 (0)89 289-14911
Mail:  XXXX@XXXXX.COM 

6. example program using binder1st and binder2nd needed

7. Literate programming (was: Uninitialized variables)

8. ANN: Literate Programming Tool



Return to forth

 

Who is online

Users browsing this forum: No registered users and 89 guest