Re: Install munge-texi.pl for use by packages?

[Mike Miller]

On Mon, Jul 7, 2014 at 22:53:45 +0200, Olaf Till wrote:
> On Mon, Jul 07, 2014 at 02:46:04PM -0400, John W. Eaton wrote:
>> On 07/07/2014 12:50 PM, Mike Miller wrote:
>>
>> >Yep, exactly as Carlo said, no reason for duplication, if we can
>> >replace this with an Octave script or function, it can also be used to
>> >build Octave's own manual as well.
>> >
>> >I think these are great ideas, please file a wishlist bug on Octave to
>> >replace munge-texi.pl with an equivalent Octave function that can be
>> >used for both Octave's manual and for package manuals.
>>
>> I'd like to be able to cross compile packages so that we can cross
>> compile a complete Octave distribution that includes packages that
>> are already built and ready to install along with Octave.  Will
>> having this script as an Octave function make that job harder?

Yes, good point, if the goal is to be able to cross-compile Octave
completely from hg.

>> For example, we can't currently cross compile Octave directly from
>> the mercurial sources because doing so requires running the copy of
>> Octave that is being built in order to create figures for the
>> manual.  And when doing a cross build, that doesn't work.  I suppose
>> that making the munge-texi script an Octave function would make that
>> problem slightly worse because then building would fail if you
>> modified the manual sources, not just if you modified the source
>> file for one of the figures.
>>
>> If we do go down this path, then I suppose a solution for cross
>> compiling would be to require that we build (or use, if it is
>> already installed on the system) a corresponding native version of
>> Octave that can be executed on the build system to generate the
>> figures and perform the munge-texi step.

Or require that a native dist tarball is made first. Is there any
effective difference between doing a native "make dist" and
cross-building from that, versus adding an option to the build to use
an externally built native Octave to generate images and etc?

> I didn't see first that munge-texi.pl uses DOCSTRINGS files generated
> by mkdoc.pl. So either mkdoc.pl also would have to be converted to an
> Octave function, or the Octave function for munge-texi should use
> `get_help_text()' instead of DOCSTRINGS files. Intuitively I'd like
> the latter better, but are the DOCSTRINGS files also needed for other
> things? And using `get_help_text()' would require always to have the
> _same_ Octave version locally installed for cross-builds, since the
> help texts would be taken from the installed version ...

The DOCSTRINGS files are used to embed function docstrings into the
manual's texi sources and also to build the "doc-cache" file used by
the help function for fast lookup.

Incidentally, pkg install also builds a doc-cache file for functions
in a package. This is done in Perl for Octave's own doc-cache but in
an Octave function for pkg. So there is a lot of overlap between these
pieces as well.

Keeping cross-building of Octave in mind, it appears to be best if
Octave's own docs can be built without a native Octave executable, but
the opposite for installing packages, the fewer additional
dependencies for users the better.

-- 
mike