doc.cpp

Go to the documentation of this file.

/************************************************************************
 ************************************************************************
 FAUST compiler
 Copyright (C) 2009 GRAME, Centre National de Creation Musicale
 ---------------------------------------------------------------------
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.
 
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 ************************************************************************
 ************************************************************************/



/*****************************************************************************
 ******************************************************************************
 
 
                        The Documentator Language
 
 
 ******************************************************************************
 *****************************************************************************/


#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <sys/stat.h>
#include <time.h>
#include <algorithm>
#include <functional>

#include <iostream>
#include <fstream>
#include <sstream>

#include <map>
#include <string>
#include <vector>

#include "ppbox.hh"
#include "prim2.hh"
#include "doc.hh"
#include "eval.hh"
#include "errormsg.hh"
#include "doc_Text.hh"
#include "sigprint.hh"
#include "propagate.hh"
#include "enrobage.hh"
#include "drawschema.hh"
#include "names.hh"
#include "simplify.hh"
#include "privatise.hh"
#include "recursivness.hh"
#include "sourcereader.hh"
#include "lateq.hh"
#include "doc_compile.hh"
#include "doc_lang.hh"
#include "doc_notice.hh"
#include "doc_autodoc.hh"
#include "compatibility.hh"



#define MAXIDCHARS 5                ///< max numbers (characters) to represent ids (e.g. for directories).

using namespace std ;


/*****************************************************************************
                        Globals and prototyping
 *****************************************************************************/

extern Tree                     gExpandedDefList;
extern map<Tree, set<Tree> >    gMetaDataSet;
extern map<string, string>      gDocMetadatasStringMap;
extern map<string, string>      gDocMathStringMap;
extern bool                     gDetailsSwitch;
extern bool                     gStripDocSwitch;
extern string                   gFaustDirectory;
extern string                   gFaustSuperDirectory;
extern string                   gFaustSuperSuperDirectory;
extern string                   gMasterDocument;
extern string                   gMasterName;
extern SourceReader             gReader;

extern string                   gDocName;               
static const char*              gDocDevSuffix;          
static string                   gCurrentDir;            
static const string             gLatexheaderfilename = "latexheader.tex";

vector<Tree>                    gDocVector;             

static struct tm                gCompilationDate;

bool                            gLstDependenciesSwitch  = true; 
bool                            gLstMdocTagsSwitch      = true; 
bool                            gLstDistributedSwitch   = true; 

enum { langEN, langFR, langIT };
string              gDocLang;

/* Printing functions */
static void     printlatexheader(istream& latexheader, const string& faustversion, ostream& docout);
static void     printfaustlistings(ostream& docout);
static void     printfaustlisting(string& path, ostream& docout);
static void     printlatexfooter(ostream& docout);
static void     printdoccontent(const char* svgTopDir, const vector<Tree>& docVector, const string& faustversion, ostream& docout);
static void     printfaustdocstamp(const string& faustversion, ostream& docout);
static void     printDocEqn(Lateq* ltq, ostream& docout);
static void     printDocDgm(const Tree expr, const char* svgTopDir, ostream& docout, int i);
static void     printDocMetadata(const Tree expr, ostream& docout);

/* Primary sub-functions for <equation> handling */
static void prepareDocEqns( const vector<Tree>& docBoxes, vector<Lateq*>& docCompiledEqnsVector );      
static void collectDocEqns( const vector<Tree>& docBoxes, vector<Tree>& eqBoxes );                      
static void mapEvalDocEqn( const vector<Tree>& eqBoxes, const Tree& env, vector<Tree>& evalEqBoxes );   
static void mapGetEqName( const vector<Tree>& evalEqBoxes, vector<string>& eqNames );                   
static void calcEqnsNicknames( const vector<string>& eqNames, vector<string>& eqNicknames );            
static void mapPrepareEqSig( const vector<Tree>& evalEqBoxes, vector<int>& eqInputs, vector<int>& eqOutputs, vector<Tree>& eqSigs );    
static void mapSetSigNickname( const vector<string>& eqNicknames, const vector<int>& eqInputs, const vector<Tree>& eqSigs );    
static void collectEqSigs( const vector<Tree>& eqSigs, Tree& superEqList );                             
static void annotateSuperList( DocCompiler* DC, Tree superEqList );                             
//static void   calcAndSetLtqNames( Tree superEqList );     ///< step 9. 
static void mapCompileDocEqnSigs( const vector<Tree>& eqSigs, const vector<int>& eqInputs, const vector<int>& eqOutputs, DocCompiler* DC, vector<Lateq*>& docCompiledEqnsVector );  

