Re: [Axiom-developer] Pamphlet files and Axiom

[C Y]

--- Stephen Wilson <address@hidden> wrote:

> C Y <address@hidden> writes:
> > And you think such events would be sufficiently common to merit
> > going away from them as tags for references?
> 
> Absolutely.  If I design a piece of software I consider its
> `philosophy', the why of its approach to the problem.

OK.  I was thinking solely about the Axiom codebase, but that is
probably too narrow a scope.

> I want a tool which can be tailored to axioms needs.  But at the same
> time, I do not want to say that you can only write spad, boot, and
> lisp code with this tool.

Fair enough.

> C and C++ are sufficiently popular for them to be considered when
> writing a program which manipulates source code.

Especially since we are likely to be using libraries written in those
languages for some time...

> OK.  My tool gives significance to @< currently in documentation,
> which introduces a chunk reference.

OK.

> > I'm curious when you plan to refer to code chunks in documentation.
> > Thus far most of the references I've made are from chunk to chunk. 
> 
> Really?  I always cite other code when describing a function which
> supports or uses it.

Hmm.  OK.  I look forward to seeing your new example - it should be
quite educational!
 
> > >    @<The \texttt{WEAVE} command@>= ....
> > 
> > Erm.  That didn't occur to me.  I always viewed simple non-LaTeX
> > chunk names as sufficient.
> 
> For me it is not sufficient.

I guess I can see that.  In a collection chunk, would you then do:

@<collectingterms@>=
   @<The \texttt{TANGLE} command@>
   @<The \texttt{WEAVE} command@>
etc...
@

That would be very interesting.
 
> > In cl-web, they both come out literally as they went in.  Isn't
> > that desired behavior?
> 
> latex the file and look at the dvi.

I did.  Maybe I have something set up oddly here.  Oh, well - no
matter.
 

> > So you want LaTeX typset comments inside the source code chunks? 
> 
> Sure, why not?  Sometimes the explanation of an algorithm falls
> naturally in that context.  We could number each line in a source
> code context automatically, but I dont like that approach
> exclusively. 

So, we could (for example) have the latex mode use the tangle line
information to append each line with its line number per the tangled
file output?  That would be sweet...

> Its a pain to always say "at line 34 we ....".  Its also a drag to
> have to ensure that line 34 isnt typeset as line 33 or somesuch. 
> Little creeping errors like that bug me, and I can avoid them
> completely by placing simple explanations in comments (and I would
> like to have TeXs math available to make the comments even more
> concise).

How would such comments be tangled?
 

> I will do it.  Just because you wont doesnt mean its not possible or
> desirable.

Of course.  My concern was that the complexity of learning how to write
pamphlets will be increased by using a tool that is so general,
resulting in driving away authors.  However, that's probably wrong upon
reflection - it's not any harder than anything else needed for Axiom.

> We need tools which are accommodating to needs different
> to our own.

That actually brings up a point - how much of a uniform writing style
policy do we want to enforce in Axiom?

Cheers, and thanks for all your hard work on this!

CY


       
____________________________________________________________________________________
Yahoo! oneSearch: Finally, mobile search 
that gives answers, not web links. 
http://mobile.yahoo.com/mobileweb/onesearch?refer=1ONXIC