Edit detail for SpadFileConvention revision 3 of 3

Conventions for writing .spad files after noweb has been dropped

• .spad files must be understood by the SPAD compiler and can be compiled separately
• for bootstrap there is a script that splits files into pieces starting at )abbrev lines and ending just before next )abbrev line or at the end of file. Consequently, each such piece must be complete valid Spad file. In particular constructor documentation should go after )abbrev line
• Literate documentation (proper LaTeX) should be written inside :

        )if LiterateDoc
        ...
        )endif
  

• There is an awk script in the commit message of r1773 that turns xhash.spad into a proper LaTeX file.

  See: http://sourceforge.net/p/fricas/code/1773/ or https://github.com/fricas/fricas/commit/c6a9d5251e7a7d8b6f9af10c31d6b3780747f8cb

History

Since revision r1764, FriCAS does not use noweb anymore. https://groups.google.com/d/msg/fricas-devel/_cAs5lm8rS4/mcVSx6iGVHAJ

A new convention for .spad files has been introduced. Note: Currently .spad files are valid Spad From a mail of Waldek Hebisch to the fricas-devel mailing list::

Subject: fricas-devel Recent changes To: fricas-devel@googlegroups.com Date: Fri, 16 May 2014 05:23:10 +0200 (CEST) From: Waldek Hebisch

FriCAS no longer uses noweb. .spad.pamphelt files are renamed to .spad. We have now a little sed script called unpack_file which splits source files into pieces corresponding 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.

Concerning structure of sources, currently there is a requirement 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 hebisch@math.uni.wroc.pl