Automated way of creating PCODE for distribution purposes while retaining original function documentation

All,

I'm in a position where I would like to distribute a number of functions (i.e., M files) as P-code to a third party. Specifically, I would like to distribute the functionality as P files as I am for various reasons unable to disclose the actual implementation to the third party. However, as far as I can tell, the HELP function is unable to extract the function documentation from a P file so I will additionally need to distribute some kind of "documentation only" M files (akin to, for instance, the way The MathWorks documents the HISTC built-in function).

So far I've relied upon a number of scripts and regular expressions to extract the documentation block from each function out into a separate M file, build the pertinent P-code, and then overwriting (a copy of) the original M file with the documentation one for distribution purposes. This approach works reasonably well for many of my functions, but there is just too much variety in the way documentation occurs (or not) for the approach to be a reliable solution in the long run. If I am to proceed further along this path, I fear I may have to actually parse ever greater amounts of the MATLAB language myself and I am reluctant to take on that challenge.

I guess what I'm wondering is if any of you have experienced a similar situation and found a workable solution. If we were just talking about a handful of functions I'd be inclined to just do the work manually with a text editor and invoking the PCODE function from the command line, but the number of files often exceed 30-40 and I am really looking for a better, automated way of accomplishing this task.

I suppose accessing the built-in MATLAB parser (e.g., from Java-type code) could be used to create a robust solution but I do not know how to do this or even if it is possible at all.

Any and all suggestions are most welcome.

Sincerely,

Bård Skaflestad SINTEF ICT, Applied Mathematics

Answer 1

[Jan]

The HELP command extracts exactly the help section, if an output is used:

Str = help('mean');
CStr = regexp(Str, '\n', 'split');
fprintf('%s\n', CStr{:});

Because I need some extra comments in my files e.g. for version information, I'm using a different approach: I copy all lines from the first line, which starts with '%' until the next following line, which is not empty and does not start with a '%':

Str = fileread(MFileName);
CStr = regexp(Str, '\n', 'split');
CStr = deblank(CStr);
isComment = or(strncmp(CStr, '%', 1), ...
               cellfun('isempty', CStr));
iniIndex = find(isComment, 1, 'first');
isComment(1:iniIndex - 1) = true;
finIndex = find(~isComment, 1, 'first') - 1;

CommentBlock = sprintf('%s\n', CStr{iniIndex:finIndex})

[Bård Skaflestad]

Jan,

This is brilliant. Thank you so much. I was unaware of that property of HELP. Just goes to show that I really should be reading "help help". I also like your more targeted approach and I'm sure I can adapt it to my particular situation.

Thank you again!

Bård

[Jan]

@Bård: help(help(help('help')))

[Walter Roberson]

Also available via help(help('me'))

("Won't you please help, help me!"))

[Bård Skaflestad]

@Jan, @Walter

Wow, what can I say. I just knew about calling SPY with no parameters. And RESHAPE(..., -1, -1) in earlier releases. How do you discover these things?

[Jan]

@Bard: I've read the source of all toolbox functions to learn Matlab. "help('help')" creates the short message "me not found" etc. But if you catch the output "S = help('me')" you get the empty string. "help(help('me'))" is evaluated as "help('')" and replies the list of all help topics. So there is no concealed mechanism, but actually a sunset is not magic also. ;-)

[Bård Skaflestad]

@Jan

I guess I should have phrased my comment better. I didn't mean to imply that there was some kind of magic involved, just that combining functions in unexpected ways sometimes produces useful or just plain humorous results.

That said, I applaud your determination. Reading through all the toolbox functions is bound to take considerable of effort. I usually limit my reading to that of the official documentation.