Recent changes
50 views
Skip to first unread message
Waldek Hebisch
May 15, 2014, 11:23:10 PM5/15/14
to fricas...@googlegroups.com
FriCAS no longer uses noweb. .spad.pamphelt files are
remaned to .spad. We have now a little sed script
called 'unpack_file' which splits source files into
pieces correspondig to single constructor. Note that
this is fresh code, so some breakage is expected. In
particular I would appreciate reports about build
from svn on various OS-es.
Concerining structure of sources, currently there is a
requrement to have ')abbrev' lines at the start of
constructor, that is ')abbrev' must be the very first thing,
anything before it will be cut off by the 'unpack_file' script.
'unpack_file' takes part form ')abbrev' up to '@' or next
')abbrev'. The '@' ending constructor must be the only
character in the line. Lines between ')abbrev' and
end of piece are copied without change, there is no
reordering etc. so they must be valid Spad.
My plan is to make sure that .spad files are correct Spad,
that is it should be possible to compile them without splitting
using Spad compiler. I am not sure how long we will split
files during build -- spliting has some advantages, OTOH
building directly from source file looks more natural.
Note that what I wrote above means that currently there
are no reordering of source code inside single constructor.
In cases where pamphlet had some real "literate" part I tried
to preserve it. I turned small one-two line intrusions into
Spad commens. Longer passages are inside conditional
sections like
)if false
Some text trying to explain what is going on,
possibly hawing several lines
)endif
Let me add that I use 'false' however currently condtional
can use any identifier. If that indentifer was not
"asserted", then conditional is treated as false, otherwise
as true. To "assert" an identifier on can use ')asset'
command, for exaple ')assert Linux' will cause Linux to
be treated as true in subseqent conditionals. There
are to builtin assertions: 'CommonLisp' and 'AIX' (we probably
should drop 'AIX' as it makes no sense). If somebody
wants to put "literate" sections in the future it would
be good to choose unique indentifier for them, for
example 'FriCASdoc'.
Also, note that reordering feature of noweb frequently can be
replaced by Spad macros. I did not use macros because my
impresion was that people using noweb featurs did not like Spad
macros. However functionality offerd by them is very
similar... Spad macros normaly have "define before use"
restriction, but this can be circumvented by using 'where'.
Concerning furthere changes: if file have no real "literate"
content I plan to remove noweb markup and TeX boilerplate.
In other cases I will probably wrap boilerplate parts into
conditional sections, so that Spad compiler will skip over
them.
--
Waldek Hebisch
heb...@math.uni.wroc.pl
remaned to .spad. We have now a little sed script
called 'unpack_file' which splits source files into
pieces correspondig to single constructor. Note that
this is fresh code, so some breakage is expected. In
particular I would appreciate reports about build
from svn on various OS-es.
Concerining structure of sources, currently there is a
requrement to have ')abbrev' lines at the start of
constructor, that is ')abbrev' must be the very first thing,
anything before it will be cut off by the 'unpack_file' script.
'unpack_file' takes part form ')abbrev' up to '@' or next
')abbrev'. The '@' ending constructor must be the only
character in the line. Lines between ')abbrev' and
end of piece are copied without change, there is no
reordering etc. so they must be valid Spad.
My plan is to make sure that .spad files are correct Spad,
that is it should be possible to compile them without splitting
using Spad compiler. I am not sure how long we will split
files during build -- spliting has some advantages, OTOH
building directly from source file looks more natural.
Note that what I wrote above means that currently there
are no reordering of source code inside single constructor.
In cases where pamphlet had some real "literate" part I tried
to preserve it. I turned small one-two line intrusions into
Spad commens. Longer passages are inside conditional
sections like
)if false
Some text trying to explain what is going on,
possibly hawing several lines
)endif
Let me add that I use 'false' however currently condtional
can use any identifier. If that indentifer was not
"asserted", then conditional is treated as false, otherwise
as true. To "assert" an identifier on can use ')asset'
command, for exaple ')assert Linux' will cause Linux to
be treated as true in subseqent conditionals. There
are to builtin assertions: 'CommonLisp' and 'AIX' (we probably
should drop 'AIX' as it makes no sense). If somebody
wants to put "literate" sections in the future it would
be good to choose unique indentifier for them, for
example 'FriCASdoc'.
Also, note that reordering feature of noweb frequently can be
replaced by Spad macros. I did not use macros because my
impresion was that people using noweb featurs did not like Spad
macros. However functionality offerd by them is very
similar... Spad macros normaly have "define before use"
restriction, but this can be circumvented by using 'where'.
Concerning furthere changes: if file have no real "literate"
content I plan to remove noweb markup and TeX boilerplate.
In other cases I will probably wrap boilerplate parts into
conditional sections, so that Spad compiler will skip over
them.
--
Waldek Hebisch
heb...@math.uni.wroc.pl
Martin Baker
May 16, 2014, 2:16:32 AM5/16/14
to fricas...@googlegroups.com
On 16/05/14 04:23, Waldek Hebisch wrote:
> Concerning furthere changes: if file have no real "literate"
> content I plan to remove noweb markup and TeX boilerplate.
> In other cases I will probably wrap boilerplate parts into
> conditional sections, so that Spad compiler will skip over
> them.
Waldek,
> Concerning furthere changes: if file have no real "literate"
> content I plan to remove noweb markup and TeX boilerplate.
> In other cases I will probably wrap boilerplate parts into
> conditional sections, so that Spad compiler will skip over
> them.
Do you see a distinction between this literate content and other
documentation? That is do you see a distinction between 'programmer
documentation' and 'user documentation'? In an email conversion with Tim
he argued against this distinction and I agree with him on this
particular issue. (I hope I'm not misrepresenting Tims views since I am
disagreeing about the mechanics of LP).
So I would argue that this literate content should be brought into the
same form as the other documentation (you know my views on that).
What I would really like to see is some keyword in the ++ comments that
points out to a separate file containing this, more freely structured,
documentation. The point of that is code, like Ralfs can display the
meta information from the ++ comments but also have a button to link to
this much more detailed stuff.
Just an idea.
Martin
Martin Baker
May 16, 2014, 2:28:12 AM5/16/14
to fricas...@googlegroups.com
oops I said 'email conversion' and I meant 'email conversation'
Ralf Hemmecke
May 16, 2014, 5:19:19 AM5/16/14
to fricas...@googlegroups.com
On 05/16/2014 05:23 AM, Waldek Hebisch wrote:
Your mail is now here
http://axiom-wiki.newsynthesis.org/SpadFileConvention
so that it doesn't get lost in the mailing archive.
Maybe we also have to watch for "noweb" on the wiki and replace it with
a link to the above site.
> I would appreciate reports about build
> from svn on various OS-es.
I had no problem in building on Ubuntu 14.04.
> Concerining structure of sources, currently there is a
> requrement to have ')abbrev' lines at the start of
> constructor, that is ')abbrev' must be the very first thing,
> anything before it will be cut off by the 'unpack_file' script.
> 'unpack_file' takes part form ')abbrev' up to '@' or next
> ')abbrev'. The '@' ending constructor must be the only
> character in the line. Lines between ')abbrev' and
> end of piece are copied without change, there is no
> reordering etc. so they must be valid Spad.
Maybe I can find a trick that turns ')if FriCASdoc' and the very next
')endif' into latex commands so that one could simply create
\documentclass{article}
\usepackage{fricasdoc}
\begin{document}
\include{foo.spad}
\end{document}
and latex that directly, i.e. turning ')endif' into something like
'\begin{lstlisting}' and ')if FriCASdoc' into '\end{lstlisting}'.
OK, maybe a little sed script would be easier.
The only difference now is that without noweb, we don't have reordering
of chunks. Which I reget a bit, but since most files were pure spad
anyway, the changes are probably minimal anyway.
> My plan is to make sure that .spad files are correct Spad,
BTW, have you looked at
https://github.com/nrnrnr/noweb/blob/master/src/shell/nountangle#L8
I only had to change this line to
width=72 subst=' ' format='-- %%-%ds'
(and one should trim spaces at the end of the line)
in order to arrive at a spad file where the doc (*before* a code chunk)
is reordered together with the code chunks.
./mynountangle -R'domain XHASHTBL XHashTable' xhash.spad.pamphlet >
xhash.spad
(this is from r1760)
Unfortunately, in particular for xhash.spad it missed the section
==================================
The above numbers have been computed by the following code chunk.
<<compute possible values for the number of buckets>>=
prevTwinPrime(x) ==
p := prevPrime(x)
while p-(q := prevPrime p) > 2 repeat p := q
p
[[prevTwinPrime(2^i)::N for i in 3..40]]
@ %
==================================
which I had nowhere referenced and so nountangle simply throws it away
without warning. :-( No tool is perfect.
> that is it should be possible to compile them without splitting
> using Spad compiler. I am not sure how long we will split
> files during build -- spliting has some advantages, OTOH
> building directly from source file looks more natural.
The only issue is that browse.daase takes the )abbrev to report the
filename where the respective constructor is defined. But since the
introduction of .pamphlet that was always wrong, since it referred to
the .spad file and not the .spad.pamphlet file.
Anyway, I have no clear preference wrt to splitting. I think
constructors that logically belong together should be in one file. Their
implementation should also be together in one file.
> Let me add that I use 'false' however currently condtional
> can use any identifier.
I am more in favour of something like )if FriCASdoc.
Maybe even something like
...
)if fi
-- \begin{code}
CODE HERE
-- \end{code}
)endif
(Just a thought.)
> Also, note that reordering feature of noweb frequently can be
> replaced by Spad macros. I did not use macros because my
> impresion was that people using noweb featurs did not like Spad
> macros.
That was not the point. It simply felt unnatural to defin a SPAD macro
to do the same as noweb did. Also noweb allows to join chunks, which I
cannot do with SPAD macros. But I won't argue here. Noweb is gone and
that's OK for now.
> Concerning furthere changes: if file have no real "literate"
> content I plan to remove noweb markup and TeX boilerplate.
> In other cases I will probably wrap boilerplate parts into
> conditional sections, so that Spad compiler will skip over
> them.
I guess, such removal is simply done by using notangle. Most of the
files have no LP structure anyway.
Ralf
Your mail is now here
http://axiom-wiki.newsynthesis.org/SpadFileConvention
so that it doesn't get lost in the mailing archive.
Maybe we also have to watch for "noweb" on the wiki and replace it with
a link to the above site.
> I would appreciate reports about build
> from svn on various OS-es.
> Concerining structure of sources, currently there is a
> requrement to have ')abbrev' lines at the start of
> constructor, that is ')abbrev' must be the very first thing,
> anything before it will be cut off by the 'unpack_file' script.
> 'unpack_file' takes part form ')abbrev' up to '@' or next
> ')abbrev'. The '@' ending constructor must be the only
> character in the line. Lines between ')abbrev' and
> end of piece are copied without change, there is no
> reordering etc. so they must be valid Spad.
')endif' into latex commands so that one could simply create
\documentclass{article}
\usepackage{fricasdoc}
\begin{document}
\include{foo.spad}
\end{document}
and latex that directly, i.e. turning ')endif' into something like
'\begin{lstlisting}' and ')if FriCASdoc' into '\end{lstlisting}'.
OK, maybe a little sed script would be easier.
The only difference now is that without noweb, we don't have reordering
of chunks. Which I reget a bit, but since most files were pure spad
anyway, the changes are probably minimal anyway.
> My plan is to make sure that .spad files are correct Spad,
https://github.com/nrnrnr/noweb/blob/master/src/shell/nountangle#L8
I only had to change this line to
width=72 subst=' ' format='-- %%-%ds'
(and one should trim spaces at the end of the line)
in order to arrive at a spad file where the doc (*before* a code chunk)
is reordered together with the code chunks.
./mynountangle -R'domain XHASHTBL XHashTable' xhash.spad.pamphlet >
xhash.spad
(this is from r1760)
Unfortunately, in particular for xhash.spad it missed the section
==================================
The above numbers have been computed by the following code chunk.
<<compute possible values for the number of buckets>>=
prevTwinPrime(x) ==
p := prevPrime(x)
while p-(q := prevPrime p) > 2 repeat p := q
p
[[prevTwinPrime(2^i)::N for i in 3..40]]
@ %
==================================
which I had nowhere referenced and so nountangle simply throws it away
without warning. :-( No tool is perfect.
> that is it should be possible to compile them without splitting
> using Spad compiler. I am not sure how long we will split
> files during build -- spliting has some advantages, OTOH
> building directly from source file looks more natural.
filename where the respective constructor is defined. But since the
introduction of .pamphlet that was always wrong, since it referred to
the .spad file and not the .spad.pamphlet file.
Anyway, I have no clear preference wrt to splitting. I think
constructors that logically belong together should be in one file. Their
implementation should also be together in one file.
> Let me add that I use 'false' however currently condtional
> can use any identifier.
Maybe even something like
...
)if fi
-- \begin{code}
CODE HERE
-- \end{code}
)endif
(Just a thought.)
> Also, note that reordering feature of noweb frequently can be
> replaced by Spad macros. I did not use macros because my
> impresion was that people using noweb featurs did not like Spad
> macros.
to do the same as noweb did. Also noweb allows to join chunks, which I
cannot do with SPAD macros. But I won't argue here. Noweb is gone and
that's OK for now.
> Concerning furthere changes: if file have no real "literate"
> content I plan to remove noweb markup and TeX boilerplate.
> In other cases I will probably wrap boilerplate parts into
> conditional sections, so that Spad compiler will skip over
> them.
files have no LP structure anyway.
Ralf
Ralf Hemmecke
May 16, 2014, 5:55:24 AM5/16/14
to fricas...@googlegroups.com
> Do you see a distinction between this literate content and other
> documentation?
Not a question to me, but let bring in my opinion.
> documentation?
I think there are quite a lot of different views on a program and
different people have different needs.
If I want to drive from A to B, I am not interested in learning how to
build a car. It's enough, if I learn driving.
As for software that is:
A) User documenatation: How to use the functions?
I'd say that these are the ++ docstrings.
That usually assumes that the user is satisfied with the
input/output specification of the program.
Personal experience tells me that there should be lots of
examples that demonstrate the use of the function in some
context. I.e. comes with a short tutorial or at least
has references into a tutorial about the use of the program.
B) Tutorials for the use of the program. It's also user documentation,
but it's longer and with lots of examples.
Often that might be the ++ docstrings for the whole constructor,
but maybe one area is not covered by just one domain, but rather
several of them. Then there would be the question where to put such
documentation. Maybe putting several constructors in one file and
writing the tutorial at the top of that file would be a good
approach.
C) Maintainer documenation. That's the hard part as this involves
all the mathematics and references to the literature to enable
someone to understand the actual code. But it should include more.
Namely in addition to the maths, it must include statements about
the complexity of the function, it must include discussions of tricks
that are used inside the code, it must include documentations of
approaches that have been tried and but evaluated to be wrong paths
for an implementation of the function. There is probably more.
So I see at least 3 different kinds of documentation.
Ralf
Martin Baker
May 16, 2014, 6:49:08 AM5/16/14
to fricas...@googlegroups.com
On 16/05/14 10:55, Ralf Hemmecke wrote:
> So I see at least 3 different kinds of documentation.
Ralf,
> So I see at least 3 different kinds of documentation.
You have said you are a fan of LP but what you describe here looks to me
like a more conventional view of documentation. Are you saying that LP
would only apply to your 'C) Maintainer documentation'?
I seems to me (a view I may have got from Tim, but don't blame him if
I've got it wrong) is that a user may go backwards and forwards between
different ways of working from using FriCAS as a calculator to
maintaining/writing scripts, SPAD and system code and there are lots of
graduations in-between.
Documentation needs to support this. So you may start using FriCAS as a
calculator but then need to know how a function works, so you drill down
and get more and more details of the algorithm and eventually, if you
keep going, you are looking at the code.
I'm not sure that what is in the existing 'literate content' is purely
what you would classify as 'C) Maintainer documentation' so I still
think all documentation should be in the same place so users don't have
to guess how it is classified or look in several places.
Martin
Bill Page
May 16, 2014, 8:40:21 AM5/16/14
to fricas-devel
On 15 May 2014 23:23, Waldek Hebisch <heb...@math.uni.wroc.pl> wrote:
>
> Concerining structure of sources, currently there is a
> requrement to have ')abbrev' lines at the start of
> constructor, that is ')abbrev' must be the very first thing,
> anything before it will be cut off by the 'unpack_file' script.
> 'unpack_file' takes part form ')abbrev' up to '@' or next
> ')abbrev'. The '@' ending constructor must be the only
> character in the line. Lines between ')abbrev' and
> end of piece are copied without change, there is no
> reordering etc. so they must be valid Spad.
>
> My plan is to make sure that .spad files are correct Spad,
> that is it should be possible to compile them without splitting
> using Spad compiler. I am not sure how long we will split
> files during build -- spliting has some advantages, OTOH
> building directly from source file looks more natural.
>
I like getting rid of the pamphlet files except for the way it grouped
>
> Concerining structure of sources, currently there is a
> requrement to have ')abbrev' lines at the start of
> constructor, that is ')abbrev' must be the very first thing,
> anything before it will be cut off by the 'unpack_file' script.
> 'unpack_file' takes part form ')abbrev' up to '@' or next
> ')abbrev'. The '@' ending constructor must be the only
> character in the line. Lines between ')abbrev' and
> end of piece are copied without change, there is no
> reordering etc. so they must be valid Spad.
>
> My plan is to make sure that .spad files are correct Spad,
> that is it should be possible to compile them without splitting
> using Spad compiler. I am not sure how long we will split
> files during build -- spliting has some advantages, OTOH
> building directly from source file looks more natural.
>
certain spad files in a (more or less) logical way. Rather than one
large directory of .spad files I would like to see some useful
sub-directory structure within the src directory, e.g. with
subdirectories for each category and domains and packages grouped
within them is some logical way. Another simple way might be to make
a subdirectory for each old pamphlet file and untangle the pamphlet
file into that subdirectory.
jiazhaoconga
May 16, 2014, 8:48:47 AM5/16/14
to fricas-devel
> I would appreciate reports about build
> from svn on various OS-es.
On my gentoo, there is a (doc) build error:
> from svn on various OS-es.
....
mkdir -p tmp
gawk -f src/doc/secmenu.awk src/doc/htex/CLIF.htex 9 `sed -n '/^CLIF
/=' examples.list` tmp > tmp/CLIF.menu
gawk: src/doc/secmenu.awk:109: (FILENAME=src/doc/htex/CLIF.htex
FNR=84) fatal: can't redirect to `20/ug9.19.menu' (No such file or
directory)
Makefile:427: recipe for target 'tmp/CLIF.menu' failed
make[3]: *** [tmp/CLIF.menu] Error 2
make[3]: Leaving directory 'src/doc'
Makefile:601: recipe for target 'copy-to-target' failed
make[2]: *** [copy-to-target] Error 2
make[2]: Leaving directory 'src/doc'
Makefile:226: recipe for target 'all-doc' failed
make[1]: *** [all-doc] Error 2
make[1]: Leaving directory 'src'
Makefile:255: recipe for target 'all-src' failed
make: *** [all-src] Error 2
Ralf Hemmecke
May 16, 2014, 9:28:22 AM5/16/14
to fricas...@googlegroups.com
On 05/16/2014 02:48 PM, jiazhaoconga wrote:
> mkdir -p tmp
> gawk -f src/doc/secmenu.awk src/doc/htex/CLIF.htex 9 `sed -n '/^CLIF
> /=' examples.list` tmp > tmp/CLIF.menu
> gawk: src/doc/secmenu.awk:109: (FILENAME=src/doc/htex/CLIF.htex
> FNR=84) fatal: can't redirect to `20/ug9.19.menu' (No such file or
> directory)
That looks strange. Especially the '20/ug9.19.menu' I don't see where
> mkdir -p tmp
> gawk -f src/doc/secmenu.awk src/doc/htex/CLIF.htex 9 `sed -n '/^CLIF
> /=' examples.list` tmp > tmp/CLIF.menu
> gawk: src/doc/secmenu.awk:109: (FILENAME=src/doc/htex/CLIF.htex
> FNR=84) fatal: can't redirect to `20/ug9.19.menu' (No such file or
> directory)
that 20 comes from.
Since I usually do an out-of-source build, I may have overlooked
something for an insource build.
Can you tell me the command sequence that led to this log?
I would like to your directory structure, where you build, your
./configure call parameters and then you probably do a
cd src/doc; make ...
Right?
Ralf
Ralf Hemmecke
May 16, 2014, 9:29:52 AM5/16/14
to fricas...@googlegroups.com
On 05/16/2014 02:48 PM, jiazhaoconga wrote:
>> I would appreciate reports about build
>> from svn on various OS-es.
What's your svn revision number or git-hash?
>> from svn on various OS-es.
Ralf
Martin Baker
May 16, 2014, 11:10:05 AM5/16/14
to fricas...@googlegroups.com
On 16/05/14 13:40, Bill Page wrote:
> I like getting rid of the pamphlet files except for the way it grouped
> certain spad files in a (more or less) logical way. Rather than one
> large directory of .spad files I would like to see some useful
> sub-directory structure within the src directory, e.g. with
> subdirectories for each category and domains and packages grouped
> within them is some logical way. Another simple way might be to make
> a subdirectory for each old pamphlet file and untangle the pamphlet
> file into that subdirectory.
Why not leave it all in the same file as they are now?
> I like getting rid of the pamphlet files except for the way it grouped
> certain spad files in a (more or less) logical way. Rather than one
> large directory of .spad files I would like to see some useful
> sub-directory structure within the src directory, e.g. with
> subdirectories for each category and domains and packages grouped
> within them is some logical way. Another simple way might be to make
> a subdirectory for each old pamphlet file and untangle the pamphlet
> file into that subdirectory.
I have been using )compile with multiple category/domains/packages per
file and it seems to work OK as it is.
My preference would be to move the literate stuff to a different file
and not change )compile at all.
Martin
Bill Page
May 16, 2014, 11:33:04 AM5/16/14
to fricas-devel
The build system does/did not compile the contents of each pamphlet file in toto, rather it was first untangled into multiple spad files and these collectively were compiled in an order that was determined by dependencies. Maybe this is not so important in the way FriCAS is built now.
Also as Ralf noted, the grouping into pamphlet files long ago broke part of the AXIOM help system that was intended to point users to the appropriate SPAD source file.
--
You received this message because you are subscribed to the Google Groups "FriCAS - computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fricas-devel+unsubscribe@googlegroups.com.
To post to this group, send email to fricas...@googlegroups.com.
Visit this group at http://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.
Ralf Hemmecke
May 16, 2014, 12:46:42 PM5/16/14
to fricas...@googlegroups.com
On 05/16/2014 02:48 PM, jiazhaoconga wrote:
> mkdir -p tmp
> gawk -f src/doc/secmenu.awk src/doc/htex/CLIF.htex 9 `sed -n '/^CLIF
> /=' examples.list` tmp > tmp/CLIF.menu
> gawk: src/doc/secmenu.awk:109: (FILENAME=src/doc/htex/CLIF.htex
> FNR=84) fatal: can't redirect to `20/ug9.19.menu' (No such file or
> directory)
I've looked into the script which gives me the impression that your
> gawk -f src/doc/secmenu.awk src/doc/htex/CLIF.htex 9 `sed -n '/^CLIF
> /=' examples.list` tmp > tmp/CLIF.menu
> gawk: src/doc/secmenu.awk:109: (FILENAME=src/doc/htex/CLIF.htex
> FNR=84) fatal: can't redirect to `20/ug9.19.menu' (No such file or
> directory)
examples.list file is corrupt. Can you sent that to me and check whether
it's creation was OK? Logs?
It should start like
ALIST AssociationList
BBTREE BalancedBinaryTree
BOP BasicOperator
BINARY BinaryExpansion
BSTREE BinarySearchTree
CARD CardinalNumber
CARTEN CartesianTensor
CHAR Character
and just be the short and long name of all constructors.
Ralf
Waldek Hebisch
May 16, 2014, 8:20:50 PM5/16/14
to fricas...@googlegroups.com
Ralf Hemmecke wrote:
>
> On 05/16/2014 02:48 PM, jiazhaoconga wrote:
> > mkdir -p tmp
> > gawk -f src/doc/secmenu.awk src/doc/htex/CLIF.htex 9 `sed -n '/^CLIF
> > /=' examples.list` tmp > tmp/CLIF.menu
> > gawk: src/doc/secmenu.awk:109: (FILENAME=src/doc/htex/CLIF.htex
> > FNR=84) fatal: can't redirect to `20/ug9.19.menu' (No such file or
> > directory)
>
> I've looked into the script which gives me the impression that your
> examples.list file is corrupt. Can you sent that to me and check whether
> it's creation was OK? Logs?
>
> It should start like
>
> ALIST AssociationList
> BBTREE BalancedBinaryTree
I can reproduce the problem on Debian stable. Just build in source
>
> On 05/16/2014 02:48 PM, jiazhaoconga wrote:
> > mkdir -p tmp
> > gawk -f src/doc/secmenu.awk src/doc/htex/CLIF.htex 9 `sed -n '/^CLIF
> > /=' examples.list` tmp > tmp/CLIF.menu
> > gawk: src/doc/secmenu.awk:109: (FILENAME=src/doc/htex/CLIF.htex
> > FNR=84) fatal: can't redirect to `20/ug9.19.menu' (No such file or
> > directory)
>
> I've looked into the script which gives me the impression that your
> examples.list file is corrupt. Can you sent that to me and check whether
> it's creation was OK? Logs?
>
> It should start like
>
> ALIST AssociationList
> BBTREE BalancedBinaryTree
tree. AFAICS all positions are doubled now because *.spad pattern
catches not only unpacked files but also sources. This seem to
be the only difference. In C locale using [A-Z]*.spad leads to
correct build.
--
Waldek Hebisch
heb...@math.uni.wroc.pl
Waldek Hebisch
May 16, 2014, 9:07:05 PM5/16/14
to fricas...@googlegroups.com
spad.list:
echo $(patsubst %, %.spad, ${NSPADLIST}) > spad.list
to the algebra Makefile and use it from doc Makefile. Or maybe:
abbrev.list: $(patsubst %, %.spad, ${NSPADLIST})
sed -n 's/^)abbrev [a-z]* *\([A-Z0-9]*\) *\([^ ]*\)/\1 \2/p' \
$(patsubst %, %.spad, ${NSPADLIST}) > abbrev.list
and use the abbrev.list file from doc Makefile.
Remark: AFAICS the regex above is should be good enough and is
shorter then current in doc Makefile.
--
Waldek Hebisch
heb...@math.uni.wroc.pl
Waldek Hebisch
May 16, 2014, 9:24:32 PM5/16/14
to fricas...@googlegroups.com
Bill Page wrote:
>
> On 15 May 2014 23:23, Waldek Hebisch <heb...@math.uni.wroc.pl> wrote:
> >
> > My plan is to make sure that .spad files are correct Spad,
> > that is it should be possible to compile them without splitting
> > using Spad compiler. I am not sure how long we will split
> > files during build -- spliting has some advantages, OTOH
> > building directly from source file looks more natural.
> >
>
> I like getting rid of the pamphlet files except for the way it grouped
> certain spad files in a (more or less) logical way.
I have on intention to split source files in repository.
>
> On 15 May 2014 23:23, Waldek Hebisch <heb...@math.uni.wroc.pl> wrote:
> >
> > My plan is to make sure that .spad files are correct Spad,
> > that is it should be possible to compile them without splitting
> > using Spad compiler. I am not sure how long we will split
> > files during build -- spliting has some advantages, OTOH
> > building directly from source file looks more natural.
> >
>
> I like getting rid of the pamphlet files except for the way it grouped
> certain spad files in a (more or less) logical way.
A single .spad file can contain several constructors. Currently
we cut in into pieces during build. But once we make sure
that extra stuff is not visible to Spad compiler we can
compile the whole file. For first stage bootstrap it would
make no difference if we compile from original sources
or from split files: we handle whole algebra a single unit.
But in later stages we compile categories first. For this
we could give option to Spad compiler so that it compiles
just single constructor from the file (ATM this option is
probably broken, but we could restore it).
--
Waldek Hebisch
heb...@math.uni.wroc.pl
jiazhaoconga
May 17, 2014, 2:40:54 AM5/17/14
to fricas-devel
>I can reproduce the problem on Debian stable. Just build in source
> tree. AFAICS all positions are doubled
Yes, examples.list is doubled.
> tree. AFAICS all positions are doubled
Waldek Hebisch
May 18, 2014, 7:56:02 AM5/18/14
to fricas...@googlegroups.com
Martin Baker wrote:
>
> On 16/05/14 04:23, Waldek Hebisch wrote:
> > Concerning furthere changes: if file have no real "literate"
> > content I plan to remove noweb markup and TeX boilerplate.
> > In other cases I will probably wrap boilerplate parts into
> > conditional sections, so that Spad compiler will skip over
> > them.
>
> Waldek,
>
> Do you see a distinction between this literate content and other
> documentation? That is do you see a distinction between 'programmer
> documentation' and 'user documentation'? In an email conversion with Tim
> he argued against this distinction and I agree with him on this
> particular issue. (I hope I'm not misrepresenting Tims views since I am
> disagreeing about the mechanics of LP).
There is wide spectrum of documentation. On one axis things move
>
> On 16/05/14 04:23, Waldek Hebisch wrote:
> > Concerning furthere changes: if file have no real "literate"
> > content I plan to remove noweb markup and TeX boilerplate.
> > In other cases I will probably wrap boilerplate parts into
> > conditional sections, so that Spad compiler will skip over
> > them.
>
> Waldek,
>
> Do you see a distinction between this literate content and other
> documentation? That is do you see a distinction between 'programmer
> documentation' and 'user documentation'? In an email conversion with Tim
> he argued against this distinction and I agree with him on this
> particular issue. (I hope I'm not misrepresenting Tims views since I am
> disagreeing about the mechanics of LP).
from informal to formal. There are differences in assumed
background: some parts try to explain very basic things, while
other can not be understand without lot of knowledge. There
is interface/implementation distincion.
Concerning literate content: I wrote several times that IMHO
it is ineffective and labour intensive form of documentation.
In my ideal world there ++ docstrings more or less as they are
now (some could be better written but general direction is
fine). In implementation part there would be comments or
pointers to extra explanations in tricky places, but tricky
places would be rare, so the amount of text in implementation
part would be relatively small. There would be overview
of implementation giving general structure, representation
of data and assumption. There would be explanation of
algorithms. There would API part, more detailed than
++ docstrings. Then usage part.
Of course, in trurely ideal world documentation would
exactly answer users questions. In good, but not so
ideal world some answers are implied, so user must
actively seek answers and apply inference. And there
is big problem a search: documentation containing
answers to all likely questions would be so big
that finding answer would be hard. So we need
to split documentation into parts. Such split
is very useful for users who understand it,
other must search all anyway.
> So I would argue that this literate content should be brought into the
> same form as the other documentation (you know my views on that).
>
> What I would really like to see is some keyword in the ++ comments that
> points out to a separate file containing this, more freely structured,
> documentation. The point of that is code, like Ralfs can display the
> meta information from the ++ comments but also have a button to link to
> this much more detailed stuff.
>
> Just an idea.
consider docsting for ellipticE:
ellipticE : (F, F) -> F
++ ellipticE(z, m) is the incomplete elliptic integral of the
++ second kind: \spad{ellipticE(z, m) =
++ integrate(sqrt(1-m*t^2)/sqrt(1-t^2), t = 0..z)}
There are several notaitions for elliptic functions,
this docstring tells you which funtion it is and
elliminates all doubts about used notation. If you
need more info you need to look into a texbook
about elliptic functions. One can argue that we
really should provide such a texbook, in particuler
FriCAS capabilites allow nice expostion of some
aspect. OTOH we are now getting int texbook
business, quite far from our main field. So
we probably should outsorce this.
One extra rant: there is huge difference between reference
texts and normal books. Reference text is dull, precise,
tries to be comprehensive and usually organizes things
to make them easy to find. Normal book uses various
tricks to get didactic effect: informal explanations,
examples special order. LP folks try to make programs
into normal books, while if book analigy is appropriate
it would be reference book.
--
Waldek Hebisch
heb...@math.uni.wroc.pl
Ralf Hemmecke
May 18, 2014, 10:22:59 AM5/18/14
to fricas...@googlegroups.com
On 05/18/2014 01:56 PM, Waldek Hebisch wrote:
> There would API part, more detailed than ++ docstrings. Then usage
> part.
Oh. I think, some day we need some text that displays the conventions
> There would API part, more detailed than ++ docstrings. Then usage
> part.
for the ++ docstrings. I would claim that the API description should go
there. But maybe I don't have the same notion of API as you have.
So let me state what I would like inside the ++ docstrings:
1) input/output specification
That should be something like
++ If if x is a prime number and y is any integer then after
++ z:=foo(x,y) z is an integer in the the range 0..x-1 and
++ there is and integer k such that y=k*x+z.
The real types of x,y,z would be known from the actual type of the
function which would be shown near the ++ docstring.
2) Usage part should probably also already be in the ++ docstring.
It's often quite helpful to see how a function is used in order to
understand it. Sometimes, it's hard to grasp whether some function
does the right thing until one sees a common use case.
3) If it makes sense, the ++ docstring should include links to the
literature or related functionality
4) The docstring of the domain/category/package should give an overview
of what the constructor is about and give links to other relevant
literature.
> LP folks try to make programs into normal books, while if book
> analigy is appropriate it would be reference book.
guiding someone through the theory and illustrate that with a program
and reference documentation, one cannot easily say that one is better
than the other.
The big problem is that I haven't yet found a solution for the problem
that LP and ++ stuff both want to be close to the code. Another problem
is that one needs two types of authors.
Anyway, FriCAS has the problem of having not enough users. 5 people
cannot all LP-document the whole FriCAS code base, we first need a lot
more people that help with that effort. What value does a book have that
isn't read?
Ralf
Martin Baker
May 18, 2014, 12:30:53 PM5/18/14
to fricas...@googlegroups.com
Waldek and Ralf,
I think you are both agreeing that there is a big gap between structured
metadata in ++ and pure mathematics theory from textbooks although,
towards the end of Waldeks email, you seem to be suggesting there was
not much of a gap?
I think we are all agreed that this structured information needs to be
improved, if there were more users/developers then this could be done,
but I think users are put off by lack of information, so how to cut
through that loop?
I would suggest making any information that does exist available to the
documentation system, for instance by using a script or cut and paste to
move old LP comments to a separate file which can be linked to from the
documentation system. So what I am suggesting is make the information
available in unstructured form now, then structure it when time is
available, on the grounds that any information is better than none.
I think that the most damaging situation is where a potential new user
is looking for an implementation of some mathematics they want to do in
some specialist field. They look through all the domains, there are so
many that it is not clear which they should use, but eventually they
find one that might be what they need. They spend several days trying to
get it to work without success, perhaps they just give up and try some
other CAS or perhaps they ask here and are told that code probably does
not work "but I left it in because it does not do any harm". A simple
one line in some unstructured documentation might avoid alienating users
in this way.
I think there is a lot more, that is not pure maths theory but is
specific to the program about:
* Things that only work is certain cases or have not been fully tested.
* How well is it expected to scale to higher dimensions.
* Unusual notation
* If there is not a canonical form then why was this method chosen.
* Plus all the points Ralf made about usage stuff and so on.
Example 1
---------
The following function documentation was written by Waldek so I will
take that to be your ideal form:
kroneckerSum : (%, %) -> %
++ kroneckerSum(a, b) calculates the Kronecker sum
++ of the matrices a and b.
This has the advantage of using few words (although those words don't
tell me a lot that is not in the function signature).
Do all potential users user the term 'Kronecker sum'? When this was
discussed on this list not everyone here did. perhaps some people just
know it as a Cartesian product for matrix algebra? Perhaps people may
confuse it with 'Kronecker product'.
What happens when this is fed with non-square matrix values? Are there
any error conditions that I should look out for?
What algorithm is used? It might help to say it is something like this:
A (+) B = A (x) Im + In (x) B
Example 2
---------
What does the following do? In what circumstances would I extend my code
from it? Is this what most people would expect a category called Monad
to do?
)abbrev category MONAD Monad
++ Authors: J. Grabmeier, R. Wisbauer
++ Date Created: 01 March 1991
++ Date Last Updated: 11 June 1991
++ Basic Operations: *, ^
++ Related Constructors: SemiGroup, Monoid, MonadWithUnit
++ Also See:
++ AMS Classifications:
++ Keywords: Monad, binary operation
++ Reference:
++ N. Jacobson: Structure and Representations of Jordan Algebras
++ AMS, Providence, 1968
++ Description:
++ Monad is the class of all multiplicative monads, i.e. sets
++ with a binary operation.
Monad() : Category == SetCategory with
I think you are both agreeing that there is a big gap between structured
metadata in ++ and pure mathematics theory from textbooks although,
towards the end of Waldeks email, you seem to be suggesting there was
not much of a gap?
I think we are all agreed that this structured information needs to be
improved, if there were more users/developers then this could be done,
but I think users are put off by lack of information, so how to cut
through that loop?
I would suggest making any information that does exist available to the
documentation system, for instance by using a script or cut and paste to
move old LP comments to a separate file which can be linked to from the
documentation system. So what I am suggesting is make the information
available in unstructured form now, then structure it when time is
available, on the grounds that any information is better than none.
I think that the most damaging situation is where a potential new user
is looking for an implementation of some mathematics they want to do in
some specialist field. They look through all the domains, there are so
many that it is not clear which they should use, but eventually they
find one that might be what they need. They spend several days trying to
get it to work without success, perhaps they just give up and try some
other CAS or perhaps they ask here and are told that code probably does
not work "but I left it in because it does not do any harm". A simple
one line in some unstructured documentation might avoid alienating users
in this way.
I think there is a lot more, that is not pure maths theory but is
specific to the program about:
* Things that only work is certain cases or have not been fully tested.
* How well is it expected to scale to higher dimensions.
* Unusual notation
* If there is not a canonical form then why was this method chosen.
* Plus all the points Ralf made about usage stuff and so on.
Example 1
---------
The following function documentation was written by Waldek so I will
take that to be your ideal form:
kroneckerSum : (%, %) -> %
++ kroneckerSum(a, b) calculates the Kronecker sum
++ of the matrices a and b.
This has the advantage of using few words (although those words don't
tell me a lot that is not in the function signature).
Do all potential users user the term 'Kronecker sum'? When this was
discussed on this list not everyone here did. perhaps some people just
know it as a Cartesian product for matrix algebra? Perhaps people may
confuse it with 'Kronecker product'.
What happens when this is fed with non-square matrix values? Are there
any error conditions that I should look out for?
What algorithm is used? It might help to say it is something like this:
A (+) B = A (x) Im + In (x) B
Example 2
---------
What does the following do? In what circumstances would I extend my code
from it? Is this what most people would expect a category called Monad
to do?
)abbrev category MONAD Monad
++ Authors: J. Grabmeier, R. Wisbauer
++ Date Created: 01 March 1991
++ Date Last Updated: 11 June 1991
++ Basic Operations: *, ^
++ Related Constructors: SemiGroup, Monoid, MonadWithUnit
++ Also See:
++ AMS Classifications:
++ Keywords: Monad, binary operation
++ Reference:
++ N. Jacobson: Structure and Representations of Jordan Algebras
++ AMS, Providence, 1968
++ Description:
++ Monad is the class of all multiplicative monads, i.e. sets
++ with a binary operation.
Monad() : Category == SetCategory with
Ralf Hemmecke
May 18, 2014, 1:48:44 PM5/18/14
to fricas...@googlegroups.com
On 05/18/2014 06:30 PM, Martin Baker wrote:
> Example 1
> ---------
> The following function documentation was written by Waldek so I will
> take that to be your ideal form:
>
> kroneckerSum : (%, %) -> %
> ++ kroneckerSum(a, b) calculates the Kronecker sum
> ++ of the matrices a and b.
>
> This has the advantage of using few words (although those words don't
> tell me a lot that is not in the function signature).
That's not my ideal. It misses a clear input output specification or at
> Example 1
> ---------
> The following function documentation was written by Waldek so I will
> take that to be your ideal form:
>
> kroneckerSum : (%, %) -> %
> ++ kroneckerSum(a, b) calculates the Kronecker sum
> ++ of the matrices a and b.
>
> This has the advantage of using few words (although those words don't
> tell me a lot that is not in the function signature).
least a reference to such a definition. I agree with Martin that in
mathematics we need definitions to make clear what we are talking about.
It already starts with the question whether or not 0 is a "natural number".
And like Martin, I think it is important either to specify the input
(i.e. restrict for example to matrices of a certain shape) or document,
what the function is doing if the input makes no sense.
/: (%, %) -> %
++ a/b returns the quotient of a and b
is a really bad documentation. In general, I don't even know what a
"quotient" is. Would 1/0 be OK? Does it return 0 or abort the program?
How can someone even slightly trust a function that is not properly
specified? That's not mathematics.
Anyway, Martin, you seem to have lots of ideas and want to discuss them
in order to get confirmation that this is the "correct" direction to go.
What if you don't get that confirmation? There are two options.
1) You don't care what others say and just implement your ideas.
2) You wait some more time for someone to realise your ideas.
What I want to say is that Waldek has some ideas, I have some idea, you
have some ideas. They probably all differ in some way. Now suppose I
don't have a clear idea how I would realise what I have in mind, but you
have and start coding and come up with something fancy that improves
FriCAS (at least for you), but isn't a realisation of my idea.
If I see an improvement and cannot compete to your implementation, do
you think, I will ignore the improvement?
Yes, it's important to find out about about a consens for a direction to
go, but if you (or a small group around you) are alone, then just go,
implement and surprise the others with the result. There's a good chance
that *you* count as the expert.
Maybe my words sound a bit harsh, but I think the best way to improve
FriCAS is to take the repo and improve it in the way *you* like and then
see if others like it. It's a bit like the wiki ideas
Be bold! http://axiom-wiki.newsynthesis.org/BeBold
Ralf
Waldek Hebisch
May 18, 2014, 3:36:20 PM5/18/14
to fricas...@googlegroups.com
Martin Baker wrote:
>
> I think we are all agreed that this structured information needs to be
> improved, if there were more users/developers then this could be done,
> but I think users are put off by lack of information, so how to cut
> through that loop?
Well, IMHO documentation is just one of factor in program
>
> I think we are all agreed that this structured information needs to be
> improved, if there were more users/developers then this could be done,
> but I think users are put off by lack of information, so how to cut
> through that loop?
popularity. I would say that FriCAS is at or maybe above
free average. There are other factors, some counterintuitive.
For example, you may think that program which has less
bugs will be more sucessful. But some user judge popularity
based on number of bug reports, and assume that program
with more bug reports is more popular, hence better choice.
Also, new developers frequently get started fixing some
easy bug, so program with more bugs has better chance to
gather new developers.
Coming back to documentation, I think that we need cookbook
type recipes for various compitations. Crucial point is
that recipes should present calculations that people actually
want to do. For example, if you show how to calculate
number of lions living in given area, this will help
only if there are people who need this calculation.
--
Waldek Hebisch
heb...@math.uni.wroc.pl
Franz Lehner
May 19, 2014, 10:53:20 AM5/19/14
to fricas...@googlegroups.com
On Sun, 18 May 2014, Waldek Hebisch wrote:
> Well, IMHO documentation is just one of factor in program
> popularity.
program acceptance, second only to marketing.
Some years ago I taught "computer mathematics" to first year students,
that is MMOM = Maple, Mathematica, Octave, Maxima. At the end when asked
which of these they considered the best, all of them pointed to Maple,
because that's where it is easiest to find documentation.
When it comes to popularity, quality doesn't really count, otherwise MP3
wouldn't be so popular and random number generators wouldn't be called
"Det" [1] in "the world's ultimate application for computations" [2].
> Coming back to documentation, I think that we need cookbook
> type recipes for various compitations.
I do a lot of computations for my colleagues and in my experience a large
majority of pure mathematicians are like first year students, they do not
want to understand what is going on in the computer and just want to press
a button to obtain their result.
Thus many people start by doing simple computations with maple and then
go on to write programs despite all of its bugs and mess in the library.
It's fine with engineering kind of mathematics, but terrible when it comes
to abstract algebra.
"Instant gratification" doesn't mix well with the steep learning curve
of Axiom/FriCAS. Even for developers it takes time to appreciate the
qualities of FriCAS, and a long phase of "initiation" is needed indeed in
order to interpret the cryptic error messages of the compiler.
As for documentation, in the long term we all will be gone and should make
sure that it doesn't require a Champollion like Waldek to keep our work
alive.
just my 2c,
Franz
[1] http://arxiv.org/abs/1312.3270
[2] http://www.wolfram.com/mathematica/?source=nav
Ralf Hemmecke
May 19, 2014, 11:29:00 AM5/19/14
to fricas...@googlegroups.com
The following patch simply adds "-u" to the sort command. That would
make the lines in examples.list unique.
I'm not really happy with that solution, but it's the easiest fix.
My only question is whether non-GNU sort also accept the -u switch. For
BSD it seems to be OK.
http://www.openbsd.org/cgi-bin/man.cgi?query=sort&sektion=1
Can I commit?
Ralf
On 05/16/2014 02:48 PM, jiazhaoconga wrote:
make the lines in examples.list unique.
I'm not really happy with that solution, but it's the easiest fix.
My only question is whether non-GNU sort also accept the -u switch. For
BSD it seems to be OK.
http://www.openbsd.org/cgi-bin/man.cgi?query=sort&sektion=1
Can I commit?
Ralf
On 05/16/2014 02:48 PM, jiazhaoconga wrote:
Waldek Hebisch
May 19, 2014, 7:07:30 PM5/19/14
to fricas...@googlegroups.com
adequate. We probably should add word 'square' before
'matrices'. Today the first Google hit for "Kronecker sum"
is on Wolfram MathWorld which gives definition. The
second hit is Wikipedia article on Kronecker product, which
in section about related constructs contains definition of
Kronecker sum. So, I do not think there is real danger
of misunderstanding.
Yes, in a sense this docstring tels nothing new and in
principle we could omit it. It is there mostly to catch
cases where developers forgot to add docstring.
>
> What algorithm is used? It might help to say it is something like this:
> A (+) B = A (x) Im + In (x) B
be enoug. And it is easy to look up more information.
Adding such helpful informations we we quickly getting into
textbook business. It makes sense to have text called
"matrices with FriCAS" and there add such helpful informations.
But IMO source code is not right place for this.
> Example 2
> ---------
> What does the following do? In what circumstances would I extend my code
> from it? Is this what most people would expect a category called Monad
> to do?
>
> )abbrev category MONAD Monad
> ++ Authors: J. Grabmeier, R. Wisbauer
> ++ Date Created: 01 March 1991
> ++ Date Last Updated: 11 June 1991
> ++ Basic Operations: *, ^
> ++ Related Constructors: SemiGroup, Monoid, MonadWithUnit
> ++ Also See:
> ++ AMS Classifications:
> ++ Keywords: Monad, binary operation
> ++ Reference:
> ++ N. Jacobson: Structure and Representations of Jordan Algebras
> ++ AMS, Providence, 1968
> ++ Description:
> ++ Monad is the class of all multiplicative monads, i.e. sets
> ++ with a binary operation.
> Monad() : Category == SetCategory with
makes clear what is meant. Concerning usage: normally you
inherit from categories which best fits to your problem. If
you have single binary operation whithout specific properties,
than Monad may be good fit.
--
Waldek Hebisch
heb...@math.uni.wroc.pl
Waldek Hebisch
May 19, 2014, 9:33:14 PM5/19/14
to fricas...@googlegroups.com
Ralf Hemmecke wrote:
>
> The following patch simply adds "-u" to the sort command. That would
> make the lines in examples.list unique.
>
> I'm not really happy with that solution, but it's the easiest fix.
>
> My only question is whether non-GNU sort also accept the -u switch. For
> BSD it seems to be OK.
>
> http://www.openbsd.org/cgi-bin/man.cgi?query=sort&sektion=1
>
> Can I commit?
I would rather use accurate list of source file. I will try
>
> The following patch simply adds "-u" to the sort command. That would
> make the lines in examples.list unique.
>
> I'm not really happy with that solution, but it's the easiest fix.
>
> My only question is whether non-GNU sort also accept the -u switch. For
> BSD it seems to be OK.
>
> http://www.openbsd.org/cgi-bin/man.cgi?query=sort&sektion=1
>
> Can I commit?
to prepare a patch tomorrow.
--
Waldek Hebisch
heb...@math.uni.wroc.pl
Ralf Hemmecke
May 20, 2014, 2:19:35 AM5/20/14
to fricas...@googlegroups.com
## Generate rules to extrad SPAD type definitions from pamphlets.
echo "extracting list of SPAD type definitions"
(cd $srcdir/src/algebra;
. ../scripts/find-algebra-files) > src/algebra/tmp-extract-spad.mk
$srcdir/config/move-if-change \
src/algebra/tmp-extract-spad.mk src/algebra/extract-spad.mk
I think, the generation of examples.list should be done at this point.
Or rather it should create a MAKE variable with all SPAD files.
That would also make the lists in src/algebra/Makefile.in (SPAD_SRCS) go
away and also all the SPAD_LIST* variables. Proper handling of the
partial list for bootstrapping can be left as it is.
In fact, (since I'm somewhat an autotool fan and autotools rather want a
static list of all the files) listing the files explicitly instead of
computing that list at configure time, is somewhat safer, since it might
happen that in my source tree are some temporary .spad files that should
not be used during the compilation.
On the other hand, when adding a new constructor, I always have to
change in *two* places, namely add the constructor abbreviations to
SPAD_LIST* and the filename to SPAD_SRCS. That's not hard, but boring.
SPAD_SRCS should anyway be computed from the filenames *before* "make"
is run.
Ralf
Ralf Hemmecke
May 20, 2014, 3:33:47 AM5/20/14
to fricas...@googlegroups.com
On 05/17/2014 03:07 AM, Waldek Hebisch wrote:
> Maybe we should add something like:
>
> spad.list:
> echo $(patsubst %, %.spad, ${NSPADLIST}) > spad.list
>
> to the algebra Makefile and use it from doc Makefile.
No. No matter what you do in src/algebra/Makefile, I am not in favour of
> Maybe we should add something like:
>
> spad.list:
> echo $(patsubst %, %.spad, ${NSPADLIST}) > spad.list
>
> to the algebra Makefile and use it from doc Makefile.
using that computation for make in another directory that is on the same
level as algebra. src/doc/Makefile shouldn't know that src/algebra
exists. All it needs is where to find the .spad files and that should
come via a variable that is passed via an environment variable from
src/Makefile.
(Of course, the above is more of a philosophical statement.)
As I wrote in another mail. Computing the whole thing at configure time
would be my favourite. Or maybe, explicitly having a static list of
algebra source files in the top-level fricas source tree so that
configure and make can access it, in other words moving "SPAD_SRCS= ..."
into a toplevel file with one line per filename like so...
--begin spad.list
acplot
aggcat2
aggcat
algcat
...
ystream
zerodim
-- end spad.list
configure.ac could turn this into a .mk file
SPAD_SRCS = \
src/algebra/acplot.spad \
src/algebra/aggcat2.spad \
...
src/algebra/zerodim.spad
and a file at ${abs_top_srcdir}/abbrev.list as you describe below.
I think something like that would be even more my favourite, because it
doesn't lead to picking up .spad files that just temporarily are in my
source tree.
> abbrev.list: $(patsubst %, %.spad, ${NSPADLIST})
> sed -n 's/^)abbrev [a-z]* *\([A-Z0-9]*\) *\([^ ]*\)/\1 \2/p' \
> $(patsubst %, %.spad, ${NSPADLIST}) > abbrev.list
abbrev.list: $(patsubst %, %.spad, ${NSPADLIST})
sed -n 's/^)abbrev [a-z]* *\([A-Z0-9]*\) *\([^ ]*\)/\1 \2/p' \
> and use the abbrev.list file from doc Makefile.
> Remark: AFAICS the regex above is should be good enough and is
> shorter then current in doc Makefile.
examples.list: $(wildcard ${ALGEBRASOURCES}/*.spad)
(for a in ${EXAMPLES}; do echo "-- $$a"; done; \
sed -n 's/^)abb[a-z]* [a-z][a-z]* *\([A-Z0-9][A-Z0-9]*\) *\([^
]*\)/\1 \2/p' ${ALGEBRASOURCES}/*.spad\
) | ${AWK} '{if($$1=="--"){a[$$2]=1}else{if($$1 in a){print}}}'\
| sort -k2 > $@
is anyway too much. examples.list does not depend on *all* algebra
sources, but without knowledge of which file contains which constructor,
I have no other choice than a full dependency.
Using something like NSPADLIST would already be better and remove
duplicates.
But examples.list does not list *all* shortname/longname pairs, but only
those that I are used in the book. Anyway, if src/doc/Makefile would
have access to such a abbrev.list file, it would of course, be easier.
Well, some day "recursive make" should go away, then I could simply write
examples.list: ${patsubst %, src/algebra/%.spad, ${EXAMPLES}}
...
i.e. making sure that examples list is regenerated if one of the
respective sources is modified and not if just one randome .spad file is
touched.
Ralf
Waldek Hebisch
May 20, 2014, 6:03:35 PM5/20/14
to fricas...@googlegroups.com
I propose the patch in the attachement. Merits:
- it avoids using spurious files which just happen to
match a wildcard
- knowledge about spad sources is limited to algebra
- extra dependence between algebra and doc is limited
to a single file
--
Waldek Hebisch
heb...@math.uni.wroc.pl
- it avoids using spurious files which just happen to
match a wildcard
- knowledge about spad sources is limited to algebra
- extra dependence between algebra and doc is limited
to a single file
--
Waldek Hebisch
heb...@math.uni.wroc.pl
Waldek Hebisch
May 20, 2014, 6:16:21 PM5/20/14
to fricas...@googlegroups.com
Ralf Hemmecke wrote:
>
> On 05/17/2014 03:07 AM, Waldek Hebisch wrote:
> > Maybe we should add something like:
> >
> > spad.list:
> > echo $(patsubst %, %.spad, ${NSPADLIST}) > spad.list
> >
> > to the algebra Makefile and use it from doc Makefile.
>
> No. No matter what you do in src/algebra/Makefile, I am not in favour of
> using that computation for make in another directory that is on the same
> level as algebra. src/doc/Makefile shouldn't know that src/algebra
> exists. All it needs is where to find the .spad files and that should
> come via a variable that is passed via an environment variable from
> src/Makefile.
>
> (Of course, the above is more of a philosophical statement.)
>
> As I wrote in another mail. Computing the whole thing at configure time
> would be my favourite. Or maybe, explicitly having a static list of
> algebra source files in the top-level fricas source tree so that
> configure and make can access it, in other words moving "SPAD_SRCS= ..."
> into a toplevel file with one line per filename like so...
Logically there is dependence between doc and algebra. Putting
>
> On 05/17/2014 03:07 AM, Waldek Hebisch wrote:
> > Maybe we should add something like:
> >
> > spad.list:
> > echo $(patsubst %, %.spad, ${NSPADLIST}) > spad.list
> >
> > to the algebra Makefile and use it from doc Makefile.
>
> No. No matter what you do in src/algebra/Makefile, I am not in favour of
> using that computation for make in another directory that is on the same
> level as algebra. src/doc/Makefile shouldn't know that src/algebra
> exists. All it needs is where to find the .spad files and that should
> come via a variable that is passed via an environment variable from
> src/Makefile.
>
> (Of course, the above is more of a philosophical statement.)
>
> As I wrote in another mail. Computing the whole thing at configure time
> would be my favourite. Or maybe, explicitly having a static list of
> algebra source files in the top-level fricas source tree so that
> configure and make can access it, in other words moving "SPAD_SRCS= ..."
> into a toplevel file with one line per filename like so...
it in 'configure' needlessly leaks information to toplevel.
List of algebra files concerns algebra and should be defined
in algebra.
> > abbrev.list: $(patsubst %, %.spad, ${NSPADLIST})
> > sed -n 's/^)abbrev [a-z]* *\([A-Z0-9]*\) *\([^ ]*\)/\1 \2/p' \
> > $(patsubst %, %.spad, ${NSPADLIST}) > abbrev.list
>
> Why not use $< ?
>
> abbrev.list: $(patsubst %, %.spad, ${NSPADLIST})
> sed -n 's/^)abbrev [a-z]* *\([A-Z0-9]*\) *\([^ ]*\)/\1 \2/p' \
> $< > abbrev.list
avoid using rarely used features of GNU Make.
--
Waldek Hebisch
heb...@math.uni.wroc.pl
Ralf Hemmecke
May 20, 2014, 7:25:57 PM5/20/14
to fricas...@googlegroups.com
On 05/21/2014 12:03 AM, Waldek Hebisch wrote:
> I propose the patch in the attachement. Merits:
>
> - it avoids using spurious files which just happen to
> match a wildcard
That's good.
> I propose the patch in the attachement. Merits:
>
> - it avoids using spurious files which just happen to
> match a wildcard
> - knowledge about spad sources is limited to algebra
> - extra dependence between algebra and doc is limited
> to a single file
I strongly dislike the ../algebra part by which you refer to the
abbrev.list file.
In src/doc/Makefile I used
# We need access to the algebra source in order to generate a list of
# abbreviations (filenames and corresponding constructor name.
ALGEBRASOURCES=${fricas_src_algdir}
where I used
fricas_src_algdir = $(fricas_src_srcdir)/algebra
from config/var-def.mk.
I would rather like to add an extra variable that points to the
directory in which abbrev.list lives. For src/doc/Makefile, it shouldn't
matter where it lives, I just need a parameter. I dislike hardcoding it
via ../algebra .
So putting something like
algebra_srcdir = @top_srcdir@/src/algebra
into var-def.mk and then writing
examples.list: ${algebra_srcdir}/abbrev.list
(for a in ${EXAMPLES}; do echo "-- $$a"; done; \
cat $< \
) | ${AWK} '{if($$1=="--"){a[$$2]=1}else{if($$1 in a){print}}}'\
| sort -k2 > $@
would be better for my taste.
| sort -k2 > $@
Technically, your patch looks OK, just when I ran it inside src/algebra
to produce abbrev.list, I got a bit shocked by *one* big line like ...
sed -n 's/^)abbrev [a-z]* *\([A-Z0-9]*\) *\([^ ]*\)/\1 \2/p' \
/home/hemmecke/g/fricas-bisect/fricas/src/algebra/aggcat2.spad
/home/hemmecke/g/fricas-bisect/fricas/src/algebra/aggcat.spad
/home/hemmecke/g/fricas-bisect/fricas/src/algebra/algcat.spad
/home/hemmecke/g/fricas-bisect/fricas/src/algebra/algext.spad
/home/hemmecke/g/fricas-bisect/fricas/src/algebra/algfact.spad
... cut ...
/home/hemmecke/g/fricas-bisect/fricas/src/algebra/xpoly.spad
/home/hemmecke/g/fricas-bisect/fricas/src/algebra/ystream.spad
/home/hemmecke/g/fricas-bisect/fricas/src/algebra/zerodim.spad > abbrev.list
I immediately feared that this is going to lead to problems if my
directory name would have been even longer. Isn't there a max line
length that could eventually break the build?
Maybe VPATH would be a solution to that problem.
================
SPAD_SOURCES=$(patsubst %, %.spad, $(SPAD_SRCS))
VPATH=${srcdir}
abbrev.list: $(SPAD_SOURCES)
sed -n 's/^)abbrev [a-z]* *\([A-Z0-9]*\) *\([^ ]*\)/\1 \2/p' \
$^ > $@
================
But I'm not sure whether that works in nonGNU make.
In addition to all of that...
Maybe it would be a good idea to already sort abbrev.list alphabetically
with respect to the long name of the constructor.
Ralf
Waldek Hebisch
May 20, 2014, 8:09:27 PM5/20/14
to fricas...@googlegroups.com
Ralf Hemmecke wrote:
>
> On 05/21/2014 12:03 AM, Waldek Hebisch wrote:
> > I propose the patch in the attachement. Merits:
> >
> > - it avoids using spurious files which just happen to
> > match a wildcard
>
> That's good.
>
> > - knowledge about spad sources is limited to algebra
>
> Perhaps also good.
>
> > - extra dependence between algebra and doc is limited
> > to a single file
>
> Good, but not perfect.
>
> I strongly dislike the ../algebra part by which you refer to the
> abbrev.list file.
<snip>
>
> On 05/21/2014 12:03 AM, Waldek Hebisch wrote:
> > I propose the patch in the attachement. Merits:
> >
> > - it avoids using spurious files which just happen to
> > match a wildcard
>
> That's good.
>
> > - knowledge about spad sources is limited to algebra
>
> Perhaps also good.
>
> > - extra dependence between algebra and doc is limited
> > to a single file
>
> Good, but not perfect.
>
> I strongly dislike the ../algebra part by which you refer to the
> abbrev.list file.
> I would rather like to add an extra variable that points to the
> directory in which abbrev.list lives. For src/doc/Makefile, it shouldn't
> matter where it lives, I just need a parameter. I dislike hardcoding it
> via ../algebra .
We need to hardcode that _somewhere_. Putting definition in var-def.mk
> directory in which abbrev.list lives. For src/doc/Makefile, it shouldn't
> matter where it lives, I just need a parameter. I dislike hardcoding it
> via ../algebra .
propagates knowlege about location of algebra directory to _all_
Makefiles. Which is good if we want to use it and make sure
uses stay in sync. But the only other Makefiles which needs to
know where algebra lives is aldor and Makefile is src (which must
know about subdirectories). So putting definition in
var-def.mk spreads information to places which have no need to
know about algebra. Note that directory structure is rather
static, so usual argument for indirection (ease of modification)
has little weight. OTOH hardcoding in doc/Makefile.in minimizes
number of places which know about algebra.
> Technically, your patch looks OK, just when I ran it inside src/algebra
> to produce abbrev.list, I got a bit shocked by *one* big line like ...
>
> sed -n 's/^)abbrev [a-z]* *\([A-Z0-9]*\) *\([^ ]*\)/\1 \2/p' \
> /home/hemmecke/g/fricas-bisect/fricas/src/algebra/acplot.spad
> /home/hemmecke/g/fricas-bisect/fricas/src/algebra/aggcat2.spad
> /home/hemmecke/g/fricas-bisect/fricas/src/algebra/aggcat.spad
> /home/hemmecke/g/fricas-bisect/fricas/src/algebra/algcat.spad
> /home/hemmecke/g/fricas-bisect/fricas/src/algebra/algext.spad
> /home/hemmecke/g/fricas-bisect/fricas/src/algebra/algfact.spad
> ... cut ...
> /home/hemmecke/g/fricas-bisect/fricas/src/algebra/xpoly.spad
> /home/hemmecke/g/fricas-bisect/fricas/src/algebra/ystream.spad
> /home/hemmecke/g/fricas-bisect/fricas/src/algebra/zerodim.spad > abbrev.list
>
> I immediately feared that this is going to lead to problems if my
> directory name would have been even longer. Isn't there a max line
> length that could eventually break the build?
old ones that could be a problem.
>
> Maybe VPATH would be a solution to that problem.
>
> ================
> SPAD_SOURCES=$(patsubst %, %.spad, $(SPAD_SRCS))
> VPATH=${srcdir}
> abbrev.list: $(SPAD_SOURCES)
> sed -n 's/^)abbrev [a-z]* *\([A-Z0-9]*\) *\([^ ]*\)/\1 \2/p' \
> $^ > $@
> ================
>
> But I'm not sure whether that works in nonGNU make.
the command and that should produce identical command line.
One way to shorten command line is to change directory before
running sed. More drastic one would be to use a shell loop
and do it file by file (shell is supposed to have no limits
on line length).
> In addition to all of that...
> Maybe it would be a good idea to already sort abbrev.list alphabetically
> with respect to the long name of the constructor.
is responsible for the final result. If sombody wants different
order then it us enough to modify doc makefile.
--
Waldek Hebisch
heb...@math.uni.wroc.pl
Ralf Hemmecke
May 21, 2014, 4:19:12 AM5/21/14
to fricas...@googlegroups.com
>> I dislike hardcoding it via ../algebra .
> We need to hardcode that _somewhere_.
I still dislike ../algebra, but don't want to stop you from committing.
> We need to hardcode that _somewhere_.
I shouldn't try to solve problems before they really become a bottleneck.
Another point why I dislike ../algebra/abbrev.list is that it is only a
dependency. Make cannot go on if that file is missing, because the rules
for building abbrev.list live outside of src/doc/Makefile.
Well, not in our case a big problem (or a problem at all) since I need
AXIOMsys anyway to build the docs, but in general if there are rules
that cannot be resolved in one Makefile, the Makefile in src must
declare all of src/algebra a dependency of src/doc. So that stops make
from fully exploiting parallelism. But I guess you know already about
"Recursive Make Considered Harmful".
http://miller.emu.id.au/pmiller/books/rmch/
>> In addition to all of that...
>> Maybe it would be a good idea to already sort abbrev.list alphabetically
>> with respect to the long name of the constructor.
>
> _That_ would create unneeded dependency.
useful for other things. And "sort" is not really a dependency. It was
just an idea after all.
But what might be interesting is to put also all of the )abbrev
arguments into abbrev.list (including domain/package/category). By this
you could make the explicit SPADLIST* variables go away. (Maybe, you can
also do this without the domain/package/category tags.) I just thought
it might be a good idea to have *all* information in one place.
I don't yet know if the distinction into constructor classes is already
useful in the build process somewhere.
Anyway, I'm all for *not splitting* the .spad files during the build.
Ralf
Reply all
Reply to author
Forward
0 new messages