axiom-developer
[Top][All Lists]

## Re: [Axiom-developer] Desired functionality from noweb

 From: C Y Subject: Re: [Axiom-developer] Desired functionality from noweb Date: Tue, 8 May 2007 04:38:05 -0700 (PDT)

--- Ralf Hemmecke <address@hidden> wrote:

> > I'm trying to reconcile that idea with an "Axiom Journal" style of
> > writing where people may do shorter papers on a single topic.
>
> Oh, I am fully aware of the Axiom Journal idea. And I completely
> support that. But besides the LaTeX issue, there is also the code
> issue. The Axiom Journal is basically Axiom itself (or rather the
> part that deals with Mathematics). In general there might be
> different "papers" that  extend Axiom in different an incompatible
> ways.

Hmm.  Definitely a point.

> An "official" Axiom could then be seen as a compatible selection of
> the Journal papers. Though, of course, everyone is free to build is
> own Axiom. I guess, we will soon end up with different branches.

Hopefully doing work in Axiom would be one way to keep things more
compatible, but I guess that still doesn't solve the problem of
competing research teams working on the same task.

> So the whole Journal idea needs a lot more of thought than just the
> LaTeX issue. For me the time is not yet ripe, but I am always
> thinking in the journal direction.

Agreed, but I still think it is worthwhile to bear it in mind when
thinking about the LaTeX machinery, since with luck it will eventually
be needed.

> > I am thinking about build times for Axiom.  Tim has stated that the
> > goal is to treat building documentation on an equal footing with
> > building machine binaries, so build time is impacted by
> > documentation decisions.  That's the whole reason Waldek proposed
> > and implemented the finite-state approach to tangle, and when I
> > asked the list if it was really necessary the consensus was yes.
>
> I am not building Axiom 10 times a day, but rather a (relatively
> small) library. If there is something faster available than noweb
> with the same functionality, I could probably switch easily.

Of course, there is also the option of giving people the choice - use
noweb and get more features, or cl-web and get (slightly) faster build
times.

I still think the most promising direction for the "read the source
code and find definitions and where they are used" is to use the
compiler to find that information - anything else just seems too
fragile.  sbcl has xref functionality now (since Dec. 2006 actually,
although I didn't see it at the time) and also a contrib module called
sb-introspection developed for SLIME.  These tools or extensions of
them might make for some VERY interesting possibilities.  (Of course
that would tie that functionality to sbcl...)

> >>> I tend to think of it as one pamphlet = 1 "concept", and then
> >>> pamphlets would be bundled like conference proceedings to make
> >>> larger volumes.
>
> OK. For me then a "concept" is like a collection of files (call it
> pamphlet or not). I simply want to have reasonable file sizes and
> different languages in different files.

Makes sense.

> >> If everything is put into html form on a website what
> >> disadvantage would that have?
> >
> > Compared to LaTeX+pdf html is (at the moment) not as convenient for
> > mathematical output.  Since Axiom is intended to support advanced
> > mathematical research robust mathematical typesetting/output is a
> > must.
>
> OK. But there are also ways to link different .dvi and .pdf files
> together. (That was shown by Tim.) That still means one can keep the
> projects/libraries/concepts separate documents and still interlink.

Yes.  I guess my next question is do you want to be able to have the
def feature work across multiple files?

> >> But that is only for chunks that have the same name. They are
> >> combined together in the order they apper in a .pamphlet. The rest
> >> appears as a hierarchy.
> >
> > ?  I'm a bit confused.  I thought chunk names had to be unique
> within a
> > pamphlet.
>
> Try
> %---BEGIN aaa.pamphlet
> <<*>>=
> <<X>>
> A
> @
> <<X>>=
> EFG
> @
> <<*>>=
> B
> @
> <<C>>=
> UVW
> @
> %---END aaa.pamphlet
>
> notangle aaa.pamphlet
> EFG
> A
> UVW
> B

Ugh.  I don't think this is a style of LP we should use.  My preference
in the above situation would be to throw an error that chunk "X" is
already defined.  For multiple "root" nodes in a file tangle the
requested node but print a note that chunks "foo" and "bar" in this
file are also root nodes.  I suppose a tangle with no specified root
node could untangle all root nodes but I don't really regard that as a
good way to work - at least the way I write if a chunk isn't inside a
root node it's a mistake and what I want is a message warning me, not
an unwanted file (or sometimes several of them) dumped into the source
dire

> >> I don't use language awareness in ALLPROSE. Aldor is not build-in
> >> into noweb anyway and I did not know how to write an appropriate
> >> noweb filter to add language support for Aldor, so my filters
> start
> >> before noweave sees the file. Anyway, if we start putting several
> >> different languages into one pamphlet, it will be difficult to
> guess
> >> the language if there is no explicit tag.
> >
> > Agreed - I think it would be a bad idea to have more than one
> language
> > per pamphlet.  If we must do so an explicit tag for language is
> needed.
>
> In fact, I am not 100% sure whether it is a bad idea to have several
> languages in one file. The reason is that sometimes one describes a
> target in a Makefile, for example, and that would use some perl
> script. If the perl script is only used for that target then it might
> be a good idea to place the script+documentation right next to the
> description of the make target. I simply have not enough experience
> in LP to decide  what is better. And there may be different tastes.

Oh, OK.  Now I see why you want tangle to export all root nodes by
default.  My personal preference would still be to call tangle for each
node but it would be faster and easier in that situation to just tangle
all root nodes once.  Hmm.  I guess a behavior flag is in order, plus I
need to flag root nodes.

> If the perl script is only used for that target then it might be a
> good idea to place the script+documentation right next to the
> description of the make target. I simply have not enough experience
> in LP to decide  what is better. And there may be different tastes.

Probably.  I personally prefer not to have "hidden" root nodes in files
that the pamphlet name doesn't suggest, but I can see your above case
as a reasonable exception to that.  (It's unfortunate that multiple
languages are needed but that's another post.)

> That line numbering in the .tex is *identical* to the .pamphlet file
> is needed for the inverse search feature.

OK.  I need to take a look at the inverse search feature in more
detail.

> What is the disadvantage of \begin{docchunk} ... \end{docchunk}? You
> can define it as
>
> \newenvironment{docchunk}{}{}
>
> but without any need to re-weave, you could also compile against
> another style file which has
>
> \usepackage{verbatim}
> \newenvironment{docchunk}{\comment}{\endcomment}
>
> and you would only see code in the .dvi file. (It's just an example.)

I guess my instinct was to add only what was absolutely necessary to
the TeX file for simplicity, but I guess I have to admit it wouldn't
make too much difference.  I didn't want to require any style files not
already in teTeX but I guess that's unrealistic.

> So noweave even adds chunk numbers which one can ignore in the .sty
> file.

search.

Cheers,
CY

__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around
http://mail.yahoo.com