* bug#24363: Clarify the VM docs
@ 2016-09-04 5:04 Wilfred Hughes
[not found] ` <handler.24363.B.147296552715192.ack@debbugs.gnu.org>
0 siblings, 1 reply; 6+ messages in thread
From: Wilfred Hughes @ 2016-09-04 5:04 UTC (permalink / raw)
To: 24363
[-- Attachment #1: Type: text/plain, Size: 1059 bytes --]
The docs currently state:
> The easiest (and most fun) way to depend on a virtual machine is to
implement the virtual machine within Guile itself. This way the virtual
machine provides what Scheme needs (tail calls, multiple values, call/cc)
and can provide optimized inline instructions for Guile (cons, struct-ref,
etc.).
This is a little confusing for new readers (like myself), who may consider
Guile to by synonymous with Scheme.
This led to interpret this as 'the VM is implemented in Scheme', which has
a bootstrapping problem (what actually interprets your bytecode?).
Instead, I propose adding an additional sentence:
> The easiest (and most fun) way to depend on a virtual machine is to
implement the virtual machine within Guile itself. Guile contains a
bytecode interpreter (written in C) and a Scheme to bytecode compiler
(written in Scheme). This way the virtual machine provides what Scheme
needs (tail calls, multiple values, @code{call/cc}) and can provide
optimized inline instructions for Guile (@code{cons}, @code{struct-ref},
etc.).
[-- Attachment #2: Type: text/html, Size: 1225 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#24363: Acknowledgement (Clarify the VM docs)
[not found] ` <handler.24363.B.147296552715192.ack@debbugs.gnu.org>
@ 2016-09-04 5:08 ` Wilfred Hughes
2016-09-04 16:14 ` Andy Wingo
0 siblings, 1 reply; 6+ messages in thread
From: Wilfred Hughes @ 2016-09-04 5:08 UTC (permalink / raw)
To: 24363
[-- Attachment #1.1: Type: text/plain, Size: 942 bytes --]
Here's my proposed change as a patch against master, currently
cb421b6546ad3e09299462df63c389aa734fdba8.
On 4 September 2016 at 01:06, GNU bug Tracking System <help-debbugs@gnu.org>
wrote:
> Thank you for filing a new bug report with debbugs.gnu.org.
>
> This is an automatically generated reply to let you know your message
> has been received.
>
> Your message is being forwarded to the package maintainers and other
> interested parties for their attention; they will reply in due course.
>
> Your message has been sent to the package maintainer(s):
> bug-guile@gnu.org
>
> If you wish to submit further information on this problem, please
> send it to 24363@debbugs.gnu.org.
>
> Please do not send mail to help-debbugs@gnu.org unless you wish
> to report a problem with the Bug-tracking system.
>
> --
> 24363: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=24363
> GNU Bug Tracking System
> Contact help-debbugs@gnu.org with problems
>
[-- Attachment #1.2: Type: text/html, Size: 1709 bytes --]
[-- Attachment #2: vm_docs.patch --]
[-- Type: text/x-patch, Size: 1071 bytes --]
diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi
index 2f32c51..9766ccb 100644
--- a/doc/ref/vm.texi
+++ b/doc/ref/vm.texi
@@ -62,10 +62,12 @@ The obvious solution is to compile to a virtual machine that is
present on all Guile installations.
The easiest (and most fun) way to depend on a virtual machine is to
-implement the virtual machine within Guile itself. This way the
-virtual machine provides what Scheme needs (tail calls, multiple
-values, @code{call/cc}) and can provide optimized inline instructions
-for Guile (@code{cons}, @code{struct-ref}, etc.).
+implement the virtual machine within Guile itself. Guile contains a
+bytecode interpreter (written in C) and a Scheme to bytecode compiler
+(written in Scheme). This way the virtual machine provides what Scheme
+needs (tail calls, multiple values, @code{call/cc}) and can provide
+optimized inline instructions for Guile (@code{cons}, @code{struct-ref},
+etc.).
So this is what Guile does. The rest of this section describes that VM
that Guile implements, and the compiled procedures that run on it.
^ permalink raw reply related [flat|nested] 6+ messages in thread
* bug#24363: Acknowledgement (Clarify the VM docs)
2016-09-04 5:08 ` bug#24363: Acknowledgement (Clarify the VM docs) Wilfred Hughes
@ 2016-09-04 16:14 ` Andy Wingo
2016-09-05 0:23 ` Wilfred Hughes
0 siblings, 1 reply; 6+ messages in thread
From: Andy Wingo @ 2016-09-04 16:14 UTC (permalink / raw)
To: Wilfred Hughes; +Cc: 24363
On Sun 04 Sep 2016 07:08, Wilfred Hughes <me@wilfred.me.uk> writes:
> Here's my proposed change as a patch against master, currently
> cb421b6546ad3e09299462df63c389aa734fdba8.
Looks good! Can you provide it in the format produced by
git-format-patch? If you commit it to your Guile tree, give it a
changelog in the normal format (see git log doc/ref/vm.texi to see
examples), then run "git format-patch HEAD^", I can apply it
super-easily, and it will have your authorship info intact.
I am treating this one as trivial from a copyright POV so that we can
just get it in. If you plan on submitting more patches, let me know and
we can get the copyright papers going (I see you already have one for
Emacs).
Cheers,
Andy
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#24363: Acknowledgement (Clarify the VM docs)
2016-09-04 16:14 ` Andy Wingo
@ 2016-09-05 0:23 ` Wilfred Hughes
2016-09-05 18:52 ` Andy Wingo
0 siblings, 1 reply; 6+ messages in thread
From: Wilfred Hughes @ 2016-09-05 0:23 UTC (permalink / raw)
To: Andy Wingo; +Cc: 24363
[-- Attachment #1.1: Type: text/plain, Size: 86 bytes --]
Patch attached.
I'd like to sort copyright papers too, let me know what's necessary.
[-- Attachment #1.2: Type: text/html, Size: 136 bytes --]
[-- Attachment #2: 0001-Clarify-bootstrap-docs.patch --]
[-- Type: text/x-patch, Size: 1579 bytes --]
From 0b7a585ffb3a0e5b33e10101cc817dbf50736a2f Mon Sep 17 00:00:00 2001
From: Wilfred Hughes <me@wilfred.me.uk>
Date: Sun, 4 Sep 2016 20:14:49 -0400
Subject: [PATCH] Clarify bootstrap docs
* doc/ref/vm.texi: Add a sentence stating which parts of the bytecode
toolchain are in C, and which are in Scheme. This avoids confusion if
users assume Guile==Scheme and so assume the whole toolchain is in
Scheme.
---
doc/ref/vm.texi | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi
index 2f32c51..9766ccb 100644
--- a/doc/ref/vm.texi
+++ b/doc/ref/vm.texi
@@ -62,10 +62,12 @@ The obvious solution is to compile to a virtual machine that is
present on all Guile installations.
The easiest (and most fun) way to depend on a virtual machine is to
-implement the virtual machine within Guile itself. This way the
-virtual machine provides what Scheme needs (tail calls, multiple
-values, @code{call/cc}) and can provide optimized inline instructions
-for Guile (@code{cons}, @code{struct-ref}, etc.).
+implement the virtual machine within Guile itself. Guile contains a
+bytecode interpreter (written in C) and a Scheme to bytecode compiler
+(written in Scheme). This way the virtual machine provides what Scheme
+needs (tail calls, multiple values, @code{call/cc}) and can provide
+optimized inline instructions for Guile (@code{cons}, @code{struct-ref},
+etc.).
So this is what Guile does. The rest of this section describes that VM
that Guile implements, and the compiled procedures that run on it.
--
2.9.3
^ permalink raw reply related [flat|nested] 6+ messages in thread
* bug#24363: Acknowledgement (Clarify the VM docs)
2016-09-05 0:23 ` Wilfred Hughes
@ 2016-09-05 18:52 ` Andy Wingo
2017-03-01 9:07 ` Andy Wingo
0 siblings, 1 reply; 6+ messages in thread
From: Andy Wingo @ 2016-09-05 18:52 UTC (permalink / raw)
To: Wilfred Hughes; +Cc: 24363
On Mon 05 Sep 2016 02:23, Wilfred Hughes <me@wilfred.me.uk> writes:
> Patch attached.
Applied, thanks! I'll follow up privately about papers.
Andy
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#24363: Acknowledgement (Clarify the VM docs)
2016-09-05 18:52 ` Andy Wingo
@ 2017-03-01 9:07 ` Andy Wingo
0 siblings, 0 replies; 6+ messages in thread
From: Andy Wingo @ 2017-03-01 9:07 UTC (permalink / raw)
To: 24363-done
done
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2017-03-01 9:07 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-09-04 5:04 bug#24363: Clarify the VM docs Wilfred Hughes
[not found] ` <handler.24363.B.147296552715192.ack@debbugs.gnu.org>
2016-09-04 5:08 ` bug#24363: Acknowledgement (Clarify the VM docs) Wilfred Hughes
2016-09-04 16:14 ` Andy Wingo
2016-09-05 0:23 ` Wilfred Hughes
2016-09-05 18:52 ` Andy Wingo
2017-03-01 9:07 ` Andy Wingo
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).