Re: [changeset] Re: [manual] In prepad, add reference to postpad.

[Thorsten Meyer]

Daniel J Sebald wrote:
> Thorsten Meyer wrote:
>> Hi,
>> 
>> Francesco Potortì wrote:
>> 
>>> # HG changeset patch # User Francesco Potortì <address@hidden> # Date 
>>> 1230328478 -3600 # Node ID
>>> 6fa32fc22e5b1c9b84cbcc5ce7ab5d727b42adc5 # Parent  
>>> fcc46267f239ad0199b9fa26407c1d41efeae862 
>>> In prepad, add reference to postpad.
>>> 
>>> diff -r fcc46267f239 -r 6fa32fc22e5b scripts/ChangeLog --- 
>>> a/scripts/ChangeLog    Fri Dec 26
>>> 22:51:48 2008 +0100 +++ b/scripts/ChangeLog    Fri Dec 26 22:54:38 2008 
>>> +0100 @@ -1,4 +1,6 @@
>>> 2008-12-26  Francesco Potortì  <address@hidden 2008-12-26  Francesco 
>>> Potortì  <address@hidden> + +
>>> * general/prepad.m: Add reference to postpad.
>>> 
>>> * general/postpad.m: Use @seealso.  Add reference to resize.
>>> 
>>> diff -r fcc46267f239 -r 6fa32fc22e5b scripts/general/prepad.m --- 
>>> a/scripts/general/prepad.m
>>> Fri Dec 26 22:51:48 2008 +0100 +++ b/scripts/general/prepad.m    Fri Dec 26 
>>> 22:54:38 2008
>>> +0100 @@ -33,6 +33,7 @@ ## ## If the optional @var{dim} argument is given, 
>>> then operate along
>>> this ## dimension. +## @seealso{postpad} ## @end deftypefn
>>> 
>>> ## Author: Tony Richardson <address@hidden>
>>> 
>> as it is, this patch breaks the documentation, because there is no anchor 
>> for the postpad 
>> documentation (so the seealso reference to postpad points nowhere).
>> 
>> Attached is a patch that adds an anchor for postpad.
>> 
>> However, I am not sure if this should be applied: the actual documentation 
>> of the postpad
>> function is in the documentation string for prepad. So the seealso reference 
>> to postpad would
>> be a self reference.
>> 
>> What do you think?
> 
> I deleted this email without paying much attention and then found the same 
> problem.  'help -i'
> isn't working in the HG head.
> 
> Attached is a patch of how I managed to get a working 'doc'.  Besides the 
> DOCSTRING line, I also
> found some @ref's that should be @xref's.  I don't think TeX understands 
> things like @ref{Plot
> Styles}.

The documentation is written in Texinfo. Texinfo has both @ref and @xref. See 
here:

http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Cross-Reference-Commands.html#Cross-Reference-Commands

"
@xref
    Used to start a sentence in the printed manual saying `See ...' or an Info 
cross-reference
saying ‘*Note name: node.’.
@ref
    Used within or, more often, at the end of a sentence; same as @xref for 
Info; produces just the
reference in the printed manual without a preceding `See'.
"

With your patch, the html documentation of basic plotting starts like this for 
me:

        If you need finer control over graphics, see See Advanced Plotting.
                                                 =======

Are you sure that you could not build the documentation without replacing @xref?

> Generally speaking, try to not check in things that don't compile or build 
> properly.  Even when
> there may be some bug in the code, much of it is functional so long as it 
> builds.

I think one problem is, that the documentation breaks quite silently: the 
actual build process is
not interrupted. You only see it afterwards, when you try to find something in 
the
documentation (unless you read the make output very carefully).

I propose to add at least a test like this to the doc function:

%!test if exist( info_file ()) != 2
%!       error ("Info file %s does not exist!", info_file ());
%!     endif

Or maybe the makefile should be changed in such a way that the build process is 
interrupted when the
docs do not build sucessfully.

regards

Thorsten