%PRHELP2HTML Construct HTML file from help part of PRTools routine
%
% S = PRHELP2HTML(COMMAND,RECREATE,HTMLDIR)
% S = PRHELP2HTML(TOOLBOX,RECREATE,HTMLDIR)
%
% INPUT
% COMMAND String with PRTools command, default: all prtools m-files
% TOOLBOX Name of the toolbox to be handled, default PRTOOLS.
% Toolbox should be in the bath in in this call the last
% character should be a '/'.
% RECREATE 0/1 flag indicating whether non-existing references
% in the SEE ALSO section should be created as well
% HTMLDIR String with desired directory in which the HTML
% file should be stored
%
% OUTPUT
% S HTML code written to file, empty in case of error
%
% DESCRIPTION
% This command takes the help part of a PRTools command and creates a HTML
% file in the desired sub-directory. In case it is not given, a
% sub-directory is used with the same name as the (sub-)directory of
% COMMAND.
%
% In creating HTML code the following formatting rules apply:
% - NAME is used for the title and the first heading
% - There are (slightly) different rules for standard sections of the
% PRTools help:
% INPUT, OUTPUT, DESCRIPTION, REFERENCES, EXAMPLES, SEE ALSO
% - New sections are detected by their name in capitals starting at
% position 1 or 2 of the line.
% - The first word of the first line is skipped (assuming it is identical
% to NAME). The remaining part of the line is used as heading.
% - The next block of lines is assumed to be ways to call the command and
% is printed as code (Courier size 3) on separate lines.
% - The INPUT and OUTPUT sections are printed as two-column tables. The
% first column is printed as code.
% - Multiple spaces in the source are used to define column separators.
% ACCIDENTAL MULTIPLE SPACES CAUSE ERRORS!!!!
% - Blocks of lines in the following DESCRIPTION section are formatted as
% separate paragraphs.
% - Lines starting with ' - ' will start a dotted list.
% - Lines following an empty line and starting with multiple spaces are
% assumed to be code and printed as Courier_3.
% - Lines containing sets of multiple spaces after the first words start a
% two-column table. Consecutive lines starting with multiple spaces are
% placed in the second column.
% - Lines ending with a ':' force a break (
) in the paragraph.
% - An attempt is made to detect code in text (using the Matlab convention
% of upper case characters only). This is printed as Courier 2.
% - Literature references in the REFERENCE section generater a break if the
% line starts with a number.
% - Code in the EXAMPLE section is printed as it is using Courier_2.
% - Users are advised to neglect here the Matlab convention of capitals in
% order to facilitate direct copying and execution.
% - References are created for command names in the EXAMPLE section that
% are preceded by 'See', e.g. 'See PREX_PLOTC'.
% - References are created for all PRTools commands in the SEE ALSO
% section.
% BEFORE YOU START TO DEBUG, READ THIS
% This routine was original intended to work on the prtools dir only.
% Later it was somewhat changed in order to handle files in prdatasets,
% prdatafiles and possibly distools and dd_tools as well. Only for
% prtools the subdir structure (with the @dataset, @datafile, @mapping
% sub dirs) is recognized, and only if the first parameter, COMMAND, is
% empty.
%
% The Contents files have a special layout. It is handled by prcontent2html
% in case of PRTools, but for other toolboxes it most likely doesn't work.
%
% The formatting rules of the PRTools help are strict. Don't try to relax
% them in the below code, but change the help-text if you are not satisfied
% with the result. Especially avoid ' ' (double spaces) where they are not
% needed as the conversion jumps into a table-mode as soon as they are
% encountered.
%
% Bob Duin, April 2011
function out = prhelp2html(name,recreate,htmldir)
if nargin < 3, htmldir = cd; end
if nargin < 2 | isempty(recreate), recreate = 0; end
if nargin < 1 | isempty(name) % default is prtools
dirs = {'ldc','dataset','datafile','mapping'};
run_all_files(mfilename,dirs,htmldir);
s = prcontent2html('prtools',[],htmldir);
if nargout > 0
out = s;
end
return;
else
if strcmp(name(end),'/') & exist(name(1:end-1),'dir') == 7
name = name(1:end-1);
dirs = {fullfile(name,'Contents.m')};
run_all_files(mfilename,dirs,htmldir);
s = prcontent2html(name,[],htmldir); % does not work usually
if nargout > 0
out = s;
end
return
end
end
file = which(name);
if isempty(file)
disp([' -----> ' name ' not found']);
out = [];
return
end
%[pp,name] = fileparts(file);
if isempty(htmldir)
[xx,htmldir] = fileparts(fileparts(file));
end
% if isempty(strmatch(subdir,char('prtools','@dataset','@datafile','@mapping'),'exact'))
% % disp([name ' Not PRTools'])
% out = [];
% return
% end
disp(file)
t = gethf(file); % help part
t = strrep(t,char([10 13]),char(10));
t = strrep(t,char([13 10]),char(10));
t = strrep(t,char(13),char(10));
t = strrep(t,char(9),char([32 32]));
n = length(strfind(t,10));
s = ['' content_manual '
' upper(name) '
' newline]; title = listn(t,1); [qq,title] = strtok(title); % get rid of first word, probably name s = [s '' newline]; liston = false; previous_empty = false; coding = false; cellopen = false; tabstate = false; if strfind(lower(title),'info') state = 'text'; else state = 'start'; end nextlinespace = htmlspace; for j=2:n % do for all lines newlinespace = nextlinespace; nextlinespace = htmlspace; r = listn(t,j); u = cleanstr(r); % if strfind(r,'supplied') % disp(r) % end [tok,posttok] = strtok(u); single = isempty(strtok(posttok)); emptyline = isempty(tok); if length(r) < 2, startspace = false; tabstartspace = false; else startspace = strcmp(r(1:2),' '); if length(r) < 4 || ~tabstate tabstartspace = false; else tabstartspace = strcmp(r(1:4),' '); colpos1 = find(r ~= ' ',1,'first'); end if tabstartspace startspace = false; end end uppertoken = isupper(tok); upperline = isupper(u); functioncall = ~isempty(strfind(lower(r),name)); input = strcmp(tok,'INPUT'); output = strcmp(tok,'OUTPUT'); listline = strcmp(tok,'-'); description = strcmp(tok,'DESCRIPTION'); example = strcmp(tok,'EXAMPLE') | strcmp(tok,'EXAMPLES'); reference = strcmp(tok,'REFERENCE') | strcmp(tok,'REFERENCES'); seealso = strcmpi(tok,'SEE') & strcmpi(strtok(posttok),'ALSO'); inputstate = strcmp(state,'input'); outputstate = strcmp(state,'output'); tabstate = strcmp(state,'tab'); startstate = strcmp(state,'start'); commandstate = strcmp(state,'command'); textstate = strcmp(state,'text'); examplestate = strcmp(state,'examp'); seealsostate = strcmp(state,'seealso'); refstate = strcmp(state,'reference'); iotabstate = inputstate | outputstate; ntabs = regexp(strtrim(r),' *','start'); tab = length(ntabs>1) | (length(ntabs)==1 && ntabs(1)>1); if seealso % get rid of also [qq,posttok] = strtok(posttok); single = isempty(strtok(posttok)); end if previous_empty && ~startspace && ~tabstartspace && ~tab && tabstate if cellopen s = closecell(s); cellopen = false; end s = endtable(s); s = [s '
' newline '']; state = oldstate; end if emptyline % start new paragraph if liston, s = [s '']; liston = false; end if iotabstate s = endtable(s); state = 'text'; else s = [s '
' newline '']; %#ok
' newline];
state = 'command';
elseif input && single % input
if commandstate || textstate % start table
s = [s '
' newline]; % new paragraph s = [s '
Input | ']; state = 'input'; end elseif output && single if inputstate s = endtable(s); % end inputtable end if inputstate || commandstate || textstate % start table s = [s '
Output | ']; end state = 'output'; elseif iotabstate % input/output table if uppertoken % next input/output parameter s = [s '|||
' makecode(tok,1) ' | ']; [f0,f1] = regexp(posttok,'^ *[:-] *'); if ~isempty(f0) posttok = posttok(f1+1:end); end s = [s '' findmakecode(posttok)];
else % continuation of description
s = [s htmlspace findmakecode(u)];
end
elseif (tab || tabstate) ...
&& ~examplestate && ~startspace && ~tabstartspace % arbitrary table
if ~tabstate % start table
if liston, s = [s '']; liston = false; end
s = [s ' ']; % new paragraph s = [s '
|
contents' ... ' | '... ' |