Re: [Chicken-users] hahn/salmonella issues

[lundi]

Hi,

On 1/30/19 9:14 AM, Mario Domenech Goulart wrote:

> I don't know how hahn/hahn-utils work, but both seem to be ok according
> to you test system [1][2].  It seems that you are using hahn-utils, but
> you have hahn in your dependency specification.  According to the
> dependency graphs, hahn-utils depends on hahn, not the other way around
> [3][4].  It's possible that hahn is documented using itself, and that it
> would optionally use hahn-utils (that would be a circular dependency),
> but I'm not sure about that.

I might have been a bit confused about things myself. Anyway, first of 
all there are two different things named hahn: 1) The hahn binary, which 
is provided by the hahn-utils egg; and 2) the hahn egg, which provides 
the run-hahn macro. From the hahn egg doc:

> The hahn binary from hahn-utils generates the actual documentation; the hahn 
> egg provides a convenience macro run-hahn so that installation does not fail 
> for users who haven't installed hahn-utils.
>
> There is a soft-dependency on the otherwise dependency-heavy egg hahn-utils: 
> users don't have to have it unless they want to generate docs themselves, for 
> some reason.
And from hahn-utils:

> Hahn-utils is mainly interesting because it provides the hahn program that 
> takes code documented with hahn and converts it into documentation.
>
> Hahn-utils is a soft-dependency and shouldn't be included in depends.

As far as I can tell, hahn (the egg) is not documented using itself, but 
hahn-utils is.

In any case, the problem seems to be that run-hahn does not work, 
neither through salmonella nor through csi. From csi with hahn and 
hahn-utils loaded, the error looks like this:


(run-hahn -o xmkit.wiki xmkit.scm)

Warning: Documentation not generated: unbound variable

This may be because hahn-utils is not installed. Hahn-utils is an
optional egg for generating documentation and installation will
succeed without it.

Note: the following toplevel variables are referenced but unbound:

  run
  hahn
  -o
  xmkit.wiki
  xmkit.scm


Uh-oh. Note the parsing of "run" and "hahn" as two different vars. 
Should this be considered a bug? I'd file an issue on Github in that 
case but I would like to make sure first that the problem is with 
hahn/hahn-utils and not Chicken.

So I guess for the time being I should just stick to running hahn from 
command line, and not use run-hahn in .setup. How would I provide local 
documentation with my egg then, though? Would it normally be fetched 
from the wiki svn by chicken-install?

On the other hand, I think ultimately hahn is maybe not an ideal 
solution. First of all it's not available in Chicken 5 yet... though of 
course the author is a very busy man, so chances are he'll port it at 
some point. What bugs me though is the docstring style. I think 
comment-style in-source documentation (like Doxygen) is much cleaner. So 
I'm looking at SchemeDoc now (http://people.cs.aau.dk/~normark/schemedoc/).
I'm afraid though I won't have time to make it work with Chicken any 
time soon though. Providing the LAML compat functions seems easy enough, 
but writing a SchemeDoc to snvwiki converter is quite a chunk of work 
imo. Also it seems Chicken once had a thing called Docscm, not sure what 
happened to that?

Best wishes,
-Heinz