[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [changeset] Re: [manual] In prepad, add reference to postpad.
From: |
Thorsten Meyer |
Subject: |
Re: [changeset] Re: [manual] In prepad, add reference to postpad. |
Date: |
Sun, 04 Jan 2009 19:09:53 +0100 |
User-agent: |
Mozilla-Thunderbird 2.0.0.17 (X11/20081018) |
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
[changeset] Re: [manual] In prepad, add reference to postpad., John W. Eaton, 2009/01/14