Re: [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