Documentation for Scheme scripting

Documentation for Scheme scripting

[Doug Evans]

Hi.
I'm finishing up the Scheme scripting functionality I want to have in
the first pass.
[For those not familiar with the work, I'm adding Scheme scripting
functionality to gdb that will be akin to the current Python scripting
support.]
One thing that remains is documentation.

Do folks have any preferences for how they want Scheme scripting documented?
And, any preferences for how they *not* want it done?

I can imagine making a copy of all the Python docs and just changing
spelling and such.
I'm not suggesting that's the best approach, but it is *an* approach.
From the point of view of the reader, when reading docs on Python
scripting, they might prefer *not* having to have it complicated by
reading about Scheme as well.

OTOH, duplicating all of that has its own issues.

One thing I'm hoping to avoid is doing a lot of typing only to have to
redo it all.
Speaking up now would be most welcome. :-)

Suggestions?

Re: Documentation for Scheme scripting

[Eli Zaretskii]

> Date: Sun, 8 Sep 2013 14:12:46 -0700
> From: Doug Evans <dje@sceeck.org>
> 
> Do folks have any preferences for how they want Scheme scripting documented?

Similar to Python, I guess, i.e. a section below "Extending GDB",
called something like "Scheme Scripting", and subsections below that
describing whatever needs to be described, in a format similar to how
Python features are documented.

Thanks.

Re: Documentation for Scheme scripting

[Tom Tromey]

>>>>> "Doug" == Doug Evans <dje@sceeck.org> writes:

Doug> I can imagine making a copy of all the Python docs and just changing
Doug> spelling and such.

Surely the Scheme API will not be just a simple copy of the Python API.
Even if that is the intent it will not be true since I think it is
unreasonable to require all Python changes to come with Scheme patches
as well.

I think the Scheme docs have to just be a whole separate section
spelling everything out in Scheme terms.

Though I would like to say now that this isn't really Scheme we're
talking about, but Guile.  There are differences.  I think it would be
best to be explicit about that in the docs.

Tom

Re: Documentation for Scheme scripting

[Eli Zaretskii]

> From: Tom Tromey <tromey@redhat.com>
> Cc: gdb-patches@sourceware.org, eliz@gnu.org
> Date: Mon, 09 Sep 2013 11:00:47 -0600
> 
> I think the Scheme docs have to just be a whole separate section
> spelling everything out in Scheme terms.

Yes, definitely a separate section.

Re: Documentation for Scheme scripting

[Doug Evans]

On Mon, Sep 9, 2013 at 10:00 AM, Tom Tromey <tromey@redhat.com> wrote:
>[...]  I think it is
> unreasonable to require all Python changes to come with Scheme patches
> as well.

No disagreement there.

> I think the Scheme docs have to just be a whole separate section
> spelling everything out in Scheme terms.
>
> Though I would like to say now that this isn't really Scheme we're
> talking about, but Guile.  There are differences.  I think it would be
> best to be explicit about that in the docs.

How far do you think Guile vs Scheme should be pushed?

Should the command to invoke a Scheme command be named "guile" instead
of "scheme"?
Should the gdb subdirectory be gdb/guile over gdb/scheme?

Re: Documentation for Scheme scripting

[Doug Evans]

On Mon, Sep 9, 2013 at 10:13 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Tom Tromey <tromey@redhat.com>
>> Cc: gdb-patches@sourceware.org, eliz@gnu.org
>> Date: Mon, 09 Sep 2013 11:00:47 -0600
>>
>> I think the Scheme docs have to just be a whole separate section
>> spelling everything out in Scheme terms.
>
> Yes, definitely a separate section.

"works for me"

Re: Documentation for Scheme scripting

[Eli Zaretskii]

> Date: Mon, 9 Sep 2013 22:29:10 -0700
> From: Doug Evans <dje@sceeck.org>
> Cc: gdb-patches@sourceware.org, eliz@gnu.org
> 
> > Though I would like to say now that this isn't really Scheme we're
> > talking about, but Guile.  There are differences.  I think it would be
> > best to be explicit about that in the docs.
> 
> How far do you think Guile vs Scheme should be pushed?

I don't speak for Tom, but my opinion is that you can use both
interchangeably.  Guile is an implementation of Scheme (AFAIK); its
sources are replete with references to Scheme, and many of its
variables/symbols use "scheme" or some shorthand thereof.

More specifically, I would use "Scheme" when talking about variables,
functions, etc., and "guile" when talking about the package and the
library.  Other use cases are gray area.

> Should the command to invoke a Scheme command be named "guile" instead
> of "scheme"?

Yes, I think we should use "guile" in this particular use case.