/************************************************************************
 ************************************************************************
 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
 
 
 ******************************************************************************
 *****************************************************************************/


/**
 * @file doc.cpp
 * @author Karim Barkati and Yann Orlarey
 * @version 1.0
 * @date 2009
 * @brief Implementation of documentation trees support and printing.
 */

#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;				///< Contains the filename for out documentation.
static const char* 				gDocDevSuffix;			///< ".tex" (or .??? - used to choose output device).
static string 					gCurrentDir;			///< Room to save current directory name.
static const string				gLatexheaderfilename = "latexheader.tex";

vector<Tree> 					gDocVector;				///< Contains <mdoc> parsed trees: DOCTXT, DOCEQN, DOCDGM.

static struct tm				gCompilationDate;

bool							gLstDependenciesSwitch	= true; ///< mdoc listing management.
bool							gLstMdocTagsSwitch		= true; ///< mdoc listing management.
bool							gLstDistributedSwitch	= true; ///< mdoc listing management.

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 );		///< Caller function.
static void	collectDocEqns( const vector<Tree>& docBoxes, vector<Tree>& eqBoxes );						///< step 0. Feed a vector.
static void	mapEvalDocEqn( const vector<Tree>& eqBoxes, const Tree& env, vector<Tree>& evalEqBoxes );	///< step 1. Evaluate boxes.
static void	mapGetEqName( const vector<Tree>& evalEqBoxes, vector<string>& eqNames );					///< step 2. Get boxes name.
static void	calcEqnsNicknames( const vector<string>& eqNames, vector<string>& eqNicknames );			///< step 3. Calculate nicknames.
static void	mapPrepareEqSig( const vector<Tree>& evalEqBoxes, vector<int>& eqInputs, vector<int>& eqOutputs, vector<Tree>& eqSigs );	///< step 4&5. Propagate and prepare signals.
static void	mapSetSigNickname( const vector<string>& eqNicknames, const vector<int>& eqInputs, const vector<Tree>& eqSigs );	///< step 6. Set signals nicknames.
static void	collectEqSigs( const vector<Tree>& eqSigs, Tree& superEqList );								///< step 7. Collect all signals in a superlist.
static void	annotateSuperList( DocCompiler* DC, Tree superEqList );								///< step 8. Annotate superlist.
//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 );	///< step 10. Compile equations.

/* 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
 *****************************************************************************/


/**
 * @brief The entry point to generate faust doc files.
 *
 * The entry point to generate the output LaTeX file, stored in the directory "<projname>-math/".
 * This file eventually references images for diagrams, generated in SVG subdirectories.
 * The device system was adapted from drawSchema's device system.
 *
 * @param[in]	projname		Basename of the new doc directory ("*-math").
 * @param[in]	docdev			The doc device; only ".tex" is supported for the moment.
 * @param[in]	faustversion	The current version of this Faust compiler.
 */
void printDoc(const char* projname, const char* docdev, const char* faustversion)
{
	gDocDevSuffix = docdev;
	
	/** File stuff : create doc directories and a tex file. */
	//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.

	 /** Create THE mathdoc tex file. */
	ofstream docout(subst("$0.$1", gDocName, docdev).c_str());
	cholddir();					// return to current directory
	
	/** Init and load translation file. */
	loadTranslationFile(gDocLang);
	
	/** Simulate a default doc if no <mdoc> tag detected. */
	if (gDocVector.empty()) { declareAutoDoc(); } 	
	
	/** Printing stuff : in the '.tex' ouptut file, eventually including SVG files. */
	printfaustdocstamp(faustversion, docout);						///< Faust version and compilation date (comment).
	istream* latexheader = openArchFile(gLatexheaderfilename);
	printlatexheader(*latexheader, faustversion, docout);						///< Static LaTeX header (packages and setup).
	printdoccontent(svgTopDir.c_str(), gDocVector, faustversion, docout);		///< Generate math contents (main stuff!).
	printlatexfooter(docout);										///< Static LaTeX footer.
}



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

/** 
 * Print a static LaTeX header. 
 *
 * @param[in]	latexheader		The file containing the static part of the LaTeX header.
 * @param[in]	faustversion	The current version of this Faust compiler.
 * @param[out]	docout			The LaTeX output file to print into.
 */
static void printlatexheader(istream& latexheader, const string& faustversion, ostream& docout)
{	
	string	s;
	while(getline(latexheader, s)) docout << s << endl;
	
	/** Specific LaTeX macros for Faust */
	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;
}


