manual examples - self contained or not?

manual examples - self contained or not?

[Ian Price]

Hi guilers,

is there an "official" policy on whether or not examples in the manual
should be self contained?

On IRC, kudkudyak was confused about read-line not being found when he
tried to run one of the socket examples. Naturally, I pointed out that
this is because read-line is in (ice-9 rdelim).

Some manual examples, however, do include imports
https://www.gnu.org/software/guile/manual/html_node/Hash-Table-Reference.html
includes srfis 1 and 13.  An example in
https://www.gnu.org/software/guile/manual/html_node/Dynamic-FFI.html
includes (rnrs bytevectors).

With the obvious exception of examples whose entire purpose is to show
off the module system, and similar, I think we should adopt a consistent
policy one way or the other, and adapt all the examples to it.

My vote would be for self-contained: it can be copied directly into a
file or REPL and executed, and IMO reduces confusion. I already try to
do this when posting any examples on paste.lisp.org or in a gist.

Other people may feel differently, as it is relatively easy to search
the manual for missing procedures and, as cky put it, "I don't believe
in copypasta coding".

-- 
Ian Price

"Programming is like pinball. The reward for doing it well is
the opportunity to do it again" - from "The Wizardy Compiled"

Re: manual examples - self contained or not?

[Nala Ginrut]

[-- Attachment #1: Type: text/plain, Size: 1546 bytes --]

well, I don't believe in copy-paste code too.
But my vote would be "at least I can trust the official manual"...

On Mon, Feb 20, 2012 at 12:42 AM, Ian Price <ianprice90@googlemail.com>wrote:

>
> Hi guilers,
>
> is there an "official" policy on whether or not examples in the manual
> should be self contained?
>
> On IRC, kudkudyak was confused about read-line not being found when he
> tried to run one of the socket examples. Naturally, I pointed out that
> this is because read-line is in (ice-9 rdelim).
>
> Some manual examples, however, do include imports
>
> https://www.gnu.org/software/guile/manual/html_node/Hash-Table-Reference.html
> includes srfis 1 and 13.  An example in
> https://www.gnu.org/software/guile/manual/html_node/Dynamic-FFI.html
> includes (rnrs bytevectors).
>
> With the obvious exception of examples whose entire purpose is to show
> off the module system, and similar, I think we should adopt a consistent
> policy one way or the other, and adapt all the examples to it.
>
> My vote would be for self-contained: it can be copied directly into a
> file or REPL and executed, and IMO reduces confusion. I already try to
> do this when posting any examples on paste.lisp.org or in a gist.
>
> Other people may feel differently, as it is relatively easy to search
> the manual for missing procedures and, as cky put it, "I don't believe
> in copypasta coding".
>
> --
> Ian Price
>
> "Programming is like pinball. The reward for doing it well is
> the opportunity to do it again" - from "The Wizardy Compiled"
>
>
>

[-- Attachment #2: Type: text/html, Size: 2284 bytes --]

Re: manual examples - self contained or not?

[Neil Jerram]

Nala Ginrut <nalaginrut@gmail.com> writes:

> well, I don't believe in copy-paste code too.
> But my vote would be "at least I can trust the official manual"...

I did think it would be nice, a while back, if we could implement a way
of automatically checking that the examples in the manual are still
correct, and that they generate the results that the manual says they
do.  I think that would contribute to being able to trust the manual, or
else flag up any areas that might have rotted a bit.

In order to do that, without requiring too much special casing code, the
checker would need to be able to identify any required module uses.

So, in addition to the direct benefit for people reading the manual, I
think that motivates that the example should be by some definition self
contained.  As others have suggested, I'd favour automatically picking
up (use-modules ...) forms from earlier or higher up in the current
hierarchy, so that it isn't necessary to keep repeating those in every
@example.

Does anyone fancy the automatic checking project?

      Neil

Re: manual examples - self contained or not?

[Andy Wingo]

On Tue 21 Feb 2012 22:14, Neil Jerram <neil@ossau.homelinux.net> writes:

> Does anyone fancy the automatic checking project?

Someone could use our lovely (texinfo) modules :-)

Andy
-- 
http://wingolog.org/

Re: manual examples - self contained or not?

[Noah Lavine]

Hello,

> My vote would be for self-contained: it can be copied directly into a
> file or REPL and executed, and IMO reduces confusion. I already try to
> do this when posting any examples on paste.lisp.org or in a gist.

When you say "self-contained", do you mean that if the example uses a
procedure from a module, it should have a (use-modules ...) statement?
If so, that sounds good to me.

If you mean that most examples should never use procedures that are in
modules, that seems a little restrictive.

Noah

Re: manual examples - self contained or not?

[Andy Wingo]

On Sun 19 Feb 2012 17:42, Ian Price <ianprice90@googlemail.com> writes:

> With the obvious exception of examples whose entire purpose is to show
> off the module system, and similar, I think we should adopt a consistent
> policy one way or the other, and adapt all the examples to it.

FWIW, I agree.

> My vote would be for self-contained: it can be copied directly into a
> file or REPL and executed, and IMO reduces confusion.

I agree also, with the caveat that a

  (use-modules (foo))

at the top of a manual page should imply that the module is used in all
subsequent examples.

Thoughts welcome from others, of course; and regardless, patches will
move the conversation along :)

Andy
-- 
http://wingolog.org/

Re: manual examples - self contained or not?

[Ludovic Courtès]

Hi Ian,

Ian Price <ianprice90@googlemail.com> skribis:

> Some manual examples, however, do include imports
> https://www.gnu.org/software/guile/manual/html_node/Hash-Table-Reference.html
> includes srfis 1 and 13.  An example in
> https://www.gnu.org/software/guile/manual/html_node/Dynamic-FFI.html
> includes (rnrs bytevectors).

What I typically do is to add ‘use-modules’ clauses for modules that are
not those being discussed.

So the above example has no (system foreign) import, on the assumption
that it’s implicit in its context, but it has (rnrs bytevectors).

Thanks,
Ludo’.