[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ì <pot at gnu.org> # 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ì  <pot at gnu. 2008-12-26  Francesco Potortì  <pot at gnu.org> + +
>>> * 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 <arichard at stark.cc.oh.us>
>>> 
>> 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