[PATCH] doc: embedding example more readable.

[PATCH] doc: embedding example more readable.

[Arne Babenhauserheide]

Hi,

I worked a bit on the example for linking guile into programs. The following two patches should make the documentation much less daunting.

The first patch does the major work, the second one shortenes the first line of the code to fit better with the rest of the code.

I got the idea when comparing the linking example¹ with the one from Lua². While the Lua example is actually much more complex, the Guile example *looked* more complicated. And I think that was mainly due to being more verbose than necessary and having the build instructions in the same chapter as the code-example.

¹: http://www.gnu.org/software/guile/manual/guile.html#A-Sample-Guile-Main-Program
²: http://www.lua.org/pil/24.1.html

Best wishes,
Arne

From 287c5514bfdb193a78c598d9382e5c0ed3ce3a49 Mon Sep 17 00:00:00 2001
From: Arne Babenhauserheide <bab@draketo.de>
Date: Sun, 12 Jan 2014 00:03:27 +0100
Subject: [PATCH] doc: embedding example more readable.

* doc/ref/guile.texi (A Sample Guile Main Program): Easier to read example code and building split into 2 subsections.
---
 doc/ref/libguile-linking.texi | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/doc/ref/libguile-linking.texi b/doc/ref/libguile-linking.texi
index de90768..53fbd25 100644
--- a/doc/ref/libguile-linking.texi
+++ b/doc/ref/libguile-linking.texi
@@ -71,24 +71,23 @@ Here is @file{simple-guile.c}, source code for a @code{main} and an
 interpreter.
 
 @example
-/* simple-guile.c --- how to start up the Guile
-   interpreter from C code.  */
+/* simple-guile.c --- start a Guile interpreter from C code.  */
 
-/* Get declarations for all the scm_ functions.  */
 #include <libguile.h>
 
 static void
 inner_main (void *closure, int argc, char **argv)
 @{
-  /* module initializations would go here */
+  /* preparation */
   scm_shell (argc, argv);
+  /* after exit */
 @}
 
 int
 main (int argc, char **argv)
 @{
   scm_boot_guile (argc, argv, inner_main, 0);
-  return 0; /* never reached */
+  return 0; /* never reached, see inner_main */
 @}
 @end example
 
@@ -97,7 +96,9 @@ Guile, passing it @code{inner_main}.  Once @code{scm_boot_guile} is
 ready, it invokes @code{inner_main}, which calls @code{scm_shell} to
 process the command-line arguments in the usual way.
 
-Here is a Makefile which you can use to compile the above program.  It
+@subsection Building the Example with Make
+
+Here is a Makefile which you can use to compile the example program.  It
 uses @code{pkg-config} to learn about the necessary compiler and
 linker flags.
 @example
@@ -117,8 +118,10 @@ simple-guile.o: simple-guile.c
         $@{CC@} -c $@{CFLAGS@} simple-guile.c
 @end example
 
+@subsection Building the Example with Autoconf
+
 If you are using the GNU Autoconf package to make your application more
-portable, Autoconf will settle many of the details in the Makefile above
+portable, Autoconf will settle many of the details in the Makefile
 automatically, making it much simpler and more portable; we recommend
 using Autoconf with Guile.  Here is a @file{configure.ac} file for
 @code{simple-guile} that uses the standard @code{PKG_CHECK_MODULES}
-- 
1.8.4

From c00fd3bc1296aa0f9d3dbde117e1c3c602f78715 Mon Sep 17 00:00:00 2001
From: "bab@draketo.de" <bab@draketo.de>
Date: Fri, 17 Jan 2014 14:45:10 +0100
Subject: [PATCH] doc: embedding example more readable.

* doc/ref/libguile-linking.texi (A Sample Guile Main Program): shortened a code-line.

--HG--
extra : rebase_source : 6d73225b0d9cf9a304b78efeb7f7d199b03377e7
---
 doc/ref/libguile-linking.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ref/libguile-linking.texi b/doc/ref/libguile-linking.texi
index 53fbd25..0101040 100644
--- a/doc/ref/libguile-linking.texi
+++ b/doc/ref/libguile-linking.texi
@@ -71,7 +71,7 @@ Here is @file{simple-guile.c}, source code for a @code{main} and an
 interpreter.
 
 @example
-/* simple-guile.c --- start a Guile interpreter from C code.  */
+/* simple-guile.c --- start an interpreter from C.  */
 
 #include <libguile.h>
 
-- 
1.8.4

Re: [PATCH] doc: embedding example more readable.

[Ludovic Courtès]

Arne Babenhauserheide <arne_bab@web.de> skribis:

> From 287c5514bfdb193a78c598d9382e5c0ed3ce3a49 Mon Sep 17 00:00:00 2001
> From: Arne Babenhauserheide <bab@draketo.de>
> Date: Sun, 12 Jan 2014 00:03:27 +0100
> Subject: [PATCH] doc: embedding example more readable.
>
> * doc/ref/guile.texi (A Sample Guile Main Program): Easier to read example code and building split into 2 subsections.

Pushed, thanks (I merged the two commits into one.)

Ludo’.