Forum OpenACS Development: Suggested change to the API browser

Posted by Jamie Rasmussen on 08/20/02 01:36 PM

I've modified my copy of the API browser to output function bodies in color. I think it increases readability. (See sample screenshots with and without) The code was inspired by (but not based on) the tcl2html script from Jeff Hobbs. Both screenshots also have a lighter background than the source from CVS.

I'd like to see this as a new feature in 4.7. Obviously I like coloring enough to have it as the default, but it could toggle on a package parameter or something. Another advantage of doing this additional processing is that we could potentially turn the functions encountered into hyperlinks to their own docs, which would make for slightly faster browsing...

Of course, my function just does "best guess" coloring and not real TCL parsing, so it will sometimes color / not color things that I would / would not color. But I think it works pretty well overall. The only changes are 1 new function and modifying api_proc_documentation as showed in the screenshots. Is there anywhere else this function would be useful? Do you completely hate the idea? Let me know!

2: Response to Suggested change to the API browser (response to 1)

Posted by Lars Pind on 08/20/02 02:15 PM

Jamie,

I think it's excellent. I'd love to have this be the standard. I don't think there's any need to make this optional. Only it would be good if it's relatively easy to change the coloring through CSS once we get some CSS standard in place.

Making proc names links to the proc documentation would be fantastic.

/Lars

3: Response to Suggested change to the API browser (response to 1)

Posted by Lars Pind on 08/20/02 02:47 PM

Encouraged by your fiddling, I added a shortcut to the api browser, so you can now say:

foo.com/api-doc/proc/api_proc_documentation

or, in general,

yoursite.com/api-doc/proc/proc-name

to go straight to the documentation for your proc. Makes it slightly easier to use the API browser.

/Lars

4: Response to Suggested change to the API browser (response to 1)

Posted by Marc Spitzer on 08/20/02 03:58 PM

I would prefer to have an option to turn colors off. I honestly find it annoying when trying to look at and understand code. And since it is not a true parser it will not get things correct all the time so occasionaly it will bite you. The other improvement I like thanks for doing them. And thanks for doing the color also.

For me I have found color coding code to be a distraction when I am trying to read it. They cause context switches and make the parts of code much more seperate.

5: Response to Suggested change to the API browser (response to 1)

Posted by Jon Griffin on 08/20/02 04:05 PM

I just got done doing a first pass on fixing the badly formatted html and getting rid of the header/context_bar in the adp.

I love the color, but could you make sure you check out the latest version and apply to that?

Also, there are still a bunch of things to fix in the tcl file, and I didn't complete that, I am out of time.

6: Response to Suggested change to the API browser (response to 1)

Posted by Roberto Mello on 08/20/02 04:07 PM

I quite like the colors. I agree that it should be a toggable parameter (although Marc was the first person I've ever heard of that didn't like colors).

Is there any way to make the colors more accurate? We could take the regexps from vim (or emacs) for example (granted licensing allows), which have gone through quite a bit of testing and refining.

This will be great for when I generate PDFs out of the API docs, which I'm planning to do.

Thanks for doing this. Expecting your patch.

7: Response to Suggested change to the API browser (response to 1)

Posted by Jon Griffin on 08/20/02 04:07 PM

Also, I have a simple,cross platform css file that validates for everything but webtv. I will upload it later today and someone with more interest should be able to add/correct anything.

8: Response to Suggested change to the API browser (response to 1)

Posted by Jamie Rasmussen on 08/20/02 05:34 PM

If anyone wants to try out the function on their machine, I've put up a temporary copy at http://empoweringminds.mle.ie/temp/format_tcl.txt. It isn't as clean as it could be. I added proc hyperlinking for things that looked like AOLserver and OpenACS functions. Of course, not every OpenACS function is defined with ad_proc, so some of the links won't be helpful. I think it might be hard to extract the formatting code from text editors, but if someone finds/writes better regexps I'd be happy to use them.

I know Marc isn't the only one who would prefer no color, so maybe color would be the default but easily turned off. Assuming the hyperlinking works, should that also be configurable? Another reason for turning off the fancy formatting would be speed, though it seems fast enough to me.

