%PRHELP2HTML Construct HTML file from help part of PRTools routine
%
% S = PRHELP2HTML(COMMAND,RECREATE,SUBDIR)
%
% INPUT
% COMMAND String with PRTools command, default: all prtools m-files
% RECREATE 0/1 flag indicating whether non-existing references
% in the SEE ALSO section should be created as well
% SUBDIR String with desired sub-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.
function out = prhelp2html(name,recreate,subdir)
if nargin < 3, subdir = []; end
if nargin < 2 || isempty(recreate), recreate = 0; end
if nargin < 1
run_all_files(mfilename);
s = prcontent2html('prtools');
if nargout > 0
out = s;
end
return;
end
file = which(name);
if isempty(file)
disp([' -----> ' name ' not found']);
out = [];
return
end
%[pp,name] = fileparts(file);
if isempty(subdir)
[xx,subdir] = 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' ... ' | '... ' |