/**
 * @Brief Print a metadata set.
 * 
 * Each metadata is a set, in order to handle multiple items,
 * like multiple authors, even if most of metadatas have
 * unique items.
 * 
 * @param[in]	expr		Parsed metadata keyname, as boxes tree.
 * @param[out]	docout		The output file to print into.
 */
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 = ", ";
		}
	}
}


/** 
 * Print listings of each Faust code ".dsp" files,
 * calling the 'printfaustlisting' function.
 *
 * @param[out]	docout		The LaTeX output file to print into.
 */
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);
	}
}


/** 
 * Print a listing of the Faust code, in a LaTeX "listing" environment.
 * Strip content of <mdoc> tags.
 *
 * @param[in]	faustfile	The source file containing the Faust code.
 * @param[out]	docout		The LaTeX output file to print into.
 */
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)) { /** We suppose there's only one <mdoc> tag per line. */
			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;
}


/** 
 * Print the static LaTeX footer. 
 *
 * @param[out]	docout		The LaTeX output file to print into.
 */
static void printlatexfooter(ostream& docout)
{
	docout << endl << "\\end{document}" << endl << endl;
}


/** 
 * Print a "doc stamp" in the LaTeX document :
 * - the Faust version,
 * - the date of doc compilation,
 * - faust's web site URL.
 *
 * @param[in]	faustversion	The current version of this Faust compiler.
 * @param[out]	docout			The LaTeX output file to print into.
 */
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
 *****************************************************************************/

/**
 * @brief Main documentator loop.
 *
 * First loop on gDocVector, which contains the faust <mdoc> trees.
 * Second loop for each of these <mdoc> trees, which contain parsed input expressions of 3 types :
 * DOCEQN for <equation> tags, DOCDGM for <diagram> tags, and DOCTXT for direct LaTeX text (no tag).
 * - DOCTXT expressions printing is trivial.
 * - DOCDGM expressions printing calls 'printDocDgm' to generate SVG files and print LaTeX "figure" code.
 * - DOCEQN expressions printing calls 'printDocEqn' after an important preparing work 
 *   has been done by 'prepareDocEqns'.
 *
 * @param[in]	projname		Basename of the new doc directory ("*-math").
 * @param[in]	docVector		Contains all <mdoc> parsed content (as boxes).
 * @param[in]	faustversion	The current version of this Faust compiler.
 * @param[out]	docout			The output file to print into.
 **/
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;
	
	/** Equations need to be prepared (named and compiled) before printing. */
	vector<Lateq*>  docCompiledEqnsVector;
	prepareDocEqns( docVector, docCompiledEqnsVector ); ///< Quite a lot of stuff there.
	vector<Lateq*>::iterator eqn_it = docCompiledEqnsVector.begin();
	
	int dgmIndex = 1;			///< For diagram directories numbering.

	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++;
	}
	
	/** First level printing loop, on docVector. */
	for (doc=docVector.begin(); doc<docVector.end(); doc++, code++) {
		
		Tree L = reverse(*doc);
		//cerr << "Entering into <mdoc> parsing..." << endl; 
		
		/** Second level printing loop, on each <mdoc>. */
		while (isList(L)) {
			Tree expr;
			if ( isDocEqn(hd(L), expr) ) { ///< After equations are well prepared and named.
				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
 *****************************************************************************/

/**
 * @brief Caller function for all steps of doc equations preparation.
 *  
 * Note : many of the functions called put their result into their last argument
 * in a "source / destination" manner, 
 * the "destination" being declared before the function call. 
 *
 * @param[in]	docBoxes				The <mdoc> boxes to collect and prepare.
 * @param[out]	docCompiledEqnsVector	The place to store compiled equations.
 */
static void prepareDocEqns(const vector<Tree>& docBoxes, vector<Lateq*>& docCompiledEqnsVector)
{	
	vector<Tree>	eqBoxes;		collectDocEqns( docBoxes, eqBoxes );		///< step 0. Feed a vector.
	
	if(! eqBoxes.empty() ) {
		vector<Tree>	evalEqBoxes;	mapEvalDocEqn( eqBoxes, gExpandedDefList, evalEqBoxes );	///< step 1. Evaluate boxes.
		vector<string>	eqNames;		mapGetEqName( evalEqBoxes, eqNames );		///< step 2. Get boxes name.
		vector<string>	eqNicknames;	calcEqnsNicknames( eqNames, eqNicknames );	///< step 3. Calculate nicknames.
		
		vector<int>		eqInputs;
		vector<int>		eqOutputs;
		vector<Tree>	eqSigs;			mapPrepareEqSig( evalEqBoxes, eqInputs, eqOutputs, eqSigs );	///< step 4&5. Propagate and prepare signals.
		mapSetSigNickname( eqNicknames, eqInputs, eqSigs );									///< step 6. Set signals nicknames.
		Tree			superEqList;	collectEqSigs( eqSigs, superEqList );		///< step 7. Collect all signals in a superlist.
		
		DocCompiler* DC = new DocCompiler(0, 0);
		annotateSuperList( DC, superEqList );										///< step 8. Annotate superEqList.
		//calcAndSetLtqNames( superEqList );										///< step 9. (directly in 10.)
		mapCompileDocEqnSigs( eqSigs, eqInputs, eqOutputs, DC, docCompiledEqnsVector );		///< step 10. Compile every signal.
	}
}


/**
 * #0. Collect every <equation> found in all <mdoc> faust comments.
 *
 * @param[in]	docBoxes	The <mdoc> boxes to filter.
 * @param[out]	eqBoxes		The place to store only <equation> boxes.
 */
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;
}


/**
 * #1. Evaluate every doc <equation> (evaluation replaces abstractions by symbolic boxes).
 *
 * @param[in]	eqBoxes		The boxes to evaluate.
 * @param[in]	env			The environment for the evaluation.
 * @param[out]	evalEqBoxes	The place to store evaluated equations boxes.
 */
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;
}


/**
 * #2. Get name if exists, else create one, and store it.
 *
 * @param[in]	evalEqBoxes	Evaluated box trees, eventually containing an equation name.
 * @param[out]	eqNames		The place to store equations names.
 */
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;
}


