[Texmacs-dev] A first step towards a clean spec of LP mode for texmacs

[David MENTRE]

Hello Felix,

I started to write a short illustrated spec of what I want to do with
the Literate Programming TeXmacs mode. I tried to include requirements
for the mode but I probably forgot things. Your review?


== Illustrated specs for LP-mode of TeXmacs (v0.1) ==

* Suppose we have following file.tm.cpp source file:

---file.tm.cpp---
#include <iostream>

using namespace std;

// Class Hello is designed...
class Hello {
public:
  void print(void);
};

// method print() uses a tricky algorithm because...
void Hello::print(void) 
{
  cout << "Hello world!\n";
}

int main(void)
{
  Hello *h = new Hello();
  h->print();
  delete h;

  return 0;
}
---end of file.tm.cpp---


* We want to import it into TeXmacs

File>Load...>"file.tmp.cpp"

It is displayed in texmacs as following example. All the characters in
LP blocks should *not* be interpreted as texmacs control character
(e.g. '<').

Moreover, for initial import, the comments converted into texmacs plain
text should also not be interpreted (should we use a special
Import... option of LP mode to do that?).

Example:

   +----------(verbatim LP block)------
   |#include <iostream>
   |
   |using namespace std;
   +--------------


  Class Hello is designed...

   +----------(verbatim LP block)------
   |class Hello {
   |public:
   |  void print(void);
   |};
   +--------------
    
  method print() uses a tricky algorithm because...

   +----------(verbatim LP block)------
   |void Hello::print(void) 
   |{
   |  cout << "Hello world!\n";
    }
    
    int main(void)
    {
      Hello *h = new Hello();
      h->print();
      delete h;
    
   |  return 0;
   |}
   +--------------
    

* We need to split the last block of code into two seperated code
  chunks:

Needed LP-mode functionalities:
 - code chunk split;
 - code chunk merge.

Example:

   +----------(verbatim LP block)------
   |void Hello::print(void) 
   |{
   |  cout << "Hello world!\n";
   |}
   +--------------

  Here I enter new doc, with a nice TeXmacs formula:
  <with|mode|math|x<rsup|2>+1> 
  and a some characters that look like /* comments */

   +----------(verbatim LP block)------
   |int main(void)
   |{
      Hello *h = new Hello();
      h->print();
      delete h;
    
   |  return 0;
   |}
   +--------------


* We need to save the file with texmacs code properly escaped:

---file.tm.cpp---
//<TeXmacs|1.0.5.12>
// 
//<style|generic>
//<\body>
#include <iostream>

using namespace std;

// Class Hello is designed...
class Hello {
public:
  void print(void);
};

// method print() uses a tricky algorithm because...
void Hello::print(void) 
{
  cout << "Hello world!\n";
}

//Here I enter new doc, with a nice TeXmacs formula:
//<with|mode|math|x<rsup|2>+1>     
//and a some characters that look like \/\* comments \*\/
int main(void)
{
  Hello *h = new Hello();
  h->print();
  delete h;

  return 0;
}
//</body>
//
//<\initial>
//  <\collection>
//    <associate|language|french>
//  </collection>
//</initial>
---end of file.tm.cpp---

* We need to be able to reload this file, unescaping escapted comments
  in texmacs plain text sections.


* We need to do above operations on three kinds of files:

 1. comment until the end of line (C++ //, VHDL, Ada, Lisp, Scheme,
    ...);

 2. begin-end comment pair, unested (C and C++ /* */);

 3. begin-end comment pair, nested (Ocaml (* *)).

I think cases (2) and (3) can be processed in the same way, with proper
escaping of nested comment characters.

So we need a database with, for each language:

 - language suffix (.cpp -> C++, ...);

 - comment style (comment pairs or until end of line);

 - comment sequence ("//" for C++, ("/*", "*/) for C, ...);

 - escape sequence (Always '\' ?? Not necessary for comment
   until-end-of-line type languages??).

Some languages can have multiple types of comments. E.g. GNU C (// and
/* */), Intel's IXP assembler (";", "//" and "/*" "*/").


* More elaborated literate programming features:

 - being able to reorder code chunks.

Otherwise, I think all literate programming features (cross-references,
images, formulas, ...) are already provided by current TeXmacs.


Best wishes,
d.
-- 
pub  1024D/A3AD7A2A 2004-10-03 David MENTRE <address@hidden>
 5996 CC46 4612 9CA4 3562  D7AC 6C67 9E96 A3AD 7A2A