/* Secondary sub-functions for <equation> handling */
static string   calcNumberedName(const char* base, int i);
static void     getBoxInputsAndOutputs(const Tree t, int& numInputs, int& numOutputs);
static string   calcDocEqnInitial(const string s);

/* Notice related functions */
static void     initCompilationDate();
static struct tm* getCompilationDate();

/* Files functions */
static int      cholddir ();
static int      mkchdir(const char* dirname);
static int      makedir(const char* dirname);
static void     getCurrentDir();
static istream* openArchFile (const string& filename);
static char*    legalFileName(const Tree t, int n, char* dst);
static string   rmExternalDoubleQuotes(const string& s);
static void     copyFaustSources(const char* projname, const vector<string>& pathnames);
vector<string>& docCodeSlicer(const string& faustfile, vector<string>& codeSlices);
static void     printdocCodeSlices(const string& code, ostream& docout);
static bool     doesFileBeginWithCode(const string& faustfile);

//static void       declareAutoDoc();



/*****************************************************************************
                    Types of Documentation Elements
 *****************************************************************************/

Sym DOCTXT = symbol ("DocTxt");
Tree docTxt(const char* name)       { return tree( DOCTXT, tree(symbol(name)) ); }
bool isDocTxt(Tree t)               { return t->node() == Node(DOCTXT); }
bool isDocTxt(Tree t0, const char** str)
{
    Tree t1; Sym s;
    if ( isTree(t0, DOCTXT, t1) && isSym(t1->node(), &s) ) {
        *str = name(s);
        return true;
    } else {
        return false;
    }
}

Sym DOCEQN = symbol ("DocEqn");
Tree docEqn(Tree x)                 { return tree(DOCEQN, x);       }
bool isDocEqn(Tree t, Tree& x)      { return isTree(t, DOCEQN, x);  }

Sym DOCDGM = symbol ("DocDgm");
Tree docDgm(Tree x)                 { return tree(DOCDGM, x);       }
bool isDocDgm(Tree t, Tree& x)      { return isTree(t, DOCDGM, x);  }

Sym DOCNTC = symbol ("DocNtc");
Tree docNtc()                       { return tree(DOCNTC);          }
bool isDocNtc(Tree t)               { return isTree(t, DOCNTC);     }

Sym DOCLST = symbol ("DocLst");
Tree docLst()                       { return tree(DOCLST);          }
bool isDocLst(Tree t)               { return isTree(t, DOCLST);     }

Sym DOCMTD = symbol ("DocMtd");
Tree docMtd(Tree x)                 { return tree(DOCMTD, x);       }
bool isDocMtd(Tree t, Tree& x)      { return isTree(t, DOCMTD, x);  }

//string getDocTxt(Tree t)          { return hd(t)->branch(0); }



/*****************************************************************************
                Main Printing Function for the Documentation
 *****************************************************************************/


