m2html.m

M2HTML by itself generates an HTML documentation of Matlab M-files in the current directory.

	if options.verbose
		fprintf('Saving MAT file %s...\n',matfilesave);
	end
	save(fullfile(options.htmlDir,matfilesave), ...
		'mfiles', 'names', 'mdirs', 'name', 'mdir', 'options', ...
		'hrefs', 'synopsis', 'h1line', 'subroutine', 'todo', 'ismex');
end

%-------------------------------------------------------------------------------
%- Setup the output directories
%-------------------------------------------------------------------------------
for i=1:length(mdir)
	if exist(fullfile(options.htmlDir,mdir{i})) ~= 7
		ldir = splitpath(mdir{i});
		for j=1:length(ldir)
			if exist(fullfile(options.htmlDir,ldir{1:j})) ~= 7
				%- Create the output directory
				if options.verbose
					fprintf('Creating directory %s...\n',...
							fullfile(options.htmlDir,ldir{1:j}));
				end
				if j == 1
					[status, msg] = mkdir(options.htmlDir,ldir{1});
				else
					[status, msg] = mkdir(options.htmlDir,fullfile(ldir{1:j}));
				end
				error(msg);
			end
		end
	end
end

%-------------------------------------------------------------------------------
%- Write the master index file
%-------------------------------------------------------------------------------
tpl_master = 'master.tpl';
tpl_master_identifier_nbyline = 4;

%- Create the HTML template
tpl = template(options.template,'remove');
tpl = set(tpl,'file','TPL_MASTER',tpl_master);
tpl = set(tpl,'block','TPL_MASTER','rowdir','rowdirs');
tpl = set(tpl,'block','TPL_MASTER','idrow','idrows');
tpl = set(tpl,'block','idrow','idcolumn','idcolumns');

%- Open for writing the HTML master index file
curfile = fullfile(options.htmlDir,[options.indexFile options.extension]);
if options.verbose
	fprintf('Creating HTML file %s...\n',curfile);
end
fid = openfile(curfile,'w');

%- Set some template variables
tpl = set(tpl,'var','DATE',[datestr(now,8) ' ' datestr(now,1) ' ' ...
							datestr(now,13)]);
tpl = set(tpl,'var','MASTERPATH',       './');
tpl = set(tpl,'var','DIRS',    sprintf('%s ',mdir{:}));

%- Print list of unique directories
for i=1:length(mdir)
	tpl = set(tpl,'var','L_DIR',...
			  fullurl(mdir{i},[options.indexFile options.extension]));
	tpl = set(tpl,'var','DIR',mdir{i});
	tpl = parse(tpl,'rowdirs','rowdir',1);
end

%- Print full list of M-files (sorted by column)
[sortnames, ind] = sort(names);
m_mod = mod(length(sortnames), tpl_master_identifier_nbyline);
ind = [ind zeros(1,tpl_master_identifier_nbyline-m_mod)];
m_floor = floor(length(ind) / tpl_master_identifier_nbyline);
ind = reshape(ind,m_floor,tpl_master_identifier_nbyline)';

for i=1:prod(size(ind))
	if ind(i)
		tpl = set(tpl,'var','L_IDNAME',...
			fullurl(mdirs{ind(i)},[names{ind(i)} options.extension]));
		tpl = set(tpl,'var','T_IDNAME',mdirs{ind(i)});
		tpl = set(tpl,'var','IDNAME',names{ind(i)});
		tpl = parse(tpl,'idcolumns','idcolumn',1);
	else
		tpl = set(tpl,'var','L_IDNAME','');
		tpl = set(tpl,'var','T_IDNAME','');
		tpl = set(tpl,'var','IDNAME','');
		tpl = parse(tpl,'idcolumns','idcolumn',1);
	end
	if mod(i,tpl_master_identifier_nbyline) == 0
		tpl = parse(tpl,'idrows','idrow',1);
		tpl = set(tpl,'var','idcolumns','');
	end
end

%- Print the template in the HTML file
tpl = parse(tpl,'OUT','TPL_MASTER');
fprintf(fid,'%s',get(tpl,'OUT'));
fclose(fid);

