Source documentation

[Pippijn van Steenhoven]

Hi,

as far as I can tell from the grammar in the Aldor User Guide, Doc(E) is
never used in Curly(E) which is ultimately the Goal. The only place I see
it used is in Piled(E). Is this an omission or am I missing anything
here?

A related question: is piling important? Should its support be high
priority? (Especially to you, Ralf.)

--
Pippijn van Steenhoven


_______________________________________________
Aldor-l mailing list
Aldor-l@...
http://aldor.org/mailman/listinfo/aldor-l_aldor.org

[David Casperson]

Hi Pippijn,

this is just from memory, but you can change from curly to piled any time
that you encounter a

#pile

and that the two goals can nest in relatively arbitrary ways.

Speaking solely from the point of view of someone writing tools, the piled
text is a pain to parse.

David
--
David Casperson, Assistant Professor         |  casper@...
Department of Computer Science               |  (250)   960-6672 Fax [phone]
College of Science and Management            |  3333 University Way
University of Northern British Columbia      |  Prince George, BC   V2N 4Z9

Hi,

as far as I can tell from the grammar in the Aldor User Guide, Doc(E) is
never used in Curly(E) which is ultimately the Goal. The only place I see
it used is in Piled(E). Is this an omission or am I missing anything
here?

A related question: is piling important? Should its support be high
priority? (Especially to you, Ralf.)

--
Pippijn van Steenhoven


_______________________________________________
Aldor-l mailing list
Aldor-l@...
http://aldor.org/mailman/listinfo/aldor-l_aldor.org

_______________________________________________
Aldor-l mailing list
Aldor-l@...
http://aldor.org/mailman/listinfo/aldor-l_aldor.org

[Pippijn van Steenhoven]

