First let me emphasize I have not even confirmed the feasibility of this proposal, and that step one will be to confirm said feasibility. That said, having done this three times atop different window manager models, I have great confidence it can be done. So:
What if I base the Cells tutorials on the free LW downloads? If I can believe what I hear, it is portable across Mac OS X, Linux, and some other system called Window or something. :)
That will be a lot more fun than text-based tutorials like 01-cell-basics.lisp. Oh, speaking of which, did you all also find Bill Clementson's Cells write-up?:
http://home.comcast.net/~bc19191/2003_09_07_bill-clementson_archive.html
Not that I mean to send you on a scavenger hunt for Cells documentation, but if you are left with questions those will help me figure out what to explain first and in better detail.
kenny
I'd like to second that.
I'm using LW at work (read: woohoo!) and really enjoy it. The Hemlock (Emacs-like) editor realy rocks.
- Heow
On Mon, 2003-11-10 at 10:36, Kenny Tilton wrote:
First let me emphasize I have not even confirmed the feasibility of this proposal, and that step one will be to confirm said feasibility. That said, having done this three times atop different window manager models, I have great confidence it can be done. So:
What if I base the Cells tutorials on the free LW downloads? If I can believe what I hear, it is portable across Mac OS X, Linux, and some other system called Window or something. :)
That will be a lot more fun than text-based tutorials like 01-cell-basics.lisp. Oh, speaking of which, did you all also find Bill Clementson's Cells write-up?:
http://home.comcast.net/~bc19191/2003_09_07_bill-clementson_archive.htmlNot that I mean to send you on a scavenger hunt for Cells documentation, but if you are left with questions those will help me figure out what to explain first and in better detail.
kenny
-- http://tilton-technology.com
Why Lisp? http://alu.cliki.net/RtL%20Highlight%20Film
Your Project Here! http://alu.cliki.net/Industry%20Application
cells-devel site list cells-devel@common-lisp.net http://common-lisp.net/mailman/listinfo/cells-devel
Heow Eide-Goodman wrote:
I'd like to second that.
I'm using LW at work (read: woohoo!) and really enjoy it. The Hemlock (Emacs-like) editor realy rocks.
OK, and that is under Linux? Dumb Q, I know, just checking. I plan to DL the freebie for Mac OS X and check that out when I get done with the use case and Drew's music idea.
kt
On Mon, Nov 10, 2003 at 10:36:57AM -0500, Kenny Tilton wrote:
What if I base the Cells tutorials on the free LW downloads? If I can believe what I hear, it is portable across Mac OS X, Linux, and some other system called Window or something. :)
Maybe, but I'm not sure what the benefit would be.
That will be a lot more fun than text-based tutorials like 01-cell-basics.lisp.
By this I guess that you mean to do GUI-stuff as part of the tutorial, possibily CAPI?
IF so, I really think that that's a bad idea: I'd prefer to tackle one new thing at a time. If you had something different in mind, then dunno -- but the same applies: non-standard stuff besides the main subject of in a tutorial is a Bad Thing.
What I'd really like would be CLHS style docs for DEFMODEL, CV, C?, and friends...
Cheers,
-- Nikodemus
I have a feeling Kenny is talking about things like screen-shots and stuff. Cells is pretty portable, it's Cello that has the GUI bits.
...oh wait, are we talking about a Cells or Cello Tutorial? ...Kenny?
- Heow
On Mon, 2003-11-10 at 10:51, Nikodemus Siivola wrote:
On Mon, Nov 10, 2003 at 10:36:57AM -0500, Kenny Tilton wrote:
What if I base the Cells tutorials on the free LW downloads? If I can believe what I hear, it is portable across Mac OS X, Linux, and some other system called Window or something. :)
Maybe, but I'm not sure what the benefit would be.
That will be a lot more fun than text-based tutorials like 01-cell-basics.lisp.
By this I guess that you mean to do GUI-stuff as part of the tutorial, possibily CAPI?
IF so, I really think that that's a bad idea: I'd prefer to tackle one new thing at a time. If you had something different in mind, then dunno -- but the same applies: non-standard stuff besides the main subject of in a tutorial is a Bad Thing.
What I'd really like would be CLHS style docs for DEFMODEL, CV, C?, and friends...
Cheers,
-- Nikodemus
cells-devel site list cells-devel@common-lisp.net http://common-lisp.net/mailman/listinfo/cells-devel
Nikodemus Siivola wrote:
On Mon, Nov 10, 2003 at 10:36:57AM -0500, Kenny Tilton wrote:
What if I base the Cells tutorials on the free LW downloads? If I can believe what I hear, it is portable across Mac OS X, Linux, and some other system called Window or something. :)
Maybe, but I'm not sure what the benefit would be.
More fun? Graphical output which would be much more recognizable. Handling mouse and keydown input. Have you looked at the text-based examples? I guess they can serve for simple ideas (maybe I am onto something here), but then it is completely distanced from a real-world use. Hmmm, that would be a challenge. A text-only, real-world example on which to base a tutorial.
OK, I'll give it a go. I agree, it would be weird having the tutorial for something as fundamental as Cells tied up with LW having a free distro. (Hence the "shocking" in the proposal.)
That will be a lot more fun than text-based tutorials like 01-cell-basics.lisp.
By this I guess that you mean to do GUI-stuff as part of the tutorial, possibily CAPI?
IF so, I really think that that's a bad idea: I'd prefer to tackle one new thing at a time.
Trust me, you would /not/ be learning CAPI. I would, but only to a small degree. Even when I use an implementation-specific framework, I just use it to get a window, an event stream, and a bitmap to draw on. And that layer would just be provided for the tutorials, as in "First, load window-manager.lisp". Then it is all Cells all the time, using little more than the drawing primitives of CAPI (box, line, text).
If you had something different in mind, then dunno -- but the same applies: non-standard stuff besides the main subject of in a tutorial is a Bad Thing.
What I'd really like would be CLHS style docs for DEFMODEL, CV, C?, and friends...
That would be in the reference section, yes, agreed.
Do me a favor, let me know everyone what you think of the text-based tutorials on Bill's blog and in my own 01-cell-basics.lisp (and there is more if you want to look at the regression tests in the cells-test subdirectory or go to my web site and grab some old, obsolete PDFs).
One answer might be to clean up something like the boiler example (fairly realistic, that) which already covers all the basics. Then do up a similar level of reference material for those who just want to dive in and have some place to see all the options. Then start on an advanced tutorial in which I wed Cells to Lispworks CAPI. This will be very useful for those who want to use Cells with GTk or McClim or something else--I have done this exercise first with MCL's OS9 Quickdraw-wrappers, then with ACL Common Graphics, then with the Freeglut WIndow manager. Even if one is /not/ doing a GUI, the complexity of this will be enough to see how Cells scale to big problems, and given the LW ubiquity, it would not really be an obstacle to anyone that I am using a proprietary tool (in freebie form).
One unspoken issue here is that, if I base the more elaborate examples on Cello, well, Cello is so far just win32 ACL and LW, tho it is in principle portable to Linux and Mac OS X. A small voice tells me I will have to do all the porting myself, and even then I would only do OS X to get ready for my next entrepreneuial effort. Unless someone or ones step up to port Cello to Linux (unlikely) suddenly the more advanced tutorials are win32/OSX-only. (And I do think a GUI is necessary, tho I know the Linux crowd feels differently.)
Well, I see a compromise: cleaned up text-based tutorials that cover the basics, along with commensurate amount of indexed reference-style doc, followed by an advanced tutorial: "Integrating Cells with an Existing GUI Framework".
How's that?
kenny
ps. And please do let me know what you think about the existing intros.
k
On Mon, Nov 10, 2003 at 12:16:46PM -0500, Kenny Tilton wrote:
More fun? Graphical output which would be much more recognizable. Handling mouse and keydown input.
Fair enough. Never having written a GUI app in my life I'm always left a bit cold by GUI examples, but basically they're fine.
Have you looked at the text-based examples?
Yes, comments below.
Hmmm, that would be a challenge. A text-only, real-world example on which to base a tutorial.
Almost any simulation would seem plausible.
Do me a favor, let me know everyone what you think of the text-based tutorials on Bill's blog and in my own 01-cell-basics.lisp (and there is
Looking at 01-cell-basics.lisp.
The terminology is somewhat confusing. For example:
"C? associates a rule with a cellular slot (or "cell", for short)."
Which really doesn't make sense to me: it doesn't seems to associate anything with anything, but rather (as far as I can tell so far) *creates* a rule that can then be associated with a cell.
Nowhere do I see a short explanation of the basic consepts: What are rules and cells? How do they relate to each other? It's easy enough to pick up the basics of "howto", but really hard to understand the "why".
Example: I look at an example on defmodel, and see how SELF seems to be bound by it for :default-initargs. Except that this bit of anaphora seems to be done by C?...
A non-documentation-related nitpick: I find myself mentally skipping over C?, CV, &co constantly, since the names look like internal iteration or pattern matching variable names...
I'd personally prefer
(cell-lambda (foo) ...)
or equivalent over C? with implicit lexical bindings, and DEFINE-CELL-ECHO over DEF-C-ECHO, etc...
But I'm just funny that way. ,)=
One answer might be to clean up something like the boiler example (fairly realistic, that) which already covers all the basics. Then do up a similar level of reference material for those who just want to dive in and have some place to see all the options.
Sounds sensible. Except that I'd prioritize that reference. Very often when reading a given tutorial I like to refer to an actual reference every once and a while to check if I'm understanding things correctly.
Even if one is /not/ doing a GUI, the complexity of this will be enough to see how Cells scale to big problems, and given the LW ubiquity, it would not really be an obstacle to anyone that I am using a proprietary tool (in freebie form).
True. Though I'm surprised if you really need to sell the scalability very hard. Especially since I think that if there are doubts about scalability they would/should be focused on huge nets and simulations, not interface.complexity... ;)
Cheers,
-- Nikodemus
Nikodemus Siivola wrote:
On Mon, Nov 10, 2003 at 12:16:46PM -0500, Kenny Tilton wrote:
More fun? Graphical output which would be much more recognizable. Handling mouse and keydown input.
Fair enough. Never having written a GUI app in my life I'm always left a bit cold by GUI examples, but basically they're fine.
Don't worry, I am not talking about doing a boring GUI example, I am talking about having neat visual effects and clear relationships thanks to the fact that I can draw pretty shapes on the screen that change as you tweak parameters from the repl. For example we can have a container with a fixed number of moles of a gas. we can manifest the temperature via color, moving gradually from blue to red to show gradations of increasing temperature. We'll use Boyle's Law in a rule somewhere, then let the size of the container be mediated by a cell-variable. Then we can setf that value from the repl, see the container get smaller, see the temperature increase. Then maybe we put a goofy thermometer above the box. That has a column of mercury which increases in length as the temperature below increases, but maybe we do that over time (using a new kind of synapse I think I have to invent <g>) or maybe I can do it as a drifter. I can also show how I position the thermometer over the container without calculating actual coordinates. Stuff like that.
Have you looked at the text-based examples?
Yes, comments below.
Hmmm, that would be a challenge. A text-only, real-world example on which to base a tutorial.
Almost any simulation would seem plausible.
Do me a favor, let me know everyone what you think of the text-based tutorials on Bill's blog and in my own 01-cell-basics.lisp (and there is
Looking at 01-cell-basics.lisp.
The terminology is somewhat confusing. For example:
"C? associates a rule with a cellular slot (or "cell", for short)."
Which really doesn't make sense to me: it doesn't seems to associate anything with anything, but rather (as far as I can tell so far) *creates* a rule that can then be associated with a cell.
True. I'll reword that.
Nowhere do I see a short explanation of the basic consepts: What are rules and cells? How do they relate to each other? It's easy enough to pick up the basics of "howto", but really hard to understand the "why".
Example: I look at an example on defmodel, and see how SELF seems to be bound by it for :default-initargs. Except that this bit of anaphora seems to be done by C?...
No, defmodel does not do anything like that, and any anaphoric SELF appears inside a rule. I also use self as parameter names a lot, but then there is no anaphoric mystery.
defmodel is just defclass, plus it writes macros ^slot and accessors slot and (setf slot).
A non-documentation-related nitpick: I find myself mentally skipping over C?, CV, &co constantly, since the names look like internal iteration or pattern matching variable names...
I'd personally prefer
(cell-lambda (foo) ...)
or equivalent over C? with implicit lexical bindings, and DEFINE-CELL-ECHO over DEF-C-ECHO, etc...
But I'm just funny that way. ,)=
Well I am a long-name freak myself, but when it comes down to something I will be using a lot I turn into an APL clone. Esp. because I will be using them a lot, there is no confusion. Meanwhile they do not take up a lot of space.
One answer might be to clean up something like the boiler example (fairly realistic, that) which already covers all the basics. Then do up a similar level of reference material for those who just want to dive in and have some place to see all the options.
Sounds sensible. Except that I'd prioritize that reference. Very often when reading a given tutorial I like to refer to an actual reference every once and a while to check if I'm understanding things correctly.
Probably once I sit down to do the reference I will scoot thru all the syntax at once. that is a lot easier than writing tutorials and worrying about whether the tutee is keeping up.
Even if one is /not/ doing a GUI, the complexity of this will be enough to see how Cells scale to big problems, and given the LW ubiquity, it would not really be an obstacle to anyone that I am using a proprietary tool (in freebie form).
True. Though I'm surprised if you really need to sell the scalability very hard. Especially since I think that if there are doubts about scalability they would/should be focused on huge nets and simulations, not interface.complexity... ;)
Well, there is scaling and there is scaling. Your example (many, many similar elements) gets at performance. Mine gets at what happens when a neat hack is asked to manage greater and greater varieties of things, and the functional dependencies become more and more semantically diverse.
Cells have overhead in tracking dependencies, so they do fine in the latter case (for which they were developed) where complexity arises from great variety amongst relatively few instances), but I imagine they will not be appropriate for something like the game of Life, where they add very little value (it's a pretty simple algorithm, with very clear dependencies and ways to identify on the fly said dependencies, zero variety (all Life cells work the same), and even change is completely simple: all cells get recalculated at the same time in one generational step.
Good input. Thanks.
kenny
On Mon, 10 Nov 2003 15:15:10 -0500, Kenny Tilton ktilton@nyc.rr.com wrote:
Don't worry, I am not talking about doing a boring GUI example, I am talking about having neat visual effects and clear relationships thanks to the fact that I can draw pretty shapes on the screen that change as you tweak parameters from the repl. For example we can have a container with a fixed number of moles of a gas. we can manifest the temperature via color, moving gradually from blue to red to show gradations of increasing temperature. We'll use Boyle's Law in a rule somewhere, then let the size of the container be mediated by a cell-variable. Then we can setf that value from the repl, see the container get smaller, see the temperature increase. Then maybe we put a goofy thermometer above the box. That has a column of mercury which increases in length as the temperature below increases, but maybe we do that over time (using a new kind of synapse I think I have to invent <g>) or maybe I can do it as a drifter. I can also show how I position the thermometer over the container without calculating actual coordinates. Stuff like that.
Sounds like a very good idea to me - I like it!
I also think that using the LW CAPI would be the right choice. You'd get graphical examples which would work on the three major platforms (and even on FreeBSD with the Linux compatibility layer) without the users needing to go through some installation nightmare.
I'm all for it. Go Kenny!!
Edi.
Do me a favor, let me know everyone what you think of the text-based tutorials on Bill's blog and in my own 01-cell-basics.lisp (and there is more if you want to look at the regression tests in the cells-test subdirectory or go to my web site and grab some old, obsolete PDFs).
I liked your 01-cell-basics.lisp as it gave a first feeling of what cells is about also I liked Bill's one as it introduced the idea of filtering the values before using them (something that obviously needs doing in a real world problem but that I had no idea, nor I would have expected, you had implemented).
However as side problem with Bill's example I never got to see the status of the pump on closed from a def-c-echo call until when at the end I called (status *motor1*) and everything updated. It wasn't clear if the reason was the filtering or something else.
The problem with 01-cell-basic is that it is indeed quite basic so things like drifters are not introduced, nor filtering, nor any other goodies you are currently hiding in your source code.
So yeah they are good but only to get a first inkling of the potential of your system. However I haven't looked at your test directory in detail yet nor at the other pdfs on your site.
Side Note: in your most recent release you still have a `while' that is incompatible with acl (I replaced it with acl:while although you mentioned that changing it to a do will make it portable) which is present in the data-flow source file.
Regarding linking cells to LW, well I have got a copy of LW Personal installed on my computer as I wanted to give it a look however after having started it I was already missing my acl (although older version). So I don't know it might be a good chance for me too look back at LW then again it might not.
One unspoken issue here is that, if I base the more elaborate examples on Cello, well, Cello is so far just win32 ACL and LW, tho it is in principle portable to Linux and Mac OS X. A small voice tells me I will have to do all the porting myself, and even then I would only do OS X to get ready for my next entrepreneuial effort. Unless someone or ones step up to port Cello to Linux (unlikely) suddenly the more advanced tutorials are win32/OSX-only. (And I do think a GUI is necessary, tho I know the Linux crowd feels differently.)
Well linking Cells tutorial to Cello (and ACL and LW) I would like that though I appreciate that not using Linux I am not entirely impartial ;) However I was just wondering is there not a demo of ACL running on Linux? and if so is the GUI linkages so different that Cello would not run on it?
rmagere
Raistlin Magere wrote:
Do me a favor, let me know everyone what you think of the text-based tutorials on Bill's blog and in my own 01-cell-basics.lisp (and there is more if you want to look at the regression tests in the cells-test subdirectory or go to my web site and grab some old, obsolete PDFs).
I liked your 01-cell-basics.lisp as it gave a first feeling of what cells is about also I liked Bill's one as it introduced the idea of filtering the values before using them (something that obviously needs doing in a real world problem but that I had no idea, nor I would have expected, you had implemented).
You're the second person who liked synapses. That came up when I did a physics sim of a pendulum and I needed to optimize a little. Lots of potential in those little critters, for expressiveness as well as performance. User-definable as well.
However as side problem with Bill's example I never got to see the status of the pump on closed from a def-c-echo call until when at the end I called (status *motor1*) and everything updated. It wasn't clear if the reason was the filtering or something else.
OK. As I roll out the tutorials I will solicit feedback form everyone to refine them. I did do that with 01-cell-basics, but it was just one reviewer.
The problem with 01-cell-basic is that it is indeed quite basic so things like drifters are not introduced, nor filtering, nor any other goodies you are currently hiding in your source code.
<heh-heh> I should have known that early adopters would want the crash course and not the gradual buildup to razzle-dazzle stuff.
So yeah they are good but only to get a first inkling of the potential of your system. However I haven't looked at your test directory in detail yet nor at the other pdfs on your site.
yeah, there's good stuff sprinkled all over, including in the cells-test regression suite. Gotta pull it all into one place and add a reference.
Side Note: in your most recent release you still have a `while' ..
Damn, I had a feeling I had done that. Now if I only new CVS! lesse:
Soon.
that is incompatible with acl (I replaced it with acl:while although you mentioned that changing it to a do will make it portable) which is present in the data-flow source file.
Regarding linking cells to LW, well I have got a copy of LW Personal installed on my computer as I wanted to give it a look however after having started it I was already missing my acl (although older version).
yep. may I can featurize the examples for ACL and MCL, too, since both are already done. I'd just have to bury them under a common framework.
Well linking Cells tutorial to Cello (and ACL and LW) I would like that though I appreciate that not using Linux I am not entirely impartial ;) However I was just wondering is there not a demo of ACL running on Linux? and if so is the GUI linkages so different that Cello would not run on it?
I am pretty sure they have not yet ported Common Graphics, their CAPI, to Linux.
kenny
Kenny Tilton ktilton@nyc.rr.com writes:
Unless someone or ones step up to port Cello to Linux (unlikely) suddenly the more advanced tutorials are win32/OSX-only. (And I do think a GUI is necessary, tho I know the Linux crowd feels differently.)
I'll try porting Cello to Linux if no one else steps up.
Kenny Tilton ktilton@nyc.rr.com writes:
That will be a lot more fun than text-based tutorials like 01-cell-basics.lisp. Oh, speaking of which, did you all also find Bill Clementson's Cells write-up?:
http://home.comcast.net/~bc19191/2003_09_07_bill-clementson_archive.html
I think the sample run could have been better designed, it would have been more clear if the temperature dropped enough to turn the motor back on.
As it is, I had to look closely and do the math in my head to see that the motor stayed off when the temperature dropped below 100 because of the synapse sensitivity.
Perhaps something like this would be better
(setf (temp *motor1*) 99.8)
;; on each iteration the motor heats up if it's on ;; or cools down if it's off (loop :repeat 10 :do (if (eq (status *motor1*) :on) (incf (temp *motor1*) 0.06) (decf (temp *motor1*) 0.03)))
Just my 2c, incase you planning on using the same example.
jan wrote:
Kenny Tilton ktilton@nyc.rr.com writes:
That will be a lot more fun than text-based tutorials like 01-cell-basics.lisp. Oh, speaking of which, did you all also find Bill Clementson's Cells write-up?:
http://home.comcast.net/~bc19191/2003_09_07_bill-clementson_archive.html
I think the sample run could have been better designed, it would have been more clear if the temperature dropped enough to turn the motor back on.
Oh, I did not notice that--Bill actually cloned one of my examples, so I just perused it.
You are right, it is important to show that once the sensitivity is exceeded the synapse lets the message through. And in case you are wondering, this is not a frog in the frying pan situation (allegedly frogs only can sense a delta, so if you increase the heat slowly it will not notice and come to grief); the synapse keeps track of the last time it let a signal thru, and each time the sensitivity check is not between the immediately prior value and the current value, but between the current value and the last time the synapse let a change thru.
uh, I hasten to add that that is how fSensitivity works in particular. One could just as easily code up an fFrog synapse which ignored the cumulative change and worried only about jumps between two concecutive readings. These things are wholly user programmable. They have to answer two questions:
1. Given this new value of a particular cell used in a calculation, should the using cell be recalculated?
2. Given this new value, what value should be returned when the using cell re-samples the changed cell?
kenny
ps. excellent start on the use case today, with all sorts of good stuff going into it. I am branching lefty and right, touching on a lot of considerations. I am not one for reading doc, but if you sit down with this and make sure you follow it, I think a pretty deep understanding of Cells will follow. It is probably too much for a tutorial approach, but I sense the early-adopters on board right now are more pissed off by than appreciative of hand-holding. So I am really not holding back in this particular write-up, though I am trying to spell everything out so that there are no gaps.
kt
Ok, this time it is in the Cells FTP directory:
ftp://common-lisp.net/pub/project/cells/uc-ring-net.pdf ftp://common-lisp.net/pub/project/cells/uc-ring-net.sig (signature if desired)
That is a very rough draft of a great little use case with a surprise ending I (still) won't give away. I am going to spend a little time now cleaning up the demo code of the solution. In the meantime feel free to request clarifications. Don't worry about proofreading stuff -- I did not even run spellcheck on it yet.
After this I will produce text-based tutorials of all Cell functionality (probably in the form of readable source ala "literate programming") and a corresponding reference section (PDF again).
kt
Kenny Tilton wrote:
Ok, this time it is in the Cells FTP directory:
ftp://common-lisp.net/pub/project/cells/uc-ring-net.pdf ftp://common-lisp.net/pub/project/cells/uc-ring-net.sig (signature if desired)
The URLs above still work but are deprecated. When I added:
ftp://common-lisp.net/pub/project/cells/use-case/uc-ring-net.lisp ftp://common-lisp.net/pub/project/cells/use-case/uc-ring-net.lisp.sig (signature if desired)
I created, as can be seen, a separate subdirectory for use-cases (so I guess the "uc-" prefix is deprecated as well), and the PDF got moved there as well.
kenny
Kenny Tilton writes:
Kenny Tilton wrote:
Ok, this time it is in the Cells FTP directory:
ftp://common-lisp.net/pub/project/cells/uc-ring-net.pdf ftp://common-lisp.net/pub/project/cells/uc-ring-net.sig (signature if desired)
The URLs above still work but are deprecated. When I added:
ftp://common-lisp.net/pub/project/cells/use-case/uc-ring-net.lisp ftp://common-lisp.net/pub/project/cells/use-case/uc-ring-net.lisp.sig
I removed the deprecated files, and made them symbolic links to the new ones. Kind of as a UI experiment: does WinSCP display this in a reasonable way? Can you see what's going on? Symlinks are a quotidian thing on Unix is why I'm asking...
On Wed, Nov 12, 2003 at 10:37:47PM -0500, Kenny Tilton wrote:
That is a very rough draft of a great little use case with a surprise
Great! I'll read it later today.
a corresponding reference section (PDF again).
Urk. PDF really sucks as a reference document: hard to convert to other formats, not browsable from within Emacs, etc.
Could you do HTML or plain text as well, or even better: TeX/LaTeX (or even Docbook) instead?
As far as formats go, they also have the advantage that you can meaningfully manage them with CVS.
The latter trio also allow you to generate both PDF, PS, HTML, and whatnot on demand, which is a Good Thing.
Cheers,
-- Nikodemus
Nikodemus Siivola wrote:
a corresponding reference section (PDF again).
Urk. PDF really sucks as a reference document: hard to convert to other formats, not browsable from within Emacs, etc.
Could you do HTML or plain text as well, or even better: TeX/LaTeX (or even Docbook) instead?
Adobe FrameMaker exports HTML, plain text, RTF, XML, Word... the HTML and RTF fail on the fancier formatting stuff, but I can simply avoid the fancier stuff while authoring. I'll take a look at LaTex, but I have heard that stuff has a learning curve. If I find a wysiwyg editor I'll give it a go, otherwise I better apply some triage.
Come to think of it, HTML butchered not just the fancy stuff but also the ascii picture of the network, as well as the layout of the code. Probably the tab characters. PDF does have its advantages.
btw, I am going to spend some time today boning up on FrameMaker indexing and TOC capabilities, then start on a reference. Between 01-cell-basics.lisp, Bill C's blog, the old doc at tilton-technology.com, and the test suite in cells-test, I think the intro thing is well-covered. It needs to be pulled together into one document, but there is more added value I think at this point in a reference, since that simply does not exist at all right now.
kt
On Thu, Nov 13, 2003 at 07:53:19AM -0500, Kenny Tilton wrote:
and RTF fail on the fancier formatting stuff, but I can simply avoid the fancier stuff while authoring. I'll take a look at LaTex, but I have heard that stuff has a learning curve. If I find a wysiwyg editor I'll give it a go, otherwise I better apply some triage.
Fair enough. Also, I think PDF is just fine for tutorials, etc. It's just the refence documentation that really needs a proper stuctural format.
LaTeX &co do have a learning curve, yes.
Cheers,
-- Nikodemus
I'm not very shocked. I think it's a good idea -- especially since it sounds like the level of graphical sophistication would be very low, so people could port it to whatever Lisp system they'd like to use, if they really feel so inclined.
Not that I mean to send you on a scavenger hunt for Cells documentation, but if you are left with questions those will help me figure out what to explain first and in better detail.
A bomb tutorial would be good for drawing more people in, and might not be a bad way of introducing people to Good Cells Syle. However, reference docs would be really nice. I ran my DocoSketch program over Cells, and posted the results here:
http://www.ocf.berkeley.edu/~tfb/no-carrier/cells/cells-docosketch.txt http://www.ocf.berkeley.edu/~tfb/no-carrier/cells/cells-docosketch.sexp
[ The first is a text file for viewing by Emacs outline-mode. The second is the data structure it was generated from. ]
DocoSketch is a little package I have that's meant as a way of browsing a loaded system, not so much for generating actual documentation, but it might be helpful as an outline for a dictionary section like in the HyperSpec. If other people think it's a good idea, I could massage it into a Wiki, so we could all work on documenting it.
On Mon, Nov 10, 2003 at 10:42:59PM -0800, Thomas F. Burdick wrote:
DocoSketch is a little package I have that's meant as a way of
...
section like in the HyperSpec. If other people think it's a good idea, I could massage it into a Wiki, so we could all work on documenting it.
I say yay! I have my own 20-liner ad-hoc-doc for making READMEs, but DocoSketch seems quite a bit more capable.
Albert is getting quite sophisticated as well, but something that works on the image as opposed to sources smells sweeter to me.
Cheers,
-- Nikodemus
Nikodemus Siivola writes:
On Mon, Nov 10, 2003 at 10:42:59PM -0800, Thomas F. Burdick wrote:
DocoSketch is a little package I have that's meant as a way of
...
section like in the HyperSpec. If other people think it's a good idea, I could massage it into a Wiki, so we could all work on documenting it.
I say yay! I have my own 20-liner ad-hoc-doc for making READMEs, but DocoSketch seems quite a bit more capable.
Mine's a wee bit longer: DocoSketch itself is about 100 lines, and docosketch-outline is a 100-line run-on function.
Albert is getting quite sophisticated as well, but something that works on the image as opposed to sources smells sweeter to me.
Yeah, I've never been very impressed with documentation generators that munge Lisp as text. We've got all that introspection for a reason! I've developed DocoSketch on an as-needed basis, so it's still lacking in a few spots, mostly it should make better use of the MOP to descend into classes and generic functions better.
I noticed that I had commented out the code that checks for specialness (oops!), so I added that back in, and now it gets the unbound variables, too. I updated the files on my website with the new output.
-
Edi Weitz -
Heow Eide-Goodman -
jan -
Kenny Tilton -
Nikodemus Siivola -
Raistlin Magere -
Thomas F. Burdick