Re: doctest and @example blocks without an actual cope and paste example

[Oliver Heimlich]

On 09.07.2015 15:49, Colin Macdonald wrote:
> On 09/07/15 14:33, Carnë Draug wrote:
> > doctest extracts code from @example blocks.  However, @example is also
> > used
> > to display definitions as in the following case from imbothat [1]:
> >
> >      A bottom hat transform corresponds to the difference between the
> > closing
> >      of @var{img} and @var{img} itself, i.e., it is equivalent to:
> >      @example
> >      imclose (img, se) - img;
> >      @end example
> >
> > which causes an extraction error.
>
> Easiest thing is to mark them with:
>
>    # doctest: +SKIP
>
> or
>
>    @c doctest: +SKIP"
>
> I complained about this elsewhere and started replacing such things,
> (especially the common @ifnotex) with @verbatim.  But unfortunately that
> doesn't format quite the same.
>
> Colin

There are several different things to consider:

- ASCII art is probably best used within an @indentedblock @verbatim 
environment (@example is semantically wrong, but easier to use, because 
of its brevity)

- Formatting within the @example environment (@@, @var, @c, …) shall be 
considered by doctest before the code gets executed

- @c doctest +SKIP should *only* be used for *examples* that are not 
meant to be executable

Oliver