Re: announcement: FriCAS-1.0.0 release

Rainer Joswig <joswig@xxxxxxx> wrote:
In article <fdist2$pre$1@xxxxxxxxxxxxxxxxxx>,
Waldek Hebisch <hebisch@xxxxxxxxxxxxxxxx> wrote:

FriCAS 1.0.0 has been released.


Thanks.

Question: does anybody still like/use literate programming?
Here with noweb?

Personally I find the use of noweb distracting.

Pro:

* creates nice static documentation
* unified documentation format across languages

Cons:

* creates static documentation, batch run
* all text files no longer have their native extension
* confuses the text editor (highlighting)
* makes the build more complicated
* makes the use of automated tools more complicated
* doesn't use the 'native' documentation features
of the language and its development environments

also:

* most better IDEs have some source browsing feature
* software is less often printed to paper as it used to be.
Today most developers have access to laptops or computer
with LCD screens where browsing source code fine.
* web based tools for viewing source repositories may
also have source browsers (with linking, highlighting, ...)
which also let you browse changes

Any experience from Axiom^h^h^h^h^h FriCAS?


FriCAS still uses noweb -- new stuff uses plain files but it
will take some time to unwrap old files. Currently in FriCAS
noweb performs one useful function: there are (many) files
which logically form one unit, but which are split and
compiled separately.

Concerning literate programming I would say that nobody know
how to it well. Classicaly literate programming means that
code is split into little snippets and mixed with documentation.
This encourages documenting low-level aspects of code. IMHO
most of time it is better to avoid tricks and write clear code
than to document tricks. What is needed is higher level
documantation which explains grand design -- literate programming
is of little help here.

For me literate programming simply does not work: when I read
code extra prose is of little help, but lack of structure hurts.
OTOH I prefer documentation which makes sense without looking at
code.

Let me remark that Axiom nicely illustrates things which may go
wrong with literate programming (FriCAS got rid of worst abuses):

- useless "documentation" which just repeats in English what
the code is doing
- old bitrotten code which supposedly documents how things are
done (but is wrong)
- spagetti of hunks which makes tracing control and data flow
difficult

Finally, already in IBM era Axiom had its own documentation
toolchain. This toolchain has a bunch of nice features absent
in noweb (but is different).

--
Waldek Hebisch
hebisch@xxxxxxxxxxxxxxxx
.

Relevant Pages

  • Re: Request for comments on simple Ada program
    ... What I still do put in the source code - and don't like putting there - is the abstracts for the subprograms and packages. ... But how can I easily cross-link the documentation and the code? ... The conversation seems to be drifting towards Knuth's "literate programming". ...
    (comp.lang.ada)
  • Re: fortran maintenance tools
    ... put code around every subroutine call to collect performance ... It is one thing to put the effort into improving the code if you end up with something readable, well organized, and with some confidence that the code matches the documentation, another thing all together if the code runs faster but is no easier to understand. ... Literate programming makes it easy to sprinkle comments of the sort that explain why a line of code really does implement equation 73 from that 1952 tech. report, assuming the arguments satisfy the constraints unique to the case under consideration. ...
    (comp.lang.fortran)
  • Re: Writing, Coding, and Professionals
    ... Guy Macon writes: ... Anton Ertl wrote: ... The first contrasts literate programming with 'an ... Contrasts Literate Programming with embedded documentation: ...
    (comp.lang.forth)
  • Re: Writing, Coding, and Professionals
    ... MPE uses literate programming of a sort for all our code. ... agree that specs for applications are rare these days, ... multiple documentation formats. ... than mixing top-down and bottom-up styles in the same document. ...
    (comp.lang.forth)
  • Re: literate programming in C++
    ... software in a LaTeX document, but I'm relying ... Hi, I am an happy user of NOWEB, I use it to code my TeX formats. ... I would not say that literate programming is agonizing, it is just staying away from the main stream as it ever did. ...
    (comp.text.tex)