2013/5/8 Thien-Thi Nguyen <t...@gnu.org>
> () Panicz Maciej Godek <godek.mac...@gmail.com>
> () 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!