Jon - I did see your changes. I'll make sure I'm using the most up-to-date CVS source when I submit my final patch. (Unless someone else wants to make the patch for me. 😊

I'm looking forward to seeing the PDF docs. BTW - does anyone know if the new website will allow visitors to browse the API online?

9: Response to Suggested change to the API browser (response to 1)

Posted by Marc Spitzer on 08/20/02 08:13 PM

I look at code as written text, so I try to read it and I feel that
color coding gets in the way of that. Imagine that you are reading a
book and the publisher colored the nouns blue, the verbs, green, the
adjectives yellow and so on for all the other classes of words you can
have in English. This would be much harder to read then plain black
text on white paper.

Another problem is that the way things are done now, regexps in vim &
emacs, is also a problem. This is because they are correct 99+% of
the time so you trust them, from personal experience this can lead to
great frustration, pain and suffering(for me any way).

The way to make the coloring more accurate is to write/borrow a parser
for your target language and use that as the basis for coloring your
output.

please one small favor, generate a black and white version of the
pdfs, color is bad enough but shades of grey can be even worse. I
like having printed docs to read.

I can see where color could be useful to check the structure of a
document, I do not care what it says just how it says it.

10: Response to Suggested change to the API browser (response to 1)

Posted by Jamie Rasmussen on 08/20/02 11:25 PM

You can easily be burned by lack of coloring too - On several occasions I've opened up a big C file in notepad, not noticed that a huge chunk of code was /* commented out */ ...

Clearly, coloring nouns and verbs in a novel would be ridiculous, but I see coloring code more like using larger boldtype for a section heading. It allows you to scan for content you're interested in. For example ad_proc has lots of escaped brackets and dollar signs. With colors I can tell at a glance which parts are evaluated immediately and which are destined for the uplevel. But I'm happy to make the formatting optional, I know not everyone works the same way I do. And I do think B&W mode could be useful for preparing printable docs.

Writing / borrowing a full parser might be the "correct" way to do this formatting, but it wouldn't be very easy to implement or incorporate into people's existing setups, even with something like ParseTools as a head start. And my code is parser-ish, it does some tracking of context (are we in quotes, a comment, etc.)

On a tangent, all of this talk of code formatting makes me want to start work on dotHACKER, a vertical app for software developers. We've got some of the building blocks already - the SDM, bug trackers, version control, an API browser. If we toss in some stuff for automated builds, maybe some graphical merging tools, we really could rival SourceForge. I'm halfway serious. 😊

11: Response to Suggested change to the API browser (response to 1)

Posted by Roberto Mello on 08/20/02 11:38 PM

We should make a lisst of these vertical apps and those wanting to build them.

I for one, would like to build dotLUG ((GNU/)Linux Users Group) on OpenACS. Everything that's needed to maintain a LUG is already in OpenACS, perhaps with the exception of a Cookbook package, which I'm already working on.

Perhaps we should call it dotUG (for Users Group) instead.

dotHacker would be great. I'm just afraid that the current trend of calling these vertical apps "dotTHIS" and "dotTHAT" (especially dotHACKER) is going to bring some marketing problems, since the "dot" immediatelly gives the impression of some based on or trying to ride on the hype wave of billions of M$ marketing for .NET (when in fact none of our applications currently make use of any of the .NET stuff, with the marginal exception of XML for the query dispatcher).

dotLRN is a different thing since Sloan came up with the name, but I would like to ask if we are that creatively-impaired that we can't come up with names that won't start with "dot". Unless people are really trying to ride on the .NET hype.

12: Response to Suggested change to the API browser (response to 1)

Posted by Marc Spitzer on 08/21/02 05:16 AM

I would have to agree that multline comments should be colored, when there is no comment charater for each line. Another place where coloring or even beter folding would be great is when you are working on code that has the same set of functions writen one per os, qpopper comes to mind, so that when you work on the solaris version of function foo() you did not waste time on the hpux version and then track down where the hell your changes went, what a royal pain.

13: Response to Suggested change to the API browser (response to 1)

Posted by defunct defunct on 08/21/02 09:45 AM

Roberto,

I strongly disagree wih your comments about riding off the .NET lingo...

dotLRN, dotWRK, dotHACK or whatever gives a nice common theme, implies relationships between the products and also gives the impression of coordinated marketing.

Furthermore the lukcy happenstance that .NET has a *similar* form can only serve to help raise the profile by accidental association.

And I don;t mean positive association... It wouldn't take more that about 2 mins for anyone to discover that this is not related to .NET in any way..... it just might server to give the impression thats its part of some higher dotX industry trend....

14: Response to Suggested change to the API browser (response to 1)

Posted by Marc Spitzer on 08/21/02 04:45 PM

so oacs can do "embrace and extend" too? yippie

15: Response to Suggested change to the API browser (response to 1)

Posted by Don Baccus on 08/21/02 05:06 PM

If we could just "extinguish" we'd be world heros!

16: Response to Suggested change to the API browser (response to 1)

Posted by Marc Spitzer on 08/21/02 07:27 PM

But think of all the harm that would do to linux. Many(not most) of the people involved in linux are fighting against MS not for linux, from what I have observed. Now if MS went away there would be an enemy vacuum that would cause them to go after the other distros. I can see it now "the linux wars" with the "storm" troopers etc.

It is a good thing I use freebsd.

17: Response to Suggested change to the API browser (response to 1)

Posted by Roberto Mello on 08/21/02 07:48 PM

"Many(not most) of the people involved in linux are fighting against MS not for linux, from what I have observed."

Well, you can say that about almost every group involved in some area of computing and tellecommunications, and that includes FreeBSD people.

"Half wits talk much, but say little" --Benjamin Franklin

18: Response to Suggested change to the API browser (response to 1)

Posted by Marc Spitzer on 08/21/02 09:05 PM

I am not saying it does not exist in freebsd, but I have seen much less of it. I do not go looking for it, so perhaps I have been lucky

And my comment was ment to be funny, perhaps I should have put in an "oh my?!?!?"

here are some others:

The Red Hats, goodwins law is not involved

The Slack Warriors

The Mandrake Roots

19: Response to Suggested change to the API browser (response to 1)

Posted by defunct defunct on 08/22/02 11:01 AM

Well.... if its War!!!!!!

I'm with the Mandrake's.... no seriously, I've upgraded to 8.2 recently and apart from Nutscrape 6 being its usual pain-in-the-arse-machine-killer, its a good distro !... Ho Ho ! Good bye Red Hat ;)

20: Response to Suggested change to the API browser (response to 1)

Posted by Marc Spitzer on 08/23/02 06:31 PM

On a completely related note, I just saw this on comp.lang.tcl:

Ho!

A couple of years ago I wrote a Tcl syntax checker which mostly has
been collecting dust since then.

I'm planning to do something with it so I have removed some of the
dust, called it v0.1 and released it for anyone interested:
http://spjuth.pointclark.net/Tcl.html

It does not even have a proper name yet, and lacks "a bit" in
documentation but it works well enough to be worth using before
starting a 30 hour synthesis script 😊

Some features:
* Written in pure Tcl.

* It's picky. It prefers to warn when in doubt so not to miss things.

* If you have a tool using Tcl as script language, you can extract
information like commands available to build a syntax database for
checking scripts for the tool.
E.g., I have used it to check Synopsys Design Compiler scripts.

/Peter

21: Response to Suggested change to the API browser (response to 1)

Posted by Jamie Rasmussen on 08/23/02 06:54 PM

Thanks for the link Marc. I downloaded the package and will try to look at it soon. In the meantime, I've put a slightly modified version of the proc up at the above address. I incorporated it into my setup with a "FancySourceFormattingP" parameter, so it can be easily turned off.

Since this is a new feature and not a bug fix, should I wait until after 4.6 is released to submit the patch? Or should I submit it now anyway?

22: Response to Suggested change to the API browser (response to 1)

Posted by Don Baccus on 08/23/02 07:17 PM

Submit it when you think it's mature. For instance if you're thinking of incorporating the syntax checker's basic parser in order to keep your colorer from getting fooled occasionally then we should wait. But if you've taken it as far as you want to take it, then submit it now ...

IMO at least. What do others think?

23: Response to Suggested change to the API browser (response to 1)

Posted by Jamie Rasmussen on 08/23/02 09:46 PM

To clarify, I'm mostly interested in seeing if the syntax checker has good test cases - I don't have any interest in modifying it for this task. If a function is being colored for api-doc then it presumably has no syntax problems. Plus, the syntax checker has lots of Tk stuff that we don't need, etc. It would be overkill.

Assuming nobody sends me bug reports before then, I'll submit the patch next week. If the patch becomes out-of-date because of Jon's fixes or something, I can make another. I'm still operating on the "default is to color" assumption, which seems to be the opinion of the majority of posters.