Re: ffi-help: documentation

[Matt Wette <matt.wette@gmail.com>]

> On Jan 7, 2018, at 1:19 PM, Thien-Thi Nguyen <ttn@gnu.org> wrote:
> 
> 
> () Matt Wette <matt.wette@gmail.com>
> () 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 ‘@item’ 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 ‘@example’:
> 
> | 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

Thanks.  I will take that into serious consideration.

Matt