Documentation options

>>>>> "Igor" == Igor Stasenko <[hidden email]> writes:

Igor> As i suspected, this discussion is going to nowhere, because of
Igor> conservative people like you.
Igor> There is no point to prove anything, if people simply don't want to
Igor> change anything.

And you're swinging to the extreme as well.  I'm all for change, but the
change to fundamental syntax and toolchain has a very high bar to jump for me.

Especially when options are *already* being proposed.  I like the idea of
teaching the browser to "[un]paste as comment" or "[un]comment this region",
doing the proper escaping and such.  Keep in mind that we already have a way
of uniquely putting a double-quote in a comment in the same way that we can
put a single quote in a string... just double it up!

I've also suggested other things in this thread and others.

Class comments are underutilized.  Let's start by at least putting
unstructured English in there.  That would help quite a bit.

However, we could also put *structures* into the class comments, as long as it
was backward compatible.  Maybe some form of wiki markup (Pier? Perl's POD?
ASCIIDOC?)  so that it could be mechanically translated when necessary.

I'd caution against overkill in this area though.  If it's difficult to use or
learn, IT WILL NOT BE USED by the very wide variety of folks that you need to
use it to make it a success.

I don't believe well-written methods need a lot of comments, so I'm unsure
what the drive is to get more structure into the methods.  However, I think
some proposal to have recognizable structure in a method comment would also be
interesting.

So, no, I'm not against change.  But I'm also practical.  Changing the
language means that we break compatibility with the past, and with other
smalltalks.  Smalltalk is about to have its second golden era.  Let's not kill
that before it starts.

--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<[hidden email]> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!

I think, reserving a slot in CompiledMethod and in Class(es) for
documentation is better way.
Simply put there any object , which should answer #show message. And
then you can attach anything you like: URL, in-image PDF or
whatever...
> cheers
>
> Keith
>
>


--
Best regards,
Igor Stasenko AKA sig.

On 2-Jan-08, at 10:09 AM, Tony Garnock-Jones wrote:
>
>
> Then I went looking. CompiledMethod is a direct subclass of ByteArray,
> and has no instance variables.


Yes, there have been plans to fix that for years but the work to do  
(what was once a simple change) is sufficiently complicated by traits,  
existing .pr files, tool related hacks and so on that it has become a  
major change that would require considerable resources. I tried again  
last year but it just grew into too much work.

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
"Both.." said Pooh, as the guillotine came down

>>>>> "tim" == tim Rowledge <[hidden email]> writes:

tim> Yes, there have been plans to fix that for years but the work to do  (what was
tim> once a simple change) is sufficiently complicated by traits,  existing .pr
tim> files, tool related hacks and so on that it has become a  major change that
tim> would require considerable resources. I tried again  last year but it just
tim> grew into too much work.

Of course, we could have a global WeakDictionary keyed by CompiledMethod
that has whatever bolt-on payload we want for a documentation system.  That'd
be an upward compatible extension without affecting the naive
compiler/debugger/everything-else toolchain.

--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<[hidden email]> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!

On 02/01/2008, tim Rowledge <[hidden email]> wrote: Btw, this is one of the biggest things what i dislike in squeak.

As CompiledMethod class comment reads:
"My instances are methods suitable for interpretation by the virtual
machine.  This is the only class in the system whose instances
intermix both indexable pointer fields and indexable integer fields."

There is a lot of dirty hacks around this in VM, around attaching a
reference to source code, around using primitive index (FFI/external
prims)..
Lot of stinking code, just to make it working properly, and very hard
to add anything new.
How this can be called a 'standard' by any means?
Are we brave enough to fix things which holding progress? Any chance?

--
Best regards,
Igor Stasenko AKA sig.

 > without affecting the naive compiler/debugger/everything-else
 > toolchain.

      Nice typo. :)


-C

--
Craig Latta
improvisational musical informaticist
www.netjam.org
Smalltalkers do: [:it | All with: Class, (And love: it)]

On 2-Jan-08, at 10:33 AM, Igor Stasenko wrote:
>
> Lot of stinking code, just to make it working properly, and very hard
> to add anything new.
> How this can be called a 'standard' by any means?
Read your Blue Book; this *is* that standard way of doing it.

How to fix CompiledMethods is not an issue, how to move to using the  
fixed stuff without breaking every image out there and pissing off  
everyone with old .pr file or imagesegments etc is the problem. Anyone  
that can come up with a good plan and some way to make time available  
really should speak up.

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Useful random insult:- Mind like a steel sieve.

>>>>> "Craig" == Craig Latta <[hidden email]> writes:

>> without affecting the naive compiler/debugger/everything-else
>> toolchain.

Craig>      Nice typo. :)

Where's the typo?  I really did mean "naive" as in "unaware".  If you have an
advanced doc system that can run without changing a single line of the
existing tool chain, it'd get *my* vote for sure.

--
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<[hidden email]> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!

On Wed, 02 Jan 2008 19:33:11 +0100, Igor Stasenko wrote:

Are you aware of the consequences of such dislikeness? :) CompiledMethod  
has a dozen or so accessors which, to the average Smalltalk developer are  
"gettable" instance variables (some are even "settable").

Encapsulation rules! :)

