Re: building documentation

[Daniel Kraft]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 08/17/11 20:19, Rik wrote:
> 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.

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).

>> 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?

Yours,
Daniel


- -- 
OpenPGP: 3BA2 3DDB 7758 F010 BDAB 0DCF 527E 79BA A3B5 3998
or use https://safesend.domob.eu/
- --
Done:  Arc-Bar-Cav-Kni-Ran-Rog-Sam-Tou-Val-Wiz
To go: Hea-Mon-Pri
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.17 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQIcBAEBAgAGBQJOTBv0AAoJEFJ+ebqjtTmYia0P/1tkCE5HyHqVACMwlH5F9kic
XO/hWzMqnCsaTUV6hobi+bUiS+0MIPZ3LcCm1NE4BTpPlQjjRmpEpLM5imJVfAVP
T+/42PIhDGPVfbMwFevKWJHc3tOwd1/mj8e7PjXVtZKdrHbJbNEKcjeaxgNXU3bN
A/krYW3VpwccJW475rySrE3lQgxdNeTR6jFqqqSwCymBRxCLaMXzgRXvLhRdlMpP
U6mgSJfbuRU64yxLElbHGCpstllcZJCJ6zsMSwBQfN/05phmki1VGsWjdddokBbW
2guy2G/G3TZ1KcYqi3A2iN7PajOMFqUZ8yLam/s1MSXdkVYB/Dv94BBGw4+d++DR
N4bV2YIbA0TMUAaIzs7XNn7cE+x7FoITVGGl2qNA9jpbjPcWGzcHgv92mNCTb3br
gieS2j2TagD2fJ+nm5xUf9GJ0PdsjRR7wO3m4/+CZ6ZbAWrmZug0/JNPUbPW6oQb
bDdXU027Xg87kCBAQ9GQFnL1FOAuqYicZobJco8+OViLqGW35VkvxfZpl3GIg3EL
MkWRaxINyULDbez5/lvYhgBHxIyCm6zKxtSCs/p+hM2M1ePw3Y97arHTeJzGyGvS
M6vFLLIm0eKDlRAIlT5tTDKIUEvfUYI13ZAdFOpNo7y3emBfdKxujHW5cEaKNp/m
UfYKVjWrqnPQarlPohmE
=hV1m
-----END PGP SIGNATURE-----

smime.p7s
Description: S/MIME Cryptographic Signature