Re: [Chicken-users] hahn/salmonella issues
Evan Hanson wrote: I hesitate to mention this since I'm pretty sure I'm the only person who uses it, so it hasn't really been battle-tested (and it's not really documented either), but the schematic egg might do what you're looking for. In particular, the `schematic-wiki' program will generate svnwiki tags for commented (toplevel) procedure definitions, with each tag followed by the comment. So, if you use svnwiki syntax for the comments, the result could be copied into a wiki page without any changes: Ha, that is indeed pretty close to what I want. I remember looking at the description before and not being able to work out whether it'd be useful. Definately looks like it though. Meanwhile I got impatient and hacked up my own little crap tool. https://github.com/utz82/scm2wiki It's not using schematic at the moment, but I could imagine using it in the future. For now though I'm too lazy to make it into a proper egg, sorry. Needs a few more features before it's worth the effort. Best wishes, -Heinz ___ Chicken-users mailing list Chicken-users@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] hahn/salmonella issues
Hi Heinz, On 2019-02-05 16:09, lundi wrote: > > $ cat file.scm | sed 's/^[ \t]+//' | grep -e "^;;;" | cut -b 5- > file.wiki > > I considered writing documenting comments in Markdown and then pipe those > through markdown-svnwiki, but I feel like there's little benefit over just > writing comments directly in svnwiki syntax. > > Obviously there's a lot of room for improvement here. For instance it would > be great to have a way of automatically converting procedure definitions > into (fn args) blocks. I hesitate to mention this since I'm pretty sure I'm the only person who uses it, so it hasn't really been battle-tested (and it's not really documented either), but the schematic egg might do what you're looking for. In particular, the `schematic-wiki' program will generate svnwiki tags for commented (toplevel) procedure definitions, with each tag followed by the comment. So, if you use svnwiki syntax for the comments, the result could be copied into a wiki page without any changes: # chicken-install schematic $ schematic-wiki -c ";;;" < file.scm There's also a program called `schematic-extract' that generates S-expressions instead of text, which you could post-process somehow. There are some details about the expression format here: https://git.foldling.org/schematic.git/tree/0.2.1/schematic-extract.1.md These are also available as library procedures, but again that's totally undocumented (the irony, I know)... Ping me if you end up using this and I'll try to help. All the best, Evan ___ Chicken-users mailing list Chicken-users@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] hahn/salmonella issues
To answer my own question regarding possible alternatives to hahn: I found that simply writing documentation to source with a special comment prefix and then extracting that with some shell voodoo will be closest to what I want. My main gripe with hahn is that IDEs will commonly not recognize the @() docstrings as such, so they will cause a lot of visual clutter in the source. So instead I'll just extract comments starting with a triple semicolon and write those to a wiki file. $ cat file.scm | sed 's/^[ \t]+//' | grep -e "^;;;" | cut -b 5- > file.wiki I considered writing documenting comments in Markdown and then pipe those through markdown-svnwiki, but I feel like there's little benefit over just writing comments directly in svnwiki syntax. Obviously there's a lot of room for improvement here. For instance it would be great to have a way of automatically converting procedure definitions into (fn args) blocks. Also, support for multi-line comments and extracting info from .meta files would be nice to have. Would anybody be interested in having an egg that provides this sort of functionality? I'm under the impression that hardly anybody uses hahn so I imagine nobody would use this either. Best wishes, -Heinz ___ Chicken-users mailing list Chicken-users@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] hahn/salmonella issues
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 ___ Chicken-users mailing list Chicken-users@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] hahn/salmonella issues
Hi, On Tue, 29 Jan 2019 14:57:17 +0100 lundi wrote: > A new day, some new questions. First up, Chicken version is 4.13.0. > > For my wip egg, I'm trying to auto-generate docs with hahn. > This works fine as far as running hahn from command line is > concerned. However, things fail when trying to invoke hahn through > salmonella via setup-helper. > > My .meta contains (depends hahn) and my .setup looks pretty much like > in the example given on the hahn eggref. Running salmonella generates > no .wiki file. Checking salmonella.log reveals: > > > Error: (require) cannot load extension: alist-lib > Call history: > bin/hahn.scm:3: ##sys#require <-- > Warning: Documentation not generated: shell command failed with > nonzero exit status 17920: > hahn -o xmkit.wiki xmkit.scm > This may be because hahn-utils is not installed. > > > Obviously hahn-utils is installed, otherwise I couldn't run hahn from > command line. So let's check that alist-lib. chicken-install alist-lib > gives me: Note that salmonella uses an isolated local egg repository to test eggs, so that it can catch dependency problems. I'd guess the hahn-utils executable you are using is from your CHICKEN installation prefix, not from the environment that salmonella uses. Is that correct? If so, that would explain why you can run hahn-utils but salmonella can't. > The following installed extensions are outdated, because `alist-lib' > requires later versions: > hahn (0.5.3 -> 0.9.3) > > Do you want to replace the existing extensions? (yes/no/abort) [no] > > > Uh, what? Ok, let's replace hahn. Afterwards I also need to reinstall > hahn-utils because "updating" hahn appearantly removes it. Now, > running salmonella again still results in the same error. And > likewise, another chicken-install alist-lib will still complain about > hahn being outdated. > Note that alist-lib is actually installed and usable from csi. > > So, any way I can get out of this loop? Am I missing anything? 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. [1] https://salmonella-linux-x86-64.call-cc.org/chicken-4-debugbuild/gcc/linux/x86-64/2019/01/29/salmonella-report/install/hahn.html [2] https://salmonella-linux-x86-64.call-cc.org/chicken-4-debugbuild/gcc/linux/x86-64/2019/01/29/salmonella-report/install/hahn-utils.html [3] https://salmonella-linux-x86-64.call-cc.org/chicken-4-debugbuild/gcc/linux/x86-64/2019/01/29/salmonella-report/dep-graphs/hahn-utils.html [4] https://salmonella-linux-x86-64.call-cc.org/chicken-4-debugbuild/gcc/linux/x86-64/2019/01/29/salmonella-report/dep-graphs/hahn.html > I'm not subscribed to hahn, in any case. But I do want to > auto-generate pretty-looking wiki pages (with rainbow parens, yay!) > from in-source documentation, if possible. > > Also a slightly related question, is it possible to pass the > salmonella's documentation step when linting locally, or does the > documentation need to be available in the svn repo? The documentation must be available in our wiki. The test that checks for the availability of documentation is basically a HEAD request. All the best. Mario -- http://parenteses.org/mario ___ Chicken-users mailing list Chicken-users@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-users
[Chicken-users] hahn/salmonella issues
Hello, A new day, some new questions. First up, Chicken version is 4.13.0. For my wip egg, I'm trying to auto-generate docs with hahn. This works fine as far as running hahn from command line is concerned. However, things fail when trying to invoke hahn through salmonella via setup-helper. My .meta contains (depends hahn) and my .setup looks pretty much like in the example given on the hahn eggref. Running salmonella generates no .wiki file. Checking salmonella.log reveals: Error: (require) cannot load extension: alist-lib Call history: bin/hahn.scm:3: ##sys#require <-- Warning: Documentation not generated: shell command failed with nonzero exit status 17920: hahn -o xmkit.wiki xmkit.scm This may be because hahn-utils is not installed. Obviously hahn-utils is installed, otherwise I couldn't run hahn from command line. So let's check that alist-lib. chicken-install alist-lib gives me: The following installed extensions are outdated, because `alist-lib' requires later versions: hahn (0.5.3 -> 0.9.3) Do you want to replace the existing extensions? (yes/no/abort) [no] Uh, what? Ok, let's replace hahn. Afterwards I also need to reinstall hahn-utils because "updating" hahn appearantly removes it. Now, running salmonella again still results in the same error. And likewise, another chicken-install alist-lib will still complain about hahn being outdated. Note that alist-lib is actually installed and usable from csi. So, any way I can get out of this loop? Am I missing anything? I'm not subscribed to hahn, in any case. But I do want to auto-generate pretty-looking wiki pages (with rainbow parens, yay!) from in-source documentation, if possible. Also a slightly related question, is it possible to pass the salmonella's documentation step when linting locally, or does the documentation need to be available in the svn repo? Thanks in advance, -Heinz ___ Chicken-users mailing list Chicken-users@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-users