%-------------------------------------------------------------------------------
%- Copy template files (CSS, images, ...)
%-------------------------------------------------------------------------------
% Get list of files
d = dir(options.template);
d = {d(~[d.isdir]).name};
% Copy files
for i=1:length(d)
	[p, n, ext] = fileparts(d{i});
	if ~strcmp(ext,'.tpl') % do not copy .tpl files
		if ~(exist(fullfile(options.htmlDir,d{i})))
			if options.verbose
				fprintf('Copying template file %s...\n',d{i});
			end
			[status, errmsg] = copyfile(fullfile(options.template,d{i}),...
										options.htmlDir);
			error(errmsg);
		end
	end
end

%-------------------------------------------------------------------------------
%- Write an index for each output directory
%-------------------------------------------------------------------------------
tpl_mdir = 'mdir.tpl';
tpl_mdir_link = '<a href="%s">%s</a>';
dotbase = 'graph';

%- Create the HTML template
tpl = template(options.template,'remove');
tpl = set(tpl,'file','TPL_MDIR',tpl_mdir);
tpl = set(tpl,'block','TPL_MDIR','row-m','rows-m');
tpl = set(tpl,'block','row-m','mexfile','mex');
tpl = set(tpl,'block','TPL_MDIR','othermatlab','other');
tpl = set(tpl,'block','othermatlab','row-other','rows-other');
tpl = set(tpl,'block','TPL_MDIR','subfolder','subfold');
tpl = set(tpl,'block','subfolder','subdir','subdirs');
tpl = set(tpl,'block','TPL_MDIR','todolist','todolists');
tpl = set(tpl,'block','TPL_MDIR','graph','graphs');
tpl = set(tpl,'var','DATE',[datestr(now,8) ' ' datestr(now,1) ' ' ...
							datestr(now,13)]);

for i=1:length(mdir)
	%- Open for writing each output directory index file
	curfile = fullfile(options.htmlDir,mdir{i},...
					   [options.indexFile options.extension]);
	if options.verbose
		fprintf('Creating HTML file %s...\n',curfile);
	end
	fid = openfile(curfile,'w');

	%- Set template fields
	tpl = set(tpl,'var','INDEX',     [options.indexFile options.extension]);
	tpl = set(tpl,'var','MASTERPATH',backtomaster(mdir{i}));
	tpl = set(tpl,'var','MDIR',      mdir{i});
	
	%- Display Matlab m-files, their H1 line and their Mex status
	tpl = set(tpl,'var','rows-m','');
	for j=1:length(mdirs)
		if strcmp(mdirs{j},mdir{i})
			tpl = set(tpl,'var','L_NAME', [names{j} options.extension]);
			tpl = set(tpl,'var','NAME',   names{j});
			tpl = set(tpl,'var','H1LINE', h1line{j});
			if any(ismex(j,:))
				tpl = parse(tpl,'mex','mexfile');
			else
				tpl = set(tpl,'var','mex','');
			end
			tpl = parse(tpl,'rows-m','row-m',1);
		end
	end
	
	%- Display other Matlab-specific files (.mat,.mdl,.p)
	tpl = set(tpl,'var','other','');
	tpl = set(tpl,'var','rows-other','');
	w = what(mdir{i}); w = w(1);
	w = {w.mat{:} w.mdl{:} w.p{:}};
	for j=1:length(w)
		tpl = set(tpl,'var','OTHERFILE',w{j});
		tpl = parse(tpl,'rows-other','row-other',1);
	end
	if ~isempty(w)
		tpl = parse(tpl,'other','othermatlab');
	end
	
	%- Display subsequent directories and classes
	tpl = set(tpl,'var','subdirs','');
	tpl = set(tpl,'var','subfold','');
	d = dir(mdir{i});
	d = {d([d.isdir]).name};
	d = {d{~ismember(d,{'.' '..'})}};
	for j=1:length(d)
		if ismember(fullfile(mdir{i},d{j}),mdir)
			tpl = set(tpl,'var','SUBDIRECTORY',...
				sprintf(tpl_mdir_link,...
				fullurl(d{j},[options.indexFile options.extension]),d{j}));
		else
			tpl = set(tpl,'var','SUBDIRECTORY',d{j});
		end
		tpl = parse(tpl,'subdirs','subdir',1);
	end
	if ~isempty(d)
		tpl = parse(tpl,'subfold','subfolder');
	end
	
	%- Link to the TODO list if necessary
	tpl = set(tpl,'var','todolists','');
	if options.todo
		if ~isempty(intersect(find(strcmp(mdir{i},mdirs)),todo.mfile))
			tpl = set(tpl,'var','LTODOLIST',['todo' options.extension]);
			tpl = parse(tpl,'todolists','todolist',1);
		end
	end
	
	%- Link to the dependency graph if necessary
	tpl = set(tpl,'var','graphs','');
	if options.graph
		tpl = set(tpl,'var','LGRAPH',[dotbase options.extension]);
		tpl = parse(tpl,'graphs','graph',1);
	end
	
	%- Print the template in the HTML file
	tpl = parse(tpl,'OUT','TPL_MDIR');
	fprintf(fid,'%s',get(tpl,'OUT'));
	fclose(fid);
