|
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 |
() Panicz Maciej Godek <address@hidden>() Wed, 8 May 2013 00:50:32 +0200
I like how guile-ncurses does it. Maybe Guile-BAUX (and SNUGGLE[0],
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
which i forgot to mention previously) will follow its lead.
And the whole thing makes me wonder about the status of guileBack in time, Guile inherited the documentation maintenance mindset of
documentation.
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 aboutCould you give some examples?
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.
And besides, how do the aforementioned modules (those are, as IThey don't. The script guile-snarf-docs is not installed, and thus not
reckon, tsar and c-tsar) refer to guile-snarf-docs that is shipped
with guile source?
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).
[Prev in Thread] | Current Thread | [Next in Thread] |