Re: how to not break cross-building

[John W. Eaton]

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.

jwe