end

%-------------------------------------------------------------------------------
%- Write a TODO list file for each output directory, if necessary
%-------------------------------------------------------------------------------
tpl_todo = 'todo.tpl';

if options.todo
	%- Create the HTML template
	tpl = template(options.template,'remove');
	tpl = set(tpl,'file','TPL_TODO',tpl_todo);
	tpl = set(tpl,'block','TPL_TODO','filelist','filelists');
	tpl = set(tpl,'block','filelist','row','rows');
	tpl = set(tpl,'var','DATE',[datestr(now,8) ' ' datestr(now,1) ' ' ...
								datestr(now,13)]);

	for i=1:length(mdir)
		mfilestodo = intersect(find(strcmp(mdir{i},mdirs)),todo.mfile);
		if ~isempty(mfilestodo)
			%- Open for writing each TODO list file
			curfile = fullfile(options.htmlDir,mdir{i},...
							   ['todo' options.extension]);
			if options.verbose
				fprintf('Creating HTML file %s...\n',curfile);
			end
			fid = openfile(curfile,'w');
			
			%- Set template fields
			tpl = set(tpl,'var','INDEX',[options.indexFile options.extension]);
			tpl = set(tpl,'var','MASTERPATH', backtomaster(mdir{i}));
			tpl = set(tpl,'var','MDIR',       mdir{i});
			tpl = set(tpl,'var','filelists',  '');
	
			for k=1:length(mfilestodo)
				tpl = set(tpl,'var','MFILE',names{mfilestodo(k)});
				tpl = set(tpl,'var','rows','');
				nbtodo = find(todo.mfile == mfilestodo(k));
				for l=1:length(nbtodo)
					tpl = set(tpl,'var','L_NBLINE',...
						[names{mfilestodo(k)} ...
							options.extension ...
							'#l' num2str(todo.line(nbtodo(l)))]);
					tpl = set(tpl,'var','NBLINE',num2str(todo.line(nbtodo(l))));
					tpl = set(tpl,'var','COMMENT',todo.comment{nbtodo(l)});
					tpl = parse(tpl,'rows','row',1);
				end
				tpl = parse(tpl,'filelists','filelist',1);
			end
	
			%- Print the template in the HTML file
			tpl = parse(tpl,'OUT','TPL_TODO');
			fprintf(fid,'%s',get(tpl,'OUT'));
			fclose(fid);
		end
	end
end

%-------------------------------------------------------------------------------
%- Create a dependency graph for each output directory, if requested
%-------------------------------------------------------------------------------
tpl_graph = 'graph.tpl';
dot_exec  = 'dot';
%dotbase defined earlier