void printDoc(const char* projname, const char* docdev, const char* faustversion)
{
    gDocDevSuffix = docdev;
    
    //cerr << "Documentator : printDoc : gFaustDirectory = '" << gFaustDirectory << "'" << endl;
    //cerr << "Documentator : printDoc : gFaustSuperDirectory = '" << gFaustSuperDirectory << "'" << endl;
    //cerr << "Documentator : printDoc : gFaustSuperSuperDirectory = '" << gFaustSuperSuperDirectory << "'" << endl;
    //cerr << "Documentator : printDoc : gCurrentDir = '" << gCurrentDir << "'" << endl;
    
    makedir(projname);          // create a top directory to store files
    
    string svgTopDir = subst("$0/svg", projname);
    makedir(svgTopDir.c_str()); // create a directory to store svg-* subdirectories.
    
    string cppdir = subst("$0/cpp", projname);
    makedir(cppdir.c_str());    // create a cpp directory.
    
    string pdfdir = subst("$0/pdf", projname);
    makedir(pdfdir.c_str());    // create a pdf directory.
    
    /* Copy all Faust source files into an 'src' sub-directory. */
    vector<string> pathnames = gReader.listSrcFiles();
    copyFaustSources(projname, pathnames);
    
    string texdir = subst("$0/tex", projname);
    mkchdir(texdir.c_str());    // create a directory and move into.

    ofstream docout(subst("$0.$1", gDocName, docdev).c_str());
    cholddir();                 // return to current directory
    
    loadTranslationFile(gDocLang);
    
    if (gDocVector.empty()) { declareAutoDoc(); }   
    
    printfaustdocstamp(faustversion, docout);                       
    istream* latexheader = openArchFile(gLatexheaderfilename);
    printlatexheader(*latexheader, faustversion, docout);                       
    printdoccontent(svgTopDir.c_str(), gDocVector, faustversion, docout);       
    printlatexfooter(docout);                                       
}



/*****************************************************************************
            LaTeX basic printing functions of the Documentation
 *****************************************************************************/

static void printlatexheader(istream& latexheader, const string& faustversion, ostream& docout)
{   
    string  s;
    while(getline(latexheader, s)) docout << s << endl;
    
    docout << "\\newcommand{\\faustfilename}{" << gMasterDocument << "}" << endl;
    docout << "\\newcommand{\\faustdocdir}{" << gMasterName << "-mdoc}" << endl;
    docout << "\\newcommand{\\faustprogname}{" << gMasterName << "}" << endl;
    docout << "\\newcommand{\\faustversion}{" << faustversion << "}" << endl;
    char datebuf [150];
    strftime (datebuf, 150, "%B %d, %Y", getCompilationDate());
    docout << "\\newcommand{\\faustdocdate}{" << datebuf << "}" << endl;
    
    docout << endl << "\\begin{document}" << endl;
}


static void printDocMetadata(const Tree expr, ostream& docout)
{
    if (gMetaDataSet.count(expr)) {
        string sep = "";
        set<Tree> mset = gMetaDataSet[expr];
        
        for (set<Tree>::iterator j = mset.begin(); j != mset.end(); j++) {
            docout << sep << rmExternalDoubleQuotes(tree2str(*j));
            sep = ", ";
        }
    }
}


static void printfaustlistings(ostream& docout)
{   
    if (gLstDependenciesSwitch) {
        vector<string> pathnames = gReader.listSrcFiles();
        for (unsigned int i=0; i< pathnames.size(); i++) {
            printfaustlisting(pathnames[i], docout);
        }
    } else {
        printfaustlisting(gMasterDocument, docout);
    }
}


static void printfaustlisting(string& faustfile, ostream& docout)
{   
    string  s;
    ifstream src;
    
    //cerr << "Documentator : printfaustlisting : Opening file '" << faustfile << "'" << endl;
    src.open(faustfile.c_str(), ifstream::in);
    
    docout << endl << "\\bigskip\\bigskip" << endl;
    docout << "\\begin{lstlisting}[caption=\\texttt{" << filebasename(faustfile.c_str()) << "}]" << endl;

    bool isInsideDoc = false;
    
    if (faustfile != "" && src.good()) {
        while(getline(src, s)) { 
            size_t foundopendoc  = s.find("<mdoc>");
            if (foundopendoc != string::npos && gStripDocSwitch) isInsideDoc = true;
            
            if (isInsideDoc == false)
                docout << s << endl;
            
            size_t foundclosedoc = s.find("</mdoc>");
            if (foundclosedoc != string::npos && gStripDocSwitch) isInsideDoc = false;
        }
    } else {
        cerr << "ERROR : can't open faust source file " << faustfile << endl;
        exit(1);
    }
    
    docout << "\\end{lstlisting}" << endl << endl;
}


