Edit detail for SpadFileConvention revision 2 of 3

Conventions for writing .spad files after noweb has been dropped

• .spad files must be understood by the SPAD compiler
• 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.

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 <hebisch@math.uni.wroc.pl>

  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
  hebisch@math.uni.wroc.pl