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

[Daniel J Sebald]

Thorsten Meyer wrote:

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

Obviously not.  "xref" means that?  Sort of arcane, 'x'; '@bref' for "beginning reference" might make more sense.  Anyway, there are still non-critical errors in the documentation that need accounting for.


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

Agreed.


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

I suppose losing documentation isn't a critical thing for non-development.  Perhaps a warning:  WARNING:  INFO FILE NOT BUILT CORRECTLY.  WILL NOT HAVE DOC FUNCTION, which would be clearly visible amongst all the text output.

Dan