static void printlatexfooter(ostream& docout)
{
    docout << endl << "\\end{document}" << endl << endl;
}


static void printfaustdocstamp(const string& faustversion, ostream& docout)
{
    char datebuf [150];
    strftime (datebuf, 150, "%c", getCompilationDate());
    
    docout << "%% This documentation was generated with Faust version " << faustversion << endl;
    docout << "%% " << datebuf << endl;
    docout << "%% http://faust.grame.fr" << endl << endl;
}



/*****************************************************************************
            Main loop : launches prepare, evaluate, and print functions
 *****************************************************************************/

static void printdoccontent(const char* svgTopDir, const vector<Tree>& docVector, const string& faustversion, ostream& docout)
{
    //cerr << endl << "Documentator : printdoccontent : " << docVector.size() << " <mdoc> tags read." << endl;
    
    vector<Lateq*>  docCompiledEqnsVector;
    prepareDocEqns( docVector, docCompiledEqnsVector ); 
    vector<Lateq*>::iterator eqn_it = docCompiledEqnsVector.begin();
    
    int dgmIndex = 1;           

    vector<string> docMasterCodeMap;
    docMasterCodeMap = docCodeSlicer(gMasterDocument, docMasterCodeMap);
    
    vector<Tree>::const_iterator doc;
    vector<string>::const_iterator code;
    code = docMasterCodeMap.begin();
    
    if(doesFileBeginWithCode(gMasterDocument) && (! docMasterCodeMap.empty()) && gLstDistributedSwitch ) {
        printdocCodeSlices(*code, docout);
        code++;
    }
    
    for (doc=docVector.begin(); doc<docVector.end(); doc++, code++) {
        
        Tree L = reverse(*doc);
        //cerr << "Entering into <mdoc> parsing..." << endl; 
        
        while (isList(L)) {
            Tree expr;
            if ( isDocEqn(hd(L), expr) ) { 
                printDocEqn(*eqn_it++, docout);
            }
            else if ( isDocDgm(hd(L), expr) ) { 
                printDocDgm(expr, svgTopDir, docout, dgmIndex++);
            }
            else if ( isDocMtd(hd(L), expr) ) { 
                printDocMetadata(expr, docout);
            }
            else if ( isDocTxt(hd(L)) ) { 
                docout << *hd(L)->branch(0); // Directly print registered doc text.
            }
            else if ( isDocNtc(hd(L)) ) { 
                printDocNotice(faustversion, docout);
            }
            else if ( isDocLst(hd(L)) ) { 
                printfaustlistings(docout);
            }
            else { 
                cerr << "ERROR : " << *hd(L) << " is not a valid documentation type." << endl; 
            }
            L = tl(L);
        }
        //cerr << " ...end of <mdoc> parsing." << endl; 
        
        if ( code != docMasterCodeMap.end() && gLstDistributedSwitch ) {
            printdocCodeSlices(*code, docout);
        }
    }
}



/*****************************************************************************
            Primary sub-functions for <equation> handling
 *****************************************************************************/

static void prepareDocEqns(const vector<Tree>& docBoxes, vector<Lateq*>& docCompiledEqnsVector)
{   
    vector<Tree>    eqBoxes;        collectDocEqns( docBoxes, eqBoxes );        
    
    if(! eqBoxes.empty() ) {
        vector<Tree>    evalEqBoxes;    mapEvalDocEqn( eqBoxes, gExpandedDefList, evalEqBoxes );    
        vector<string>  eqNames;        mapGetEqName( evalEqBoxes, eqNames );       
        vector<string>  eqNicknames;    calcEqnsNicknames( eqNames, eqNicknames );  
        
        vector<int>     eqInputs;
        vector<int>     eqOutputs;
        vector<Tree>    eqSigs;         mapPrepareEqSig( evalEqBoxes, eqInputs, eqOutputs, eqSigs );    
        mapSetSigNickname( eqNicknames, eqInputs, eqSigs );                                 
        Tree            superEqList;    collectEqSigs( eqSigs, superEqList );       
        
        DocCompiler* DC = new DocCompiler(0, 0);
        annotateSuperList( DC, superEqList );                                       
        //calcAndSetLtqNames( superEqList );                                        ///< step 9. (directly in 10.)
        mapCompileDocEqnSigs( eqSigs, eqInputs, eqOutputs, DC, docCompiledEqnsVector );     
    }
}