if options.graph
	%- Create the HTML template
	tpl = template(options.template,'remove');
	tpl = set(tpl,'file','TPL_GRAPH',tpl_graph);
	tpl = set(tpl,'var','DATE',[datestr(now,8) ' ' datestr(now,1) ' ' ...
								datestr(now,13)]);
	
	for i=1:length(mdir)
		mdotfile = fullfile(options.htmlDir,mdir{i},[dotbase '.dot']);
		if options.verbose
			fprintf('Creating dependency graph %s...',mdotfile);
		end
		ind = find(strcmp(mdirs,mdir{i}));
		href1 = zeros(length(ind),length(hrefs));
		for j=1:length(hrefs), href1(:,j) = hrefs(ind,j); end
		href2 = zeros(length(ind));
		for j=1:length(ind), href2(j,:) = href1(j,ind); end
		mdot({href2,{names{ind}},options,{mfiles{ind}}}, mdotfile);
		try
			%- see <http://www.research.att.com/sw/tools/graphviz/>
			%  <dot> must be in your system path:
			%    - on Linux, modify $PATH accordingly
			%    - on Windows, modify the environment variable PATH like this:
			
% From the Start-menu open the Control Panel, open 'System' and activate the
% panel named 'Extended'. Open the dialog 'Environment Variables'. Select the 
% variable 'Path' of the panel 'System Variables' and press the 'Modify button. 
% Then add 'C:\GraphViz\bin' to your current definition of PATH, assuming that 
% you did install GraphViz into directory 'C:\GraphViz'. Note that the various 
% paths in PATH have to be separated by a colon. Her is an example how the final
% Path should look like:  ...;C:\WINNT\System32;...;C:\GraphViz\bin
% (Note that this should have been done automatically during GraphViz installation)

			eval(['!' dot_exec ' -Tcmap -Tpng ' mdotfile ...
				' -o ' fullfile(options.htmlDir,mdir{i},[dotbase '.map']) ... 
				' -o ' fullfile(options.htmlDir,mdir{i},[dotbase '.png'])])
			% use '!' rather than 'system' for backward compability
		catch
			fprintf('failed.');
		end
		fprintf('\n');
		fid = openfile(fullfile(options.htmlDir,mdir{i},...
			[dotbase options.extension]),'w');
		tpl = set(tpl,'var','INDEX',[options.indexFile options.extension]);
		tpl = set(tpl,'var','MASTERPATH', backtomaster(mdir{i}));
		tpl = set(tpl,'var','MDIR',       mdir{i});
		tpl = set(tpl,'var','GRAPH_IMG',  [dotbase '.png']);
		fmap = openfile(fullfile(options.htmlDir,mdir{i},[dotbase '.map']),'r');
		tpl = set(tpl,'var','GRAPH_MAP',  fscanf(fmap,'%c'));
		fclose(fmap);
		tpl = parse(tpl,'OUT','TPL_GRAPH');
		fprintf(fid,'%s', get(tpl,'OUT'));
		fclose(fid);
	end
end

%-------------------------------------------------------------------------------
%- Write an HTML file for each M-file
%-------------------------------------------------------------------------------
%- List of Matlab keywords (output from iskeyword)
matlabKeywords = {'break', 'case', 'catch', 'continue', 'elseif', 'else', ...
				  'end', 'for', 'function', 'global', 'if', 'otherwise', ...
				  'persistent', 'return', 'switch', 'try', 'while'};
                  %'keyboard', 'pause', 'eps', 'NaN', 'Inf'

tpl_mfile = 'mfile.tpl';

tpl_mfile_code     = '<a href="%s" class="code" title="%s">%s</a>';
tpl_mfile_keyword  = '<span class="keyword">%s</span>';
tpl_mfile_comment  = '<span class="comment">%s</span>';
tpl_mfile_string   = '<span class="string">%s</span>';
tpl_mfile_aname    = '<a name="%s" href="#_subfunctions" class="code">%s</a>';
tpl_mfile_line     = '%04d %s\n';

%- Delimiters used in strtok: some of them may be useless (% " .), removed '.'
strtok_delim = sprintf(' \t\n\r(){}[]<>+-*~!|\\@&/,:;="''%%');

%- Create the HTML template
tpl = template(options.template,'remove');
tpl = set(tpl,'file','TPL_MFILE',tpl_mfile);
tpl = set(tpl,'block','TPL_MFILE','pathline','pl');
tpl = set(tpl,'block','TPL_MFILE','mexfile','mex');
tpl = set(tpl,'block','TPL_MFILE','script','scriptfile');
tpl = set(tpl,'block','TPL_MFILE','crossrefcall','crossrefcalls');