Ideas for Documentation

Ideas for Documentation

[Karl Winterling]

Hi,

I've thought about writing an "official tutorial" for Guile directed
at application users who have no programming experience. I thought
it's best to see what the community thinks given that educational
approaches are so politically charged. Anything I write would probably
focus a lot on discrete math and describing the rationale for Scheme's
design, which might be boring or difficult for certain people.

---Karl

Re: Ideas for Documentation

[Linas Vepstas]

Hi,

On 15 May 2010 16:35, Karl Winterling <kwinterling@gmail.com> wrote:
> Hi,
>
> I've thought about writing an "official tutorial" for Guile directed
> at application users who have no programming experience. I thought
> it's best to see what the community thinks given that educational
> approaches are so politically charged.

Heh.

> Anything I write would probably
> focus a lot on discrete math and describing the rationale for Scheme's
> design,

Well, of all of the applications that use guile, none that I know
of can be described as "discrete math".

The primary applications that I know of using guile are:

-- GnuCash (personal finance)
-- LilllyPond (music typesetting)
-- Gnome Games
-- gEDA (electronic circuit board design)
-- GnoTime (diary/timekeeping/billing)
-- OpenCog (AGI experimental platform)

Which "application users" do you have in mind?
All of the above?

--linas

Re: Ideas for Documentation

[Karl Winterling]

On Sat, May 15, 2010 at 3:03 PM, Linas Vepstas <linasvepstas@gmail.com> wrote:
> Which "application users" do you have in mind?
> All of the above?

I guess so. In the sense that Guile is supposed to become a
semi-official extension language.

Re: Ideas for Documentation

[Keith Wright]

> From: Linas Vepstas <linasvepstas@gmail.com>
> 
> On 15 May 2010 16:35, Karl Winterling <kwinterling@gmail.com> wrote:
> 
> > Anything I write would probably focus a lot on
> > discrete math and describing the rationale for
> > Scheme's design,
> 
> Well, of all of the applications that use guile, none
> that I know of can be described as "discrete math".

On the other hand, while I have no idea what you know
or how it can be described, I can prove by algebra[1]
that all computer programs are discrete math.

I would advise potential authors not to think about
writing anything "official" and just write what
you have to say.  If it is good, the world will
make it "de facto" and nobody will care if it is
"official".

   -- Keith

[1] I get to choose the premises.

Re: Ideas for Documentation

[Linas Vepstas]

On 16 May 2010 11:06, Keith Wright <kwright@keithdiane.us> wrote:
>
> On the other hand, while I have no idea what you know
> or how it can be described, I can prove by algebra[1]
> that all computer programs are discrete math.

If I knew how to describe what I know, I'd put it on my resume.
http://en.wikipedia.org/wiki/User:Linas/Articles

google and wikipedia can provide the "standard" definition
of "discrete math" e.g.
http://en.wikipedia.org/wiki/Discrete_mathematics


Although GnuCash, Gnotime & other programs that use
guile originally intended for guile to be used as a true
"extension language", that goal remains mostly unfulfilled.
Frankly, its just plain hard for non-programmers (and
many experienced programmers) to use scheme.

So, for example, GnoTime generates reports/charts in
HTML so that they can be e-mailed, etc. Scheme code can
be embedded in the reports, kind-of-like PHP, to customize
the layout contents. (gnotime sends these off to guile for
interpretation, while generating the report) There's a bunch
of example reports, and a built-in mini-scheme-tutorial in
GnoTime (found in the "reports" menu, explaining that the
reports can be customized), to assist with this. But, to the
best of my knowledge, no one has ever actually done this --
no one has ever made any changes big enough to send
back to the gnotime developers.

Guile in GnuCash was originally intended to make GnuCash
customizable in various deep and powerful ways, but I think
that vision was lost, and I don't think it even begins to be as
easily usable as gnotime is.  GnuCash would probably need
some major work to expose guile to the ordinary user, and,
even if these changes were made, its not clear that the
ordinary user cares.

At best, "extension languages" seem best suited for small
consultancies who are making one-off changes to existing
software products, for the benefit of paying clients. Neither
GnoTime nor GnuCash seem to have a user-base that is
interested in getting slightly modified versions for their own
private use.

--linas