Re: SLAYER announcement and help request for preparing a GNU package

[Thien-Thi Nguyen]

() Panicz Maciej Godek <address@hidden>
() Wed, 8 May 2013 00:50:32 +0200

   both guile-sdl and guile-figl copy the scm modules to
   $(prefix)/share/guile/site..., but apparently they both do that in a
   different way (which means there's no standard way), and none of them
   allows to 'fine tune' that directory with an optarg to ./configure

I like how guile-ncurses does it.  Maybe Guile-BAUX (and SNUGGLE[0],
which i forgot to mention previously) will follow its lead.

   And the whole thing makes me wonder about the status of guile
   documentation.

Back in time, Guile inherited the documentation maintenance mindset of
Emacs, i.e., "docstrings are for interactive (repl) consumption, full
descriptions belong in the manual".  This makes for a lot of work, which
Emacs can easily demand of its large hacker population, but Guile cannot
(its hackers being relatively few and somewhat prone to solipsism).  So
naturally, as w/ any situation where todo exceeds doers, some stuff does
not get done or gets done w/ less attention than deserved.

At present, there is a protocol between the repl and the database of
docstrings (guile-procedures.txt) only, and only for libguile(?).  And
those laboriously maintained docstrings do not make it into the manual,
either, by dint of the mindset.  If that were to change, i think it
would be a SMOP to arrange to significantly improve the status of Guile
documentation.  (Maybe that has already happened, but i missed it?)

Personally, i think the ideal model is to define a protocol between the
repl and the manual-viewing program, such that full documentation is the
only thing that needs to be maintained.  IMHO, the best layout for that
is intro, concept and expository text in .texi, and proc/var/etc details
in .h/.c/.scm comments.  That's what Guile-BAUX supports, no surpise.

   The guide is really great (although sometimes it remains silent about
   certain features that can be found in header files), but I've
   observed that doc-strings for built-in functions are no longer
   available, even though they are specified.

Could you give some examples?

   And besides, how do the aforementioned modules (those are, as I
   reckon, tsar and c-tsar) refer to guile-snarf-docs that is shipped
   with guile source?

They don't.  The script guile-snarf-docs is not installed, and thus not
available to third parties (like SLAYER or Guile-SDL).  But even if it
were, its method has changed over the years; it might give bad results
if used w/ a different Guile version than its original distribution.
Believe me, i [pw]ondered the same thing.  That's what led to Guile
1.4.x hacking and doc fu[1], and eventually, Guile-BAUX (and SNUGGLE).

___________________________________________________
[0] http://www.gnuvola.org/software/snuggle/

[1] http://www.gnuvola.org/software/guile/
    http://www.gnuvola.org/software/guile/doc/Doc-Maintenance.html

-- 
Thien-Thi Nguyen
GPG key: 4C807502

pgpUy9YqOocXA.pgp
Description: PGP signature