Re: building documentation

[Rik]

On 08/17/2011 12:52 PM, Daniel Kraft wrote:
>
> >> 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.
>
> Thanks!  I'll try that.  But isn't there some quicker way of building
> just a new version of the HTML documentation?  When working on the
> document, I'd like to see my changes ideally without having to rebuild
> everything (and in particular without rebuilding PDF).
I don't find this particularly easier than 'make all', but the following
will work.
At top-level directory
make -C src .DOCSTRINGS       # Note the '.' in the target name
make -C scripts .DOCSTRINGS
make -C doc/interpreter html

>
> >> 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/
>
> I did not modify any Texinfo myself; my version is from yesterday or
> so ... which seems "recent" to me. (?)
>
> >> 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.
>
> I already used @deftypefn (as you suggest, by copying and changing an
> existing docstring).  But still I suppose that I have to tell the
> build-system, where in the manual I want which functions?  Or do you
> mean to say that the docstrings of my profile and profshow functions
> should already be in the manual -- without me doing anything about
> it??  If so, where?
Edit one of the *.txi files in doc/interpreter and add

@DOCSTRING(NAME_OF_FUNCTION_TO_ADD)

in an appropriate location.

For the moment, why don't you add it to debug.txi.  We can make the
profiler it's own chapter if that makes sense, but I would need to do set
up some files for that and I don't want to delay you.

--Rik