guile-user
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Panicz Maciej Godek
Subject: Re: SLAYER announcement and help request for preparing a GNU package
Date: Wed, 8 May 2013 14:51:47 +0200

2013/5/8 Thien-Thi Nguyen <address@hidden>
() 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.


I think that it might be misleading. I see that autotools are already complicated, and there's no need to complicate them more, especially if guile is an official extension language of the GNU project.
When you ./configure --help, you get a section "Fine tuning of the installation directories", where you get such directives, as --bindir, --datadir and so on. However, if you want to install the guile modules, you need to use --with-guilesitedir, which is documented in 'Optional Packages' section, as if the installation directory was a package.
The Right Thing would be to place --guilesitedir flag in the former section, although I see that there's currently no official way to do it. (And I see that there's been a few discussions about that, like this one: http://lists.gnu.org/archive/html/autoconf/2006-09/msg00009.html, which says that it's allegedly incompatible with GNU Coding Standards, or that one: http://stackoverflow.com/questions/3538705/adding-a-custom-installation-directory-option-to-autoconf-generated-configure-sc. Terribly frustrating!)

   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.


The actual state of the documentation is a secondary issue. I find the question whether we have a framework that allows to extend documentation easily somewhat more important.

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?)

Even not minding the manual (although it would be best if the maintainer could decide whether or not she wishes to export the docstring to the manual), as I understand -- there is no straigtforward C interface to provide docstrings to the functions exported by external modules?
The other problem is that with the introduction of guile-vm, the builtin procedures' argument names disappeared, while they're quite helpful when used with geiser's autodoc mode.

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.


I agree that it's a fairly clean approach, and I will try to employ it ASAP

   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?


I see now that I might have gotten something wrong, but e.g. in libguile/alst.c there was a definition:
SCM_DEFINE (scm_acons, "acons", 3, 0, 0,
           (SCM key, SCM value, SCM alist),
            "Add a new key-value pair to @var{alist}.  A new pair is\n"
            "created whose car is @var{key} and whose cdr is @var{value}, and the\n"
            "pair is consed onto @var{alist}, and the new list is returned.  This\n"
            "function is @emph{not} destructive; @var{alist} is not modified.")
#define FUNC_NAME s_scm_acons
{
  return scm_cons (scm_cons (key, value), alist);
}
#undef FUNC_NAME

and (procedure-documentation acons) returns #f. Now I see that it's meant rather to generate the manual than to provide a docstring.

   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).

 I see you've done a lot of good things :)
I'm grateful!


reply via email to

[Prev in Thread] Current Thread [Next in Thread]