Re: ffi-help: documentation

[Thien-Thi Nguyen]

() Matt Wette <address@hidden>
() Wed, 6 Dec 2017 18:46:59 -0800

   Currently, I'm working on documentation.  I like manuals that
   start out with simple demos to show what's going on.  That is
   my approach here.  Enjoy ...

Cool.  Examples are great.  I suggest only one tweak, small but
pervasive, that would improve text output format readability
(IMHO): add blank lines around environments and prior to
non-trivial address@hidden lines.

For example, compare the original (at beginning):

| come from naming a set of C include files.  The nominal
| method for use is to write a _ffi-module_ specification in a
| file which includes a 'define-ffi-module' declaration and
| then use the command 'guild compile-ffi' to convert this to
| Guile Scheme.
|      $ guild compile-ffi ffi/cairo.ffi
|      wrote `ffi/cairo.scm'
| Note that no C code is generated.  The hooks to access
| C-coded functions in the Cairo library are provided in 100%
| Guile Scheme.

with a revision that adds blank lines around the address@hidden:

| come from naming a set of C include files.  The nominal
| method for use is to write a _ffi-module_ specification in a
| file which includes a 'define-ffi-module' declaration and
| then use the command 'guild compile-ffi' to convert this to
| Guile Scheme.
|
|      $ guild compile-ffi ffi/cairo.ffi
|      wrote `ffi/cairo.scm'
|
| Note that no C code is generated.  The hooks to access
| C-coded functions in the Cairo library are provided in 100%
| Guile Scheme.

(NB: This excerpt was refilled, but that is besides the point.)
I find the latter easier to jump in and out of (skim) visually.

For more mumblings on "blank lines" see:
- http://www.gnuvola.org/u/2017/08/08h21.html
- http://www.gnuvola.org/u/2017/05/17h22.html
- http://www.gnuvola.org/u/2017/05/16h15.html

[cc trimmed]

-- 
Thien-Thi Nguyen -----------------------------------------------
 (defun responsep (query)
   (pcase (context query)
     (`(technical ,ml) (correctp ml))
     ...))                              748E A0E8 1CB8 A748 9BFA
--------------------------------------- 6CE4 6703 2224 4C80 7502

signature.asc
Description: PGP signature