/**
 * #3. Calculate a nickname for each equation and store it.
 *
 * @param[in]	eqNames		Equations names to parse.
 * @param[out]	eqNicknames	The place to store calculated nicknames.
 *
 * @todo Should check unicity : check whether several names share the same initial,
 * or else capture consonants for example.
 */
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);
		/** Check duplicates */
//		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;
}


/**
 * #4&5. Propagate and prepare every doc <equation>.
 *
 * Call boxPropagateSig, deBruijn2Sym, simplify, and privatise.
 *
 * @param[in]	evalEqBoxes		Equations boxes to propagate as signals.
 * @param[out]	eqSigs			The place to store prepared signals.
 */
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);   ///< Convert debruijn recursion into symbolic recursion
		Tree lsig3 = simplify(lsig2);		///< Simplify by executing every computable operation
        //Tree lsig4 = privatise(lsig3);		///< Un-share tables with multiple writers
        Tree lsig4 = docTableConvertion(lsig3);		///< convert regular tables into special doctables
                                                    ///< (regular tables are difficult to translate to equations)

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


/**
 * #6. Set signals nicknames.
 *
 * Do nothing for the moment !
 * @param[in]	eqNicknames		Contains previously calculated nicknames.
 * @param[out]	eqSigs			The signals to tag with a NICKNAMEPROPERTY.
 */
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;
}


/**
 * #7. Collect each prepared list of signals to construct a super list.
 *
 * @param[in]	eqSigs			Contains well-prepared and nicknamed signals.
 * @param[out]	superEqList		The root where to 'cons' signals all together.
 */
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;
}


/**
 * #8. Annotate superEqList (to find candidate signals to be named later).
 *
 * @param[in]	DC			The signals compiler.
 * @param[out]	superEqList	The super equations signal tree to annotate. 
 */
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)
//{
//	
//}


/**
 * #10. Name and compile prepared doc <equation> signals.
 *
 * @param[in]	eqSigs					Contains well-prepared and nicknamed signals.
 * @param[in]	DC						The signals compiler.
 * @param[out]	docCompiledEqnsVector	The place to store each compiled Lateq* object.
 */
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
 *****************************************************************************/


/**
 * Calculate an appropriate nickname for equations,
 * from previous names.
 *
 * @param	The string to parse.
 * @return	Essentially returns the initial character, 
 * except "Y" for "process", and "Z" for unnamed equations.
 */
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;
}


