On 04/28/2016 02:12 PM, Mike
Miller wrote:
On Thu, Apr 28,
2016 at 13:24:23 +0200, Olaf Till wrote:
In building
package documentation, when the package is not yet
installed, the cleanest way for extracting help strings from
C++ code
seems to be to compile a (minimalistic) binary which outputs
this help
string. In this way, all special characters in the C-string
are
treated as they should be.
This certainly will break cross-building if the
cross-compiler is used
to compile the minimalistic binary. But any native
C-compiler would
serve, it only has to evaluate the C-string correctly and
call
'printf'. I have no practical experience with
cross-building, I only
care for it because I know others want to do it with
packages. Is
there a way to specifiy, in the Makefile, that for a certain
step a
native compiler should be used, not the cross-compiler?
I am actually not familiar with the minimalistic binary
approach.
In Octave's build system, the C++ preprocessor is used to
extract the
docstrings from all source files, which are then inserted into
the
manual and used to build the doc-cache file. I think that a
cross-preprocessor would be just as effective as a native
preprocessor.
Yes, the .df files are generated using the preprocessor and sed
(sed script is in libinterp/mkdefs). The .df files still have
\n and \" in them. Those are handled by the libinterp/gendoc.pl
script. I think it is better to do this job with a perl script
instead of compiling a program that includes the docstrings.
Rik and I had some plans to change the way docstrings are
handled in the Octave sources so that instead of writing
DEFUN (fcn, args, nargout,
"-*- texinfo -*-\n\
@deftypefn ...
...
...)
you would write something like this:
DEFUN (fcn, args, nargout,
doc: /* -*- texinfo -*-
@deftypefn ...
...
...)
This is what is done in the Emacs sources now (and Emacs is
where I got the idea for the DEFUN macro).
If we switch to this method, the docstring in the C++ sources
would be easier to edit because they would just need to be valid
C comments instead of having to follow the rules for C strings.
Either way, I think we could eliminate the need for the
preprocessor just having a perl script search for DEFUN and
extract the docstrings. But it would be simpler to not have to
deal with escape sequences.