Also related but previously forgotten: where can doc comments be and what
are the semantics of these comments? Are they attached to the expression,
such that:

  Foo (I : Integer) : Integer == {
      +++ This doc comment is attached to the following expression
      I := I + 1;
      ++ This doc comment is attached to the above expression
      +++ This doc comment is attached to I * I
      I * I
      ++ I * I is multiplying a number by itself (interesting, isn't it?)
  }

What use is a doc comment? How can one use them? More importantly: what
do we _want_ them to do?

--
Pippijn van Steenhoven


_______________________________________________
Aldor-l mailing list
Aldor-l@...
http://aldor.org/mailman/listinfo/aldor-l_aldor.org

[Pippijn van Steenhoven]

> as far as I can tell from the grammar in the Aldor User Guide, Doc(E) is
> never used in Curly(E) which is ultimately the Goal. The only place I see
> it used is in Piled(E). Is this an omission or am I missing anything
> here?

Actually, I missed it. CurlyContentB has it.

> A related question: is piling important? Should its support be high
> priority? (Especially to you, Ralf.)

This question remains. I am ignoring it for now.

--
Pippijn van Steenhoven


_______________________________________________
Aldor-l mailing list
Aldor-l@...
http://aldor.org/mailman/listinfo/aldor-l_aldor.org

[Ralf Hemmecke]

On 04/25/2009 01:20 AM, David Casperson wrote:

> Hi Pippijn,
>
> this is just from memory, but you can change from curly to piled any
>  time that you encounter a
>
> #pile
>
> and that the two goals can nest in relatively arbitrary ways.
>
> Speaking solely from the point of view of someone writing tools, the
>  piled text is a pain to parse.

Well, the Python people should have some experience with program layout
using something equivalent to #pile. So there must be a way to be able
to work nicely with #pile mode. ;-)

> ------------------------------------------------------------------------
>  A related question: is piling important? Should its support be high
> priority? (Especially to you, Ralf.)

For me, #pile is definitely not important.

I have a dislike for pile mode because of code like the following from
the Axiom library...

1:UnivariatePuiseuxSeriesWithExponentialSingularity(R,FE,var,cen):_
2:  Exports == Implementation where
3:  R   : Join(OrderedSet,RetractableTo Integer,_
4:             LinearlyExplicitRingOver Integer,GcdDomain)

The indentation of line 2 is completely irrelevant because of the _ in
line 1. The same applies for line 2. But as far as I remember, there was
a rule that Axiom would automatically continue a line when a closing
parenthesis is missing. So the _ on line 3 would be unnnecessary.
(See page 888 of (Tim's version) of the Axiom book or
http://www.axiom-developer.org/axiom-website/hyperdoc/axbook/section-10.2.xhtml)

Does someone (unfamiliar with SPAD) really understand the following?
-----
The definition of drawRibbons consists of a pile of expressions to be
executed one after another. Each expression of the pile is indented at
the same level. Lines 4-7 designate one single expression: since lines
5-7 are indented with respect to the others, these lines are treated as
a continuation of line 4. Also since lines 5 and 7 have the same
indentation level, these lines designate a pile within the outer pile.
-----

How much do you like the following from
http://www.axiom-developer.org/axiom-website/hyperdoc/axbook/section-5.2.xhtml

---BEGIN

Blocks can be used in the arguments to functions.  (Here  h is
assigned  2.1+3.5.)

h := 2.1 +
    1.0
    3.5

---END

And how much do you like the next thing?

---BEGIN
Here the second argument to eval is  x=z, where the value of z is
computed in the first line of the block starting on the second
line.

eval(x**2 - x*y**2,
      z := %pi/2.0 - exp(4.1)
      x = z
    )

The interesting part is also the closing parenthesis. Could I write it
in column 1? Or column 6, so that it alligns with "x=z"?

Ralf













_______________________________________________
Aldor-l mailing list
Aldor-l@...
http://aldor.org/mailman/listinfo/aldor-l_aldor.org

[Ralf Hemmecke]

On 04/25/2009 01:41 AM, Pippijn van Steenhoven wrote:
 >> as far as I can tell from the grammar in the Aldor User Guide, Doc(E)
 >> is never used in Curly(E) which is ultimately the Goal. The only
 >> place I see it used is in Piled(E). Is this an omission or am I
 >> missing anything here?

 > Actually, I missed it. CurlyContentB has it.

OK, but why is CurlyContentB introduced at all? It's the same as 'Doc'.

If I read tne grammar well then

+++ a
   +++ b
     +++ c
   +++ d
  foo(...): ... ==

makes 'a b c d' the PreDoc of 'foo'. Indentation does not matter,
neither in piled nor in non-piled mode.

 > Also related but previously forgotten: where can doc comments be
 > and what are the semantics of these comments? Are they attached to
 > the expression, such that:
 >
 >   Foo (I : Integer) : Integer == {
 >       +++ This doc comment is attached to the following expression
 >       I := I + 1;
 >       ++ This doc comment is attached to the above expression
 >       +++ This doc comment is attached to I * I
 >       I * I
 >       ++ I * I is multiplying a number by itself (interesting, isn't
 >       ++ it?)
 >   }
 >
 > What use is a doc comment? How can one use them? More importantly:
 > what do we _want_ them to do?

Most importantly, pre and postdoc are used like

---BEGIN
+++ PreDoc for MyCat
MyCat: Category == with {
    foo: % -> ()
      ++ PostDoc for foo
}
---END

And there they could be attached to MyCat and foo, respectively with the
obvious meaning of documenting these identifiers. The current compiler
stores these Docs in the .ao files, but there is no program that
actually uses them.

Yannis Chicha once started with an AldorDoc program which would extract
these docs and produce something like Axiom's HyperDoc. But that program
was never in a usable state.

I have, however, no idea, how one could reasonably use Pre and PostDocs
for the expressions you have documented above. That would be a question
to the designers of Aldor.


_______________________________________________
Aldor-l mailing list
Aldor-l@...
http://aldor.org/mailman/listinfo/aldor-l_aldor.org