I have been testing the first half of the API, adding caveats to the Implementation section for my in progress pull request, which is getting big enough to need section headers for navigation.

I've found that scsh's 0.7's temp-file-iterate is broken in myriad ways, and the first example using it is further broken by create-hard-link not raising an error if the newname is in a different file system, in which case it silently makes a copy there.

While I don't like how temp-file-iterate's contract allows it to fail after trying some number of iterations, it does provide unique and currently undocumented functionality because it requires an "~a" as supplied in scsh's *temp-file-template* fluid variable.  This is handed to format, allowing almost precise filenames.  If we want to keep it, we should provide a fixed version, and that shouldn't be hard, here's its source code, which can entered in the scsh REPL without error:

So my requested decisions are "fix or document", as well as should I add headers to the Implementation section.  Since none of the section 3.10 Time features are implemented, nor can they be as documented to work with scsh 0.7, which take rationals, I think we should be adding a sample code section to the srfi GitHub repository.

While I'm at it, I should mention that I took the liberty of renaming perms and mode to permission-bits after discovering that wonderful and explanatory usage elsewhere in the SRFI, that significantly decreases the need to document those argument.  This does preclude a read and then write version of set-file-mode like chmod(1), which really shouldn't be done at this level, but symbolic strings to bit mask conversion can and should be done with a helper procedure.

- Harold