On 02/04/14 02:37, Bill Page wrote:
On 1 April 2014 21:17, Waldek Hebisch <[email protected]> wrote:
...
In FriCAS you are not supposed to mix documentation and code.
If your documentation is usable from HyperDoc then it should
go into src/doc/ht or src/doc/htex. Otherwise doc is a good
place. IME trying to mix documentation and code make writing
documentation harder and lowers quality of documentation.
The only useful case beeing example code in documentation
and this is handled in .ht (and .htex) files.
Actually I agree with you. I think that in FriCAS you have argued -
and now I agree with you - that the use of pamphlet files inherited
from the original Axiom project is of little or even negative utility.
It would be best to replace all pamphlet files with just the original
spad files as was the case in the original NAG source code release.
The little useful documentation in the existing pamphlet files is
better off moved to the .htex files. If this were the case then there
would be no need for a separate target src directory and the issue
with false positives and Ralf's code would not arise.
I agree with you about going back to the original spad files but not
about going to hypertext. As far as I can see hypertext is an old
fashioned interface, in a small window on the screen, which I never use
because it crashes too often. Its also very hard to contribute to (I've
tried).
At the moment documentation is spread between:
Literate Programming (which is spread over about 400 pamphlet files
and it is not always clear which one might hold the information that is
being sought)
Hypertext - An old fashioned interface which I never use.
Axiom Book in either PDF or html form
FriCAS Wiki, formally known as Axiom Wiki.
fricas-devel mailing list
Online Documentation spread over various places on the web.
Much of this is out of date and confusing. It is very incomplete, even
if you manage to search through all of this, chances are you wont find
what you want?
I don't find Literate Programming or Hypertext encourages better
documentation, in fact I think they make it more difficult. As
experiments, judging by the results in FriCAS both literate programming
and hypertext have failed.
I think that a lot of this documentation needs to be brought together in
on place so that a person, looking for information on a given topic,
knows where to find it.
I think that it needs to be easy to produce documentation using
off-the-shelf tools and it should be easy to add diagrams. However
interactive documentation is just not worth the developers time for the
minimal benefit.
I think the documentation should be on a well structured website with
lots of diagrams. I think it should be static (not wiki or hypertext).
This is all just my opinion, which is not important, the important thing
is what would give a potential new user of FriCAS the impression that
this is a high quality program that it is worth investing their time and
commitment too. Also what is it practical to do with to developer
resources available, its no use having a sentimental attachment to
certain paradigms if there are not enough people to do it properly.
Martin
--
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 [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.