static void collectDocEqns(const vector<Tree>& docBoxes, vector<Tree>& eqBoxes)
{
    int nbdoceqn = 0;
    
    for (vector<Tree>::const_iterator doc=docBoxes.begin(); doc<docBoxes.end(); doc++) {
        Tree L = reverse(*doc);
        Tree expr;
        while (isList(L)) {
            if ( isDocEqn(hd(L), expr) ) {
                eqBoxes.push_back(expr);
                nbdoceqn++;
            }
            L = tl(L);
        }
    }
    //cerr << "Documentator : collectDocEqns : " << nbdoceqn << " <equation> tags found." << endl;
}


static void mapEvalDocEqn(const vector<Tree>& eqBoxes, const Tree& env, vector<Tree>& evalEqBoxes)
{
    //cerr << "###\n# Documentator : mapEvalDocEqn" << endl;
    
    for ( vector<Tree>::const_iterator eq=eqBoxes.begin(); eq < eqBoxes.end(); eq++)
    {
        evalEqBoxes.push_back(evaldocexpr( *eq, env ));
    }
    //cerr << "Documentator : end of mapEvalDocEqn\n---" << endl;
}


static void mapGetEqName(const vector<Tree>& evalEqBoxes, vector<string>& eqNames)
{
    //cerr << "###\n# Documentator : mapGetEqName" << endl;
    
    int i = 1;
    for( vector<Tree>::const_iterator eq = evalEqBoxes.begin(); eq < evalEqBoxes.end(); eq++, i++ ) {
        Tree id;
        string s;
        int n,m; getBoxType(*eq, &n, &m); // eq name only for bd without inputs
        if ( n==0 && getDefNameProperty(*eq, id) ) {
            s = tree2str(id);
        }
        else {
            s = calcNumberedName("doceqn-", i);
        }       
        eqNames.push_back( s ) ;
    }
    //cerr << "Documentator : end of mapGetEqName\n---" << endl;
}


static void calcEqnsNicknames(const vector<string>& eqNames, vector<string>& eqNicknames)
{
    //cerr << "###\n# Documentator : calcEqnsNicknames" << endl;
    
    vector<string> v;
    
    for( vector<string>::const_iterator eq = eqNames.begin(); eq < eqNames.end(); eq++ ) {
        string init = calcDocEqnInitial(*eq);
        v.push_back(init);
//      for( vector<string>::iterator it = v.begin(); it < v.end()-1; ++it ) {
//          if (init == *it) {
//              //cerr << "!! Warning Documentator : calcEqnsNicknames : duplicates \"" << init << "\"" << endl;
//          }
//      }
        eqNicknames.push_back(init);
    }
    
//  for( vector<string>::const_iterator eq = eqNames.begin(); eq < eqNames.end(); eq++ ) {
//      int c = 0;
//      c = count_if(eqNames.begin(), eqNames.end(), bind2nd(equal_to<string>(), *eq));
//      if (c > 0) { 
//          cerr << "- Duplicate nickname !! " << *eq << endl; 
//      } else {
//          cerr << "(no duplicate) " << *eq << endl;
//      }
//  }
    
    //cerr << "Documentator : end of calcEqnsNicknames\n---" << endl;
}


