Re: building documentation

[Rik]

On 08/17/2011 10:00 AM, address@hidden wrote:
> From: Daniel Kraft <address@hidden>
>
> Hi,
>
> sorry if that's a dumb question ... but I just tried to build the
> Octave manual from source (so that I can work on a profiler chapter
> and see the effects), but couldn't figure out how to do so.
>
> make doc/html/info/pdf from the main directory runs through, but
> doesn't seem to create any HTML or PDF files in doc/interpreter.
>From the top-level directory you need to use 'make all' which, assuming you
haven't configured with --disable-docs, will  build HTML, PDF, and Info
versions of the documentation.
> make pdf inside of doc seems to work, but I'd really love to get HTML
> output instead -- make html results in:
>
> if /bin/sh /home/daniel/Projekte/octave/build-aux/missing --run
> makeinfo --html   -I . \
>          -o octave.htp octave.texi; \
>         then \
>           rm -rf octave.html; \
>           if test ! -d octave.htp && test -d octave; then \
>             mv octave octave.html; else mv octave.htp octave.html; fi; \
>         else \
>           if test ! -d octave.htp && test -d octave; then \
>             rm -rf octave; else rm -Rf octave.htp octave.html; fi; \
>           exit 1; \
>         fi
> /home/daniel/Projekte/octave/doc/interpreter//matrix.texi:1429:
> Unknown command `leq'.
> /home/daniel/Projekte/octave/doc/interpreter//matrix.texi:1429:
> Misplaced {.
> /home/daniel/Projekte/octave/doc/interpreter//matrix.texi:1429:
> Misplaced }.
> /home/daniel/Projekte/octave/doc/interpreter//matrix.texi:1591:
> Unknown command `leq'.
> /home/daniel/Projekte/octave/doc/interpreter//matrix.texi:1591:
> Misplaced {.
> /home/daniel/Projekte/octave/doc/interpreter//matrix.texi:1591:
> Misplaced }.
> ...
>
> So what do I have to do to build the manual (preferrably as HTML, like
> on the Octave web page)?  Any idea what's going wrong?
It seems that you have unparseable Texinfo in the file matrix.texi.  I
would update to a recent Mercurial tip and then run 'make all' from the
top-level directory.  The docs build for me on tip 12974:6590446c2498.  The
HTML that you are looking for will be in the directory
<top-level>/doc/interpreter/octave.html/

> BTW, I think the docstrings of functions are included in the manual
> somehow "automagically" -- how can I make this work also for my
> profiling functions, as part of the profiler chapter?  (Which I'm
> going to write.)
See the section "Tips for Documentation Strings" in the manual.  In
particular, you want the @deftypefn macro which will get expanded and put
in the manual.  It's usually way easier to just borrow a well-written
docstring from another file and change it then to write one from scratch
where you will forget some of the macros.

--Rik