scsh documentation

[reirob]

Hello,

I finally made it to compile scsh. And it seems to work. Then I started to look for a documentation of scsh on scsh.net and it says "The Scsh Manual, packed with the distribution, in various formats". As well in the same page it says there is a github repo https://github.com/rmloveland/scsh-manual-texinfo.

I think it would be great to provide the manual together with the scsh at least as text file, even better as a man page.

Disclaimer: I never programmed in Scheme or Lisp an it is my first github issue request, so please correct me if I missed something.

[roderyc]

You're right. I'll be writing documentation for this version of scsh before I release it. I'm wavering on what particular source format to use. Basing it on @rmloveland's work wouldn't be a bad idea though.

[samliddicott]

What source format does he use? I'm reading around his work and it ins
interesting but I don't find an answer to that question.

is it anything like this? http://readable.sourceforge.net/

Sam

On Thu, Jan 9, 2014 at 4:39 AM, Roderic Morris [email protected]:

You're right. I'll be writing documentation for this version of scsh
before I release it. I'm wavering on what particular source format to use.
Basing it on @rmloveland https://github.com/rmloveland's work wouldn't
be a bad idea though.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/10#issuecomment-31902419
.

[rmloveland]

The source format I used is Texinfo. I did the conversion because I wanted the scsh docs in Emacs so I could get all the nice `jump-to-procedure-documentation' things. I also remember Olin Shivers saying something about how it'd be cool to have a Texinfo version in a really old mailing list post -- I was only like ten years too late! :-}

I don't know how roderyc feels about Texinfo, but of course it will output to plain text (and HTML, PDF, etc.). However, I could understand a desire to keep the scsh docs as widely appealing and available as possible, in which case Texinfo might not be the best choice. (Leaving aside that whomever does the writing gets to write in whatever format they please, of course. :-})

If there's something useful I could do to help out with the new Scsh docs, I'd be glad to.

[snunez1]

+1 to the idea of being able to access the docos from within emacs.

On a related note: can sash do REST interfaces? I've got a lot of systems speaking JSON & XML via HTTP and need to integrate; ideally I could script them with scsh.

[snunez1]

So has anyone got a text file of the documentation? If not, is the best source still http://scsh.net/docu/html/man.html ?

[roderyc]

yes, that's still the best source. dev on the new version is happening in the docs branch.

[snunez1]

Great. If you point me to that branch I can update and/or file bugs on the
docs when I encounter them, assuming their far enough along for that.

From: Roderic Morris [email protected]
Reply-To: scheme/scsh
<reply+i-25180500-533fd1ac79817abac3757b73e95fb356b07eea3b-7775472@reply.git
hub.com>
Date: Friday, June 6, 2014 at 13:54
To: scheme/scsh [email protected]
Cc: Steve Nunez [email protected]
Subject: Re: [scsh] scsh documentation (#10)

yes, that's still the best source. dev on the new version is happening in
the docs branch.

‹
Reply to this email directly or view it on GitHub
#10 (comment) .

CONFIDENTIALITY NOTICE
NOTICE: This message is intended for the use of the individual or entity to
which it is addressed and may contain information that is confidential,
privileged and exempt from disclosure under applicable law. If the reader
of this message is not the intended recipient, you are hereby notified that
any printing, copying, dissemination, distribution, disclosure or
forwarding of this communication is strictly prohibited. If you have
received this communication in error, please contact the sender immediately
and delete it from your system. Thank You.

[roderyc]

They're not far along enough for that, but the branch is literally named docs if you want to follow along https://github.com/scheme/scsh/tree/docs

[spelufo]

I had found that online manual a while ago. I only now found this paper which makes for a much better introduction. I'd recommend linking to it in the readme.

Edit: Does markdown not show ftp:// links?? Here it is just in case: ftp://ftp.cs.indiana.edu/pub/scheme-repository/imp/scsh-paper.ps

[roderyc]

@spelufo you're right, that paper does a good job of giving color to the project. On the other hand it's from 1994 and doesn't target a modern audience. I'll try and incorporate elements of it into the new documentation.