static void mapPrepareEqSig(const vector<Tree>& evalEqBoxes, vector<int>& eqInputs, vector<int>& eqOutputs, vector<Tree>& eqSigs)
{
    //cerr << "###\n# Documentator : mapPrepareEqSig" << endl;
    
    for( vector<Tree>::const_iterator eq = evalEqBoxes.begin(); eq < evalEqBoxes.end(); eq++ ) {
        
        int numInputs, numOutputs;
        getBoxInputsAndOutputs(*eq, numInputs, numOutputs);
        //cerr << numInputs <<" ins and " << numOutputs <<" outs" << endl;
        eqInputs.push_back(numInputs);
        eqOutputs.push_back(numOutputs);
        
        Tree lsig1 = boxPropagateSig( nil, *eq , makeSigInputList(numInputs) );
        //cerr << "output signals are : " << endl;  printSignal(lsig1, stderr);
        
        Tree lsig2 = deBruijn2Sym(lsig1);   
        Tree lsig3 = simplify(lsig2);       
        //Tree lsig4 = privatise(lsig3);        ///< Un-share tables with multiple writers
        Tree lsig4 = docTableConvertion(lsig3);     


        eqSigs.push_back(lsig4);
    }
    //cerr << "Documentator : end of mapPrepareEqSig\n---" << endl;
}


static void mapSetSigNickname(const vector<string>& eqNicknames, const vector<int>& eqInputs, const vector<Tree>& eqSigs)
{
    //cerr << "###\n# Documentator : mapSetSigNickname" << endl;

//  Do nothing for the moment...
//  for( unsigned int i=0; i < eqSigs.size(); i++ ) {
//      if (eqInputs[i] == 0) // Only "generators" should be finally named with user equation (nick)name.
//          setSigListNickName(eqSigs[i], eqNicknames[i]);
//  }
    //cerr << "Documentator : end of mapSetSigNickname\n---" << endl;
}


static void collectEqSigs(const vector<Tree>& eqSigs, Tree& superEqList)
{
    //cerr << "###\n# Documentator : collectEqSigs" << endl;
    
    superEqList = nil;
    
    for( vector<Tree>::const_iterator it = eqSigs.begin(); it < eqSigs.end(); ++it ) {
        superEqList = cons( *it, superEqList );
    }
    //printSignal(superEqList, stdout, 0);
    
    //cerr << endl << "Documentator : end of collectEqSigs\n---" << endl;
}


static void annotateSuperList(DocCompiler* DC, Tree superEqList)
{
    DC->annotate(superEqList);
}


// * #9. Calculated and set lateq (LaTeX equation) names.
// * Note : Transfered into mapCompileDocEqnSigs (DocCompiler::compileMultiSignal).
// */
//static void   calcAndSetLtqNames(Tree superEqList)
//{
//  
//}


static void mapCompileDocEqnSigs(const vector<Tree>& eqSigs, const vector<int>& eqInputs, const vector<int>& eqOutputs, DocCompiler* DC, vector<Lateq*>& docCompiledEqnsVector)
{
    //cerr << "###\n# Documentator : mapCompileDocEqnSigs" << endl;
    
    for( unsigned int i=0; i < eqSigs.size(); i++ ) {
        
        //      docCompiledEqnsVector.push_back( DC->compileMultiSignal(*it, 0) );
        docCompiledEqnsVector.push_back( DC->compileLateq(eqSigs[i], new Lateq(eqInputs[i], eqOutputs[i])) );
    }
    
    //cerr << "Documentator : end of mapCompileDocEqnSigs\n---" << endl;
}



/*****************************************************************************
                Secondary sub-functions for <equation> handling
 *****************************************************************************/


static string calcDocEqnInitial(const string s)
{
    string nn;
    if(s == "process")
        nn = "Y";
    else if (s.substr(0,6) == "doceqn")
        nn = "Z";
    else
        nn += toupper(s[0]);
    return nn;
}


static void getBoxInputsAndOutputs(const Tree t, int& numInputs, int& numOutputs)
{
    if (!getBoxType(t, &numInputs, &numOutputs)) {
        cerr << "ERROR during the evaluation of t : " << boxpp(t) << endl;
        exit(1);
    }
    //cerr << "Documentator : " << numInputs <<" inputs and " << numOutputs <<" outputs for box : " << boxpp(t) << endl;
}