/**
 * Just get the number of inputs and the number of outputs of a box.
 *
 * @param[in]	t			The box tree to get inputs and outputs from.
 * @param[out]	numInputs	The place to store the number of inputs.
 * @param[out]	numOutputs	The place to store the number of outputs.
 */
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;
}


/**
 * Print doc equations, following the Lateq::println method.
 *
 * @param[in]	ltq		The object containing compiled LaTeX code of equations.
 * @param[out]	docout	The output file to print into.
 */
static void printDocEqn(Lateq* ltq, ostream& docout) 
{
	ltq->println(docout);
	//cerr << "Documentator : printDocEqn : "; ltq->println(cerr); cerr << endl;
}


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

/**
 * @brief Doc diagrams handling.
 * 
 * Three steps :
 * 1. evaluate expression
 * 2. call svg drawing in the appropriate directory
 * 3. print latex figure code with the appropriate directory reference
 *
 * @param[in]	expr		Parsed input expression, as boxes tree.
 * @param[in]	svgTopDir	Basename of the new doc directory ("*-math/svg").
 * @param[out]	docout		The output file to print into.
 */
static void printDocDgm(const Tree expr, const char* svgTopDir, ostream& docout, int i)
{
	/** 1. Evaluate expression. */
	Tree docdgm = evaldocexpr(expr, gExpandedDefList);
	if (gErrorCount > 0) {
		cerr << "Total of " << gErrorCount << " errors during evaluation of : diagram docdgm = " << boxpp(docdgm) << ";\n";
		exit(1);
	}
	
	/**
	 * 2. Draw the diagram after its evaluation, in SVG.
	 * Warning : pdflatex can't directly include SVG files !
	 */
	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" );
	
	/** 3. Print LaTeX figure code. */
	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;
	
	/** 4. Warn about naming interferences (in the notice). */
	gDocNoticeFlagMap["nameconflicts"] = true;
	gDocNoticeFlagMap["svgdir"] = true;
}



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


/**
 * Slice faust code between "mdoc" sections.
 *
 * @param[in]	faustfile	Name of the input faust file to parse.
 * @param[in]	codeSlices	The place to store code "slices".
 */
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)) { /** Caution: we suppose there's only one <mdoc> tag per line! */
			size_t foundopendoc  = s.find("<mdoc>");
			
			if (foundopendoc != string::npos) { 
				if (isInsideDoc == false) { /** A change has come. ;) */
					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;
}
			

/**
 * Print faust code inside a listing environment.
 * 
 * @param[in]	code		Faust code as a string (may contain '\n' characters).
 * @param[out]	docout		The output file to print into.
 */
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;
	}
}


/**
 * Test whether a file does begin with some faust code or not.
 *
 * @param[in]	faustfile	Name of the input faust file to parse.
 */
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 -------------------------


/**
 * Create a new directory in the current one.
 */
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);
}


/**
 * Create a new directory in the current one, 
 * then 'cd' into this new directory.
 * 
 * @remark
 * The current directory is saved to be later restaured.
 */
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);
}


/**
 * Switch back to the previously stored current directory
 */
static int cholddir ()
{
	if (chdir(gCurrentDir.c_str()) == 0) {
		return 0;
	} else {
		perror("cholddir");
		exit(errno);
	}
}


/**
 * Get current directory and store it in gCurrentDir.
 */
static void getCurrentDir ()
{
	char	buffer[FAUST_PATH_MAX];
    gCurrentDir = getcwd (buffer, FAUST_PATH_MAX);
}


/**
 * Open architecture file.
 */
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;
}


/**
 * Transform the definition name property of tree <t> into a
 * legal file name.  The resulting file name is stored in
 * <dst> a table of at least <n> chars. Returns the <dst> pointer
 * for convenience.
 */
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;
}

/**
 * Simply concat a string with a number in a "%03d" format.
 * The number has MAXIDCHARS characters. 
 **/
static string calcNumberedName(const char* base, int i)
{
	char nb[MAXIDCHARS+1];
	sprintf(nb, "%03d", i);
	return subst("$0$1", base, nb);
}

/**
 * Remove the leading and trailing double quotes of a string
 * (but not those in the middle of the string)
 */
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 "";
    }
}


/** 
 * Copy all Faust source files into an 'src' subdirectory.
 *
 * @param[in]	projname		Basename of the new doc directory ("*-math").
 * @param[in]	pathnames		The paths list of the source files to copy.
 */
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;
}