Martin Baker wrote: > > In order to complete the recent changes to computation.spad I have > updated the documentation to match the code changes.
Commited. > > Issues: > > 1) Is it possible to suppress automatic insertion of spaces around colon > and commas in literate parts of the file? This was one time change. > 2) Am I wasting my time doing stuff on literate code? > > This is not a big deal for me. I will continue doing the literate > version if you think it worthwhile but, if not, its better not to waste > my (and your) time. > > Usually I first produce documentation in HTML and put it on my website. > I then copy it into code file, this copy is inferior to the HTML version > because it does not have diagrams. What do you use to create diagrams? In other words: what is the sorce code of your diagrams? > So why not just rely on the online documentation? Well, I prefer to be independent of network if possible. Network have unpredictable performance, may be not available at all. There are also securtity problems which vanish if tere is no network connection. So it good to have standalone documentation. Another aspect is conceptual and technical integrity. Online documentation fits well to distributed/decentralized model where various pieces are developed independently. This has advantages, allowing various approches and creating diverse points of view. But it also leads to replication and bloat. And it makes harder to find relevant correct documentation. So it makes sense to develop core documentation in more coordinated way, trying to use common style and common tools. Unfortunately, in the past it was hard to reach agreement what the common approach should be. There is documentation by original authors in HyperDoc format. There were proposal to use literate style, putting documentation together with source code. Original authors already have kind of "literate" provision, by using '++' comments. Information from '++' comments is than shown by HyperDoc. The later literate proposal wanted to use noweb, using special markup to distinguish between code and markup. There is Axiom Wiki which tried to be a place for collaborative developement of documentationn. There are also folks that do things in their own way: Arthur Ralfs translated Axiom book to Math ML, there are things which are Web only. I personally prefer to follow original authors: use ++ comments and HyperDoc format for documentation. Of course HyperDoc the program is dated. However HyperDoc format has several advantages: - it is a (small) subset of Latex, so it is natural for many mathematicians - it is simple restricted format, so it can be converted to other formats with relatively little effort - we already have substantial body of documentation in this format and toolchain to process it, in particular it automatically inserts results of examples into documentation IMO ability to produce different renderings (versions) of documentation is important. Coming back to your question about literate documentation: IMO literate approach was a mistake. Documentation in separate files is easier to handle and works better. OTOH literate documentation is clearly much better than no documentation at all. I will try to convert parts of your documentation to HyperDoc, we will see how it works. > It would be really good if Fricas IO could be the hub for all the > various types of online documentation for all categories, domains, etc. > If there were to be a standardised way to embed URLs in ++ comments like > this: > > ++ Author: Martin Baker > ++ Date Created: March 2011 > ++ Basic Operations: > ++ Related Constructors: > ++ Also See: > ++ AMS Classifications: > ++ Keywords: > ++ Reference: > http://www.euclideanspace.com/prog/scratchpad/mycode/computation/ > ++ Tutorial: > http://www.euclideanspace.com/prog/scratchpad/mycode/computation/lambda/ > ++ An implementation of untyped lambda-calculus > > Then Fricas IO might be able to pick up the URLs and generate links that > users would see when they were browsing this domain. Well, in TeX/LaTeX "standard" is '\url{http://....}'. But Fricas IO is creation of Ralf Hemmecke so it up to him... -- Waldek Hebisch -- 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+unsubscr...@googlegroups.com. To post to this group, send email to fricas-devel@googlegroups.com. Visit this group at https://groups.google.com/group/fricas-devel. For more options, visit https://groups.google.com/d/optout.