static void printDocEqn(Lateq* ltq, ostream& docout) 
{
    ltq->println(docout);
    //cerr << "Documentator : printDocEqn : "; ltq->println(cerr); cerr << endl;
}


/*****************************************************************************
                    Sub-function for <diagram> handling
 *****************************************************************************/

static void printDocDgm(const Tree expr, const char* svgTopDir, ostream& docout, int i)
{
    Tree docdgm = evaldocexpr(expr, gExpandedDefList);
    if (gErrorCount > 0) {
        cerr << "Total of " << gErrorCount << " errors during evaluation of : diagram docdgm = " << boxpp(docdgm) << ";\n";
        exit(1);
    }
    
    char dgmid[MAXIDCHARS+1];
    sprintf(dgmid, "%02d", i);
    string thisdgmdir = subst("$0/svg-$1", svgTopDir, dgmid);
    //cerr << "Documentator : printDocDgm : drawSchema in '" << gCurrentDir << "/" << thisdgmdir << "'" << endl;
    
    drawSchema( docdgm, thisdgmdir.c_str(), "svg" );
    
    char temp[1024];
    const string dgmfilename = legalFileName(docdgm, 1024, temp);
    //docout << "figure \\ref{figure" << i << "}";
    docout << "\\begin{figure}[ht!]" << endl;
    docout << "\t\\centering" << endl;
    docout << "\t\\includegraphics[width=\\textwidth]{" << subst("../svg/svg-$0/", dgmid) << dgmfilename << "}" << endl;
    docout << "\t\\caption{" << gDocMathStringMap["dgmcaption"] << " \\texttt{" << dgmfilename << "}}" << endl;
    docout << "\t\\label{figure" << i << "}" << endl;
    docout << "\\end{figure}" << endl << endl;
    
    gDocNoticeFlagMap["nameconflicts"] = true;
    gDocNoticeFlagMap["svgdir"] = true;
}



/*****************************************************************************
                            Other sub-functions
 *****************************************************************************/


vector<string>& docCodeSlicer(const string& faustfile, vector<string>& codeSlices)
{
    string  s;
    ifstream src;
    src.open(faustfile.c_str(), ifstream::in);
    string tmp = "";
    
    bool isInsideDoc = false;
    
    if (faustfile != "" && src.good()) {
        while(getline(src, s)) { 
            size_t foundopendoc  = s.find("<mdoc>");
            
            if (foundopendoc != string::npos) { 
                if (isInsideDoc == false) { 
                    if (! tmp.empty() ) {
                        codeSlices.push_back(tmp); }
                    tmp = "";
                }
                isInsideDoc = true;  
            }
            
            if (isInsideDoc == false) {
                tmp += s + '\n';
            }
            
            size_t foundclosedoc = s.find("</mdoc>");
            if (foundclosedoc != string::npos) isInsideDoc = false;
        }
    } else {
        cerr << "ERROR : can't open faust source file " << faustfile << endl;
        exit(1);
    }
    return codeSlices;
}
            

static void printdocCodeSlices(const string& code, ostream& docout)
{
    if ( ! code.empty() ) {
        docout << endl << "\\begin{lstlisting}[numbers=none, frame=none, basicstyle=\\small\\ttfamily, backgroundcolor=\\color{yobg}]" << endl;
        docout << code << endl;
        docout << "\\end{lstlisting}" << endl << endl;
    }
}


static bool doesFileBeginWithCode(const string& faustfile)
{
    string  s;
    ifstream src;
    src.open(faustfile.c_str(), ifstream::in);
    
    if (faustfile != "" && src.good()) {
        getline(src, s);
        size_t foundopendoc = s.find("<mdoc>");
        if(int(foundopendoc)==0) {
            return false;
        } else {
            return true;
        }
    } else {
        cerr << "ERROR : can't open faust source file " << faustfile << endl;
        exit(1);
    }
}   