You dislike accessors? :) Try adding a new one to CompiledMethod. Still  
dislike accessors ? :)

/Klaus

On 02/01/2008, Klaus D. Witzel <[hidden email]> wrote: Yes, it is. But if you know, compiled methods are well-known objects
handled by VM.

The current format of a CompiledMethod is as follows:
        header (4 bytes)
        literals (4 bytes each)
        bytecodes  (variable)
        trailer (variable)

now, suppose you want to add new field, called 'docs' or whatever.
Where would you put it?
- In literals? Good. Then you need to reserve a literal with a proper
index for it? And this will interfere with FFI/External primitive
literals.
- In trailer bytes (after bytecode) - then you interfere with
reference to source code. Also, your reference will be not visible by
GC.

Is there places left, where you can reserve a slot and put a reference
to object in it?
NONE.
You can write thousands of accessors, but without having something
which you can access to. :)

And now, think what if we change compiled method to have any (by
subclassing) number of named vars, and bytecode as indexed  vars. Then
each thing will find own place to live and will not interfere with
others, and you don't need a black magic in GC to handle compiled
methods differently than other objects.


--
Best regards,
Igor Stasenko AKA sig.

 > I really did mean "naive" as in "unaware".

      Even better. :)  (that you didn't mean to type "native")


-C

--
Craig Latta
improvisational musical informaticist
www.netjam.org
Smalltalkers do: [:it | All with: Class, (And love: it)]

 
> now, suppose you want to add new field, called 'docs' or whatever
>  
> Where would you put it?

Adding a new field would defeat the object. That being to facilitate
managing snippets of documentation
with the existing tools.

There are already slots for additional metadata, #pragma's and method
properties.

I am still searching for some answers to my original questions.

1. can I override #compilerClass used for class side methods.
2. can I switch off the syntax highlighting on a per class basis.

If 1. can be answered in the affirmative, I dont see that any changes to
the existing tool chain are required.

Keith

Igor Stasenko wrote:
> Is there places left, where you can reserve a slot and put a reference
> to object in it?

MethodProperties. It's the right place for it. You can add as many ivars
as Squeak supports and all you need is a delegate accessor in
CompiledMethod.

Cheers,
   - Andreas

On 02/01/2008, Andreas Raab <[hidden email]> wrote:
> Igor Stasenko wrote:
> > Is there places left, where you can reserve a slot and put a reference
> > to object in it?
>
> MethodProperties. It's the right place for it. You can add as many ivars
> as Squeak supports and all you need is a delegate accessor in
> CompiledMethod.
>

Yes, i agree.
Sorry, forgot about that.



--
Best regards,
Igor Stasenko AKA sig.

Why is necessary to add new properties to a CompiledMethod just for  
the documentation?

To handle that documentation properties you would need a browser aware  
of that. So why just not use a global to hold the documentation:

SmalltalkDocumentation for: MyClass>>#method is: 'Hello world!'.

Then this special browser just need to access to  
SmalltalkDocumentation...
This solution could be ported easily to other smalltalks.


On Jan 2, 2008, at 11:11 PM, Igor Stasenko wrote:

On Wed, 02 Jan 2008 22:22:43 +0100, Andreas Raab wrote:

> Igor Stasenko wrote:
>> Is there places left, where you can reserve a slot and put a reference
>> to object in it?
>
> MethodProperties. It's the right place for it. You can add as many ivars  
> as Squeak supports and all you need is a delegate accessor in  
> CompiledMethod.

Sh*t :) attempted to let Igor find out himself, and now? :)

> Cheers,
>    - Andreas
>
>

"Klaus D. Witzel" <[hidden email]> wrote in message

> some time ago I tried to convince people  to make available
> auto-generated, web searchable sourcecode pages from all public Squeak
> repositories

+1

Like this
http://common-lisp.net/project/cl-weblocks/docs/weblocks-package/index.html 
sample from a Lisp web framework - it made it so easy to access and browse
something without having to download, install, and poke around in an IDE.

On 3-Jan-08, at 9:14 AM, itsme213 wrote:
That's such a 19th century approach. Why would anyone want to have a  
fixed linear view of a mesh entity dynamic system?

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Strange OpCodes: IA: Illogical And

On 03/01/2008, Klaus D. Witzel <[hidden email]> wrote: Yes, i forgot about method properties.. memory failed me, it was a
half-year ago when i did some hacking with compiler.
I'm also had somewhat biased after looking how FFI/External primitives
work.. it's a pain seeing how much work needed for VM to extract
simple data from method to invoke primitive.


--
Best regards,
Igor Stasenko AKA sig.

"tim Rowledge" <[hidden email]> wrote

>> Like this
>> http://common-lisp.net/project/cl-weblocks/docs/weblocks-package/index.html
>> sample from a Lisp web framework - it made it so easy to access and
>> browse
>> something without having to download, install, and poke around in an
>> IDE.
> That's such a 19th century approach. Why would anyone want to have a
> fixed linear view of a mesh entity dynamic system?

In my case it was because I was not familiar with the package, wanted to get
a general feel for its structure, and did not want to download and install
(in this case, even into a new unfamiliar IDE).

Not an uncommon situation, I would think.

Why would you call hyperlinked documentation a fixed linear view?

Sophie