m2html.m

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

tpl = set(tpl,'block','TPL_MFILE','crossrefcalled','crossrefcalleds');
tpl = set(tpl,'block','TPL_MFILE','subfunction','subf');
tpl = set(tpl,'block','subfunction','onesubfunction','onesubf');
tpl = set(tpl,'block','TPL_MFILE','source','thesource');
tpl = set(tpl,'var','DATE',[datestr(now,8) ' ' datestr(now,1) ' ' ...
							datestr(now,13)]);

for i=1:length(mdir)
	for j=1:length(mdirs)
		if strcmp(mdirs{j},mdir{i})
		
			curfile = fullfile(options.htmlDir,mdir{i},...
							   [names{j} options.extension]);

			%- Open for writing the HTML file
			if options.verbose
				fprintf('Creating HTML file %s...\n',curfile);
			end
			fid = openfile(curfile,'w');
			
			%- Open for reading the M-file
			fid2 = openfile(mfiles{j},'r');
			
			%- Set some template fields
			tpl = set(tpl,'var','INDEX', [options.indexFile options.extension]);
			tpl = set(tpl,'var','MASTERPATH',       backtomaster(mdir{i}));
			tpl = set(tpl,'var','MDIR',             mdirs{j});
			tpl = set(tpl,'var','NAME',             names{j});
			tpl = set(tpl,'var','H1LINE',           h1line{j});
			tpl = set(tpl,'var','scriptfile',       '');
			if isempty(synopsis{j})
				tpl = set(tpl,'var','SYNOPSIS',get(tpl,'var','script'));
			else
				tpl = set(tpl,'var','SYNOPSIS', synopsis{j});
			end
			s = splitpath(mdir{i});
			tpl = set(tpl,'var','pl','');
			for k=1:length(s)
				c = cell(1,k); for l=1:k, c{l} = filesep; end
				cpath = {s{1:k};c{:}}; cpath = [cpath{:}];
				if ~isempty(cpath), cpath = cpath(1:end-1); end
				if ismember(cpath,mdir)
					tpl = set(tpl,'var','LPATHDIR',[repmat('../',...
						1,length(s)-k) options.indexFile options.extension]);
				else
					tpl = set(tpl,'var','LPATHDIR','#');
				end
				tpl = set(tpl,'var','PATHDIR',s{k});
				tpl = parse(tpl,'pl','pathline',1);
			end
			
			%- Handle mex files
			tpl = set(tpl,'var','mex', '');
			samename = dir(fullfile(mdir{i},[names{j}	'.*']));
			samename = {samename.name};
			for k=1:length(samename)
				[dummy, dummy, ext] = fileparts(samename{k});
				switch ext
					case '.c'
						tpl = set(tpl,'var','MEXTYPE', 'c');
					case {'.cpp' '.c++' '.cxx' '.C'}
						tpl = set(tpl,'var','MEXTYPE', 'c++');
					case {'.for' '.f' '.FOR' '.F'}
						tpl = set(tpl,'var','MEXTYPE', 'fortran');
				end
			end
			[exts, platform] = mexexts;
			mexplatforms = sprintf('%s, ',platform{find(ismex(j,:))});
			if ~isempty(mexplatforms)
				tpl = set(tpl,'var','PLATFORMS', mexplatforms(1:end-2));
				tpl = parse(tpl,'mex','mexfile');
			end
			
			%- Set description template field
			descr = '';
			flagsynopcont = 0;
			flag_seealso  = 0;
			while 1
				tline = fgets(fid2);
				if ~ischar(tline), break, end
				tline = entity(fliplr(deblank(fliplr(tline))));
				%- Synopsis line
				if ~isempty(strmatch('function',tline))
					if ~isempty(strmatch('...',fliplr(deblank(tline))))
						flagsynopcont = 1;
					end
				%- H1 line and description
				elseif ~isempty(strmatch('%',tline))
					%- Hypertext links on the "See also" line
					ind = findstr(lower(tline),'see also');
					if ~isempty(ind) | flag_seealso
						%- "See also" only in files in the same directory
						indsamedir = find(strcmp(mdirs{j},mdirs));
						hrefnames = {names{indsamedir}};
						r = deblank(tline);
						flag_seealso = 1; %(r(end) == ',');
						tline = '';
						while 1
							[t,r,q] = strtok(r,sprintf(' \t\n\r.,;%%'));
							tline = [tline q];
							if isempty(t), break, end;
							ii = strcmpi(hrefnames,t);
							if any(ii)
								jj = find(ii);
								tline = [tline sprintf(tpl_mfile_code,...
									[hrefnames{jj(1)} options.extension],...
									synopsis{indsamedir(jj(1))},t)];
							else
								tline = [tline t];
							end
						end
						tline = sprintf('%s\n',tline);
					end
					descr = [descr tline(2:end)];
				elseif isempty(tline)
					if ~isempty(descr), break, end;
				else
					if flagsynopcont
						if isempty(strmatch('...',fliplr(deblank(tline))))
							flagsynopcont = 0;
						end
					else
						break;
					end
				end
			end
			tpl = set(tpl,'var','DESCRIPTION',...
				horztab(descr,options.tabs));
			
			%- Set cross-references template fields:
			%  Function called
			ind = find(hrefs(j,:) == 1);
			tpl = set(tpl,'var','crossrefcalls','');
			for k=1:length(ind)
				if strcmp(mdirs{j},mdirs{ind(k)})
					tpl = set(tpl,'var','L_NAME_CALL', ...
						[names{ind(k)} options.extension]);
				else
					tpl = set(tpl,'var','L_NAME_CALL', ...
							  fullurl(backtomaster(mdirs{j}), ...
							  		   mdirs{ind(k)}, ...
									   [names{ind(k)} options.extension]));
				end
				tpl = set(tpl,'var','SYNOP_CALL',   synopsis{ind(k)});
				tpl = set(tpl,'var','NAME_CALL',   names{ind(k)});
				tpl = set(tpl,'var','H1LINE_CALL', h1line{ind(k)});
				tpl = parse(tpl,'crossrefcalls','crossrefcall',1);
			end
			%  Callers
			ind = find(hrefs(:,j) == 1);
			tpl = set(tpl,'var','crossrefcalleds','');
			for k=1:length(ind)
				if strcmp(mdirs{j},mdirs{ind(k)})
					tpl = set(tpl,'var','L_NAME_CALLED', ...
						[names{ind(k)} options.extension]);
				else
					tpl = set(tpl,'var','L_NAME_CALLED', ...
						fullurl(backtomaster(mdirs{j}),...
							mdirs{ind(k)}, ...
							[names{ind(k)} options.extension]));
				end
				tpl = set(tpl,'var','SYNOP_CALLED',   synopsis{ind(k)});
				tpl = set(tpl,'var','NAME_CALLED',   names{ind(k)});
				tpl = set(tpl,'var','H1LINE_CALLED', h1line{ind(k)});
				tpl = parse(tpl,'crossrefcalleds','crossrefcalled',1);
			end
			
			%- Set subfunction template field
			tpl = set(tpl,'var',{'subf' 'onesubf'},{'' ''});
			if ~isempty(subroutine{j}) & options.source
				for k=1:length(subroutine{j})
					tpl = set(tpl, 'var', 'L_SUB', ['#_sub' num2str(k)]);
					tpl = set(tpl, 'var', 'SUB',   subroutine{j}{k});
					tpl = parse(tpl, 'onesubf', 'onesubfunction',1);
				end
				tpl = parse(tpl,'subf','subfunction');
			end
			subname = extractname(subroutine{j});
			
			%- Display source code with cross-references
			if options.source & ~strcmpi(names{j},'contents')
				fseek(fid2,0,-1);
				it = 1;
				matlabsource = '';
				nbsubroutine = 1;
				%- Get href function names of this file
				indhrefnames = find(hrefs(j,:) == 1);
				hrefnames = {names{indhrefnames}};
				%- Loop over lines
				while 1
					tline = fgetl(fid2);
					if ~ischar(tline), break, end
					myline = '';
					splitc = splitcode(entity(tline));
					for k=1:length(splitc)
						if isempty(splitc{k})
						elseif ~isempty(strmatch('function',splitc{k}))
							%- Subfunctions definition
							myline = [myline ...
								sprintf(tpl_mfile_aname,...
									['_sub' num2str(nbsubroutine-1)],splitc{k})];
							nbsubroutine = nbsubroutine + 1;
						elseif splitc{k}(1) == ''''
							myline = [myline ...
								sprintf(tpl_mfile_string,splitc{k})];
						elseif splitc{k}(1) == '%'
							myline = [myline ...
								sprintf(tpl_mfile_comment,deblank(splitc{k}))];
						elseif ~isempty(strmatch('...',splitc{k}))
							myline = [myline sprintf(tpl_mfile_keyword,'...')];
							if ~isempty(splitc{k}(4:end))
								myline = [myline ...
									sprintf(tpl_mfile_comment,splitc{k}(4:end))];
							end
						else
							%- Look for keywords
							r = splitc{k};
							while 1
								[t,r,q] = strtok(r,strtok_delim);
								myline = [myline q];
								if isempty(t), break, end;
								%- Highlight Matlab keywords &
								%  cross-references on known functions
								if options.syntaxHighlighting & ...
										any(strcmp(matlabKeywords,t))
									if strcmp('end',t)
										rr = fliplr(deblank(fliplr(r)));
										icomma = strmatch(',',rr);
										isemicolon = strmatch(';',rr);
										if ~(isempty(rr) | ~isempty([icomma isemicolon]))
											myline = [myline t];
										else
											myline = [myline sprintf(tpl_mfile_keyword,t)];
										end
									else
										myline = [myline sprintf(tpl_mfile_keyword,t)];
									end
								elseif any(strcmp(hrefnames,t))
									indt = indhrefnames(logical(strcmp(hrefnames,t)));
									flink = [t options.extension];
									ii = ismember({mdirs{indt}},mdirs{j});
									if ~any(ii)
										% take the first one...
										flink = fullurl(backtomaster(mdirs{j}),...
													 	 mdirs{indt(1)}, flink);
									else
										indt = indt(logical(ii));
									end
									myline = [myline sprintf(tpl_mfile_code,...
											  flink, synopsis{indt(1)}, t)];
								elseif any(strcmp(subname,t))
									ii = find(strcmp(subname,t));
									myline = [myline sprintf(tpl_mfile_code,...
										['#_sub' num2str(ii)],...
										['sub' subroutine{j}{ii}],t)];
								else
									myline = [myline t];
								end
							end
						end
					end
					matlabsource = [matlabsource sprintf(tpl_mfile_line,it,myline)];
					it = it + 1;
				end
				tpl = set(tpl,'var','SOURCECODE',...
						  horztab(matlabsource,options.tabs));
				tpl = parse(tpl,'thesource','source');
			else
				tpl = set(tpl,'var','thesource','');
			end
			tpl = parse(tpl,'OUT','TPL_MFILE');
			fprintf(fid,'%s',get(tpl,'OUT'));
			fclose(fid2);
			fclose(fid);
		end
	end
end

%===============================================================================
function mfiles = getmfiles(mdirs,mfiles,recursive)
	%- Extract M-files from a list of directories and/or M-files

	for i=1:length(mdirs)
		if exist(mdirs{i}) == 2 % M-file
			mfiles{end+1} = mdirs{i};
		elseif exist(mdirs{i}) == 7 % Directory
			w = what(mdirs{i});
			w = w(1); %- Sometimes an array is returned...
			for j=1:length(w.m)
				mfiles{end+1} = fullfile(mdirs{i},w.m{j});
			end
			if recursive
				d = dir(mdirs{i});
				d = {d([d.isdir]).name};
				d = {d{~ismember(d,{'.' '..'})}};
				for j=1:length(d)
					mfiles = getmfiles(cellstr(fullfile(mdirs{i},d{j})),...
									   mfiles,recursive);
				end
			end
		else
			fprintf('Warning: Unprocessed file %s.\n',mdirs{i});
		end
	end

%===============================================================================
function s = backtomaster(mdir)
	%- Provide filesystem path to go back to the root folder

	ldir = splitpath(mdir);
	s = repmat('../',1,length(ldir));
	
%===============================================================================
function ldir = splitpath(p)
	%- Split a filesystem path into parts using filesep as separator

	ldir = {};
	p = deblank(p);
	while 1
		[t,p] = strtok(p,filesep);
		if isempty(t), break; end
		if ~strcmp(t,'.')
			ldir{end+1} = t;
		end
	end
	if isempty(ldir)
		ldir{1} = '.'; % should be removed
	end

%===============================================================================
function name = extractname(synopsis)
	if ischar(synopsis), synopsis = {synopsis}; end
	name = cell(size(synopsis));
	for i=1:length(synopsis)
		ind = findstr(synopsis{i},'=');
		if isempty(ind)
			ind = findstr(synopsis{i},'function');
			s = synopsis{i}(ind(1)+8:end);
		else
			s = synopsis{i}(ind(1)+1:end);
		end
		name{i} = strtok(s,[9:13 32 '(']);
	end
	if length(name) == 1, name = name{1}; end

%===============================================================================
function f = fullurl(varargin)
	%- Build full url from parts (using '/' and not filesep)
	
	f = strrep(fullfile(varargin{:}),'\','/');

%===============================================================================
function str = entity(str)
	%- See http://www.w3.org/TR/html4/charset.html#h-5.3.2
	
	str = strrep(str,'&','&');
	str = strrep(str,'<','&lt;');
	str = strrep(str,'>','&gt;');
	str = strrep(str,'"','&quot;');
	
%===============================================================================
function str = horztab(str,n)
	%- For browsers, the horizontal tab character is the smallest non-zero 
	%- number of spaces necessary to line characters up along tab stops that are
	%- every 8 characters: behaviour obtained when n = 0.
	
	if n > 0
		str = strrep(str,sprintf('\t'),blanks(n));
	end