//------------------------ dealing with files -------------------------


static int makedir(const char* dirname)
{
    char    buffer[FAUST_PATH_MAX];
    gCurrentDir = getcwd (buffer, FAUST_PATH_MAX);
    
    if ( gCurrentDir.c_str() != 0) {
        int status = mkdir(dirname, S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH);
        if (status == 0 || errno == EEXIST) {
            return 0;
        }
    }
    perror("makedir");
    exit(errno);
}


static int mkchdir(const char* dirname)
{
    char    buffer[FAUST_PATH_MAX];
    gCurrentDir = getcwd (buffer, FAUST_PATH_MAX);

    if ( gCurrentDir.c_str() != 0) {
        int status = mkdir(dirname, S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH);
        if (status == 0 || errno == EEXIST) {
            if (chdir(dirname) == 0) {
                return 0;
            }
        }
    }
    perror("mkchdir");
    exit(errno);
}


static int cholddir ()
{
    if (chdir(gCurrentDir.c_str()) == 0) {
        return 0;
    } else {
        perror("cholddir");
        exit(errno);
    }
}


static void getCurrentDir ()
{
    char    buffer[FAUST_PATH_MAX];
    gCurrentDir = getcwd (buffer, FAUST_PATH_MAX);
}


static istream* openArchFile (const string& filename)
{
    istream* file;
    getCurrentDir();    // Save the current directory.
    //cerr << "Documentator : openArchFile : Opening input file  '" << filename << "'" << endl;
    if ( (file = open_arch_stream(filename.c_str())) ) {
        //cerr << "Documentator : openArchFile : Opening '" << filename << "'" << endl;
    } else {
        cerr << "ERROR : can't open architecture file " << filename << endl;
        exit(1);
    }
    cholddir();         // Return to current directory.
    return file;
}


static char* legalFileName(const Tree t, int n, char* dst)
{
    Tree    id;
    int     i=0;
    if (getDefNameProperty(t, id)) {
        const char*     src = tree2str(id);
        for (i=0; isalnum(src[i]) && i<16; i++) {
            dst[i] = src[i];
        }
    }
    dst[i] = 0;
    if (strcmp(dst, "process") != 0) { 
        // if it is not process add the hex address to make the name unique
        snprintf(&dst[i], n-i, "-%p", t);
    }
    return dst;
}

static string calcNumberedName(const char* base, int i)
{
    char nb[MAXIDCHARS+1];
    sprintf(nb, "%03d", i);
    return subst("$0$1", base, nb);
}

static string rmExternalDoubleQuotes(const string& s)
{
    size_t i = s.find_first_not_of("\"");
    size_t j = s.find_last_not_of("\"");
    
    if ( (i != string::npos) & (j != string::npos) ) {
        return s.substr(i, 1+j-i);
    } else {
        return "";
    }
}


static void copyFaustSources(const char* projname, const vector<string>& pathnames)
{
    string srcdir = subst("$0/src", projname);
    //cerr << "Documentator : copyFaustSources : Creating directory '" << srcdir << "'" << endl;
    makedir(srcdir.c_str());    // create a directory.
        
    for (unsigned int i=0; i< pathnames.size(); i++) {
        ifstream src;
        ofstream dst;
        string faustfile = pathnames[i];
        string copy = subst("$0/$1", srcdir, filebasename(faustfile.c_str()));
        //cerr << "Documentator : copyFaustSources : Opening input file  '" << faustfile << "'" << endl;
        //cerr << "Documentator : copyFaustSources : Opening output file '" << copy << "'" << endl;
        src.open(faustfile.c_str(), ifstream::in);
        dst.open(copy.c_str(), ofstream::out);
        string  s;
        while ( getline(src,s) ) dst << s << endl;
    }
}


//------------------------ date managment -------------------------


static void initCompilationDate()
{
    time_t now;
    
    time(&now);
    gCompilationDate = *localtime(&now);
}

static struct tm* getCompilationDate()
{
    initCompilationDate();
    return &gCompilationDate;
}