Would a getting started guide help
Erik Lechak
I hope this is the correct place for my post. I have not seen many (or
any) newbie parrot questions on this group. Please direct me to the
correct group and forgive my intrusion if this message is misposted.
I would like to start helping in the development of parrot. I have read
the documentation, the design docs, and went over the source, but I am
still a little lost. I would eventually like to help with the coding,
but it appears that there may be a pressing need for a document helping
newbie developers figure out how to get started. I would be willing to
take on this task (Well at least until I learn enough so that I can code.)
1)If you would like me to do it, who would I send the document and its
updates to?
2)I am a diagram oriented person. If I include diagrams (gifs, png ...)
in the document, how would you want me to do this (html, ref the image
file ...)? Any prefs in the image format?
3)Do I have to use pod? No offense, but I can't stand pod. The pdd
design document states that pod is the "...documentation language for
All Things Perl", but this is Parrot not Perl. And this document would
not be a design doc. If Parrot is supposed to be a cross language VM,
why do people need to know pod to read (or write) the docs? I know that
it is easy to convert pod to an easy to read format, but would a
developer with little perl experience know that? Parrot is trying to
encourage developers from areas other than perl, so why discourage them
by introducing them to parrot with pod documents.
Could there possibly be a parrot comment style? It could be used
instead of other comment styles internal to parrot. Use it in the
c-code, the perl code, the parrot assembly code, and to write the
documentation. Then a (perl) preprocessor could strip it out before it
is compiled or run. Normally I would not suggest such a thing, but
there is a lot of code generation and manipulation going on anyway. It
could allow for document generation of all the parrot source, assembly,
tests, and documents into a javadoc-like html reference. Or maybe I'm
just dreaming.
Please go easy on me for not liking pod.
Thanks,
Erik Lechak
Nicholas Clark
On Sat, Sep 28, 2002 at 10:46:36PM -0400, Erik Lechak wrote:
> 3)Do I have to use pod? No offense, but I can't stand pod. The pdd
> design document states that pod is the "...documentation language for
> All Things Perl", but this is Parrot not Perl. And this document would
> not be a design doc. If Parrot is supposed to be a cross language VM,
> why do people need to know pod to read (or write) the docs? I know that
> it is easy to convert pod to an easy to read format, but would a
> developer with little perl experience know that? Parrot is trying to
> encourage developers from areas other than perl, so why discourage them
> by introducing them to parrot with pod documents.
Well, POD is supposed to be easy, and by implication easy to learn.
But that's irrelevant if you already know it and know you don't like it.
In my opinion it makes sense to have one documentation format consistently
(in the same way that we intend to have one true C indenting style)
What documentation format(s) do you like? Is there an easy way to convert
them, or a subset of them, losslessly to and from POD? If we provided tools
with parrot to do that, then (assuming we stick with POD as the documenting
format) it would allow you (and everyone else who shares your preferences
whom we hope to recruit) to write documentation in the way that feels
natural to you by converting the POD documentation to whatever, editing that,
and converting the changed version back.
This would mean that the round trip conversion had to be lossless and
(almost) canonical form, so that a diff of the original POD against the
round trip would be empty, and I guess that possible in theory.
However, are there any useful (not POD) documentation formats for which it's
practical?
> Could there possibly be a parrot comment style? It could be used
> instead of other comment styles internal to parrot. Use it in the
> c-code, the perl code, the parrot assembly code, and to write the
> documentation. Then a (perl) preprocessor could strip it out before it
> is compiled or run. Normally I would not suggest such a thing, but
> there is a lot of code generation and manipulation going on anyway. It
> could allow for document generation of all the parrot source, assembly,
> tests, and documents into a javadoc-like html reference. Or maybe I'm
> just dreaming.
It's not clear to me what you think might work well for this. Do you have
any suggestions - either of what we could do, or what there is already that
is bad (and why)?
> Please go easy on me for not liking pod.
Well, you were crafty enough not to say why you don't like pod, which makes
it hard for anyone to work out how to respond to your heresy. :-)
Nicholas Clark
--
Even better than the real thing: http://nms-cgi.sourceforge.net/
Tim Bunce
around? The usual cross-reference stuff would be handy, but ideally
something that goes further.
Graphical would be good, interactive better (or at least cooler :).
Perhaps something like www.kartoo.com (needs flash) or
http://www.touchgraph.com/TGGoogleBrowser.html (needs java) that
lets you "explore" the relationships between things.
And, in case you're not familar with it, the "ID database" is a
very useful tool (quite old and alomost lost in the mists of time):
http://www.math.utah.edu/docs/info/mkid_toc.html
I highly recommend it.
Tim.
On Sat, Sep 28, 2002 at 10:46:36PM -0400, Erik Lechak wrote:
Dan Sugalski
>On a related note, are there any good tools for static code analysis
>around? The usual cross-reference stuff would be handy, but ideally
>something that goes further.
If someone wants to build some and there are things that parrot
doesn't provide that would make it easier, speak up--while I won't
promise we'll design in things for it, we certainly can't if we don't
know.
--
Dan
--------------------------------------"it's like this"-------------------
Dan Sugalski even samurai
d...@sidhe.org have teddy bears and even
teddy bears get drunk
Tim Bunce
> At 12:15 PM +0100 10/2/02, Tim Bunce wrote:
> >On a related note, are there any good tools for static code analysis
> >around? The usual cross-reference stuff would be handy, but ideally
> >something that goes further.
>
> If someone wants to build some and there are things that parrot
> doesn't provide that would make it easier, speak up--while I won't
> promise we'll design in things for it, we certainly can't if we don't
> know.
Seeing my post mentioned 'in brief' in Leon's summary made me think I
should at least do some googling of my own...
I turned up this one:
http://www.gnu.org/software/gcc/news/egcs-vcg.html
http://rw4.cs.uni-sb.de/users/sander/html/gsvcg1.html
Tim.
Tim Bunce
This is slightly different:
"Infrastructure for C Program Analysis and Transformation"
http://manju.cs.berkeley.edu/cil/
I wonder if it might be useful to occasionally use the related
"CCured" tool (built using CIL) as an extra sanity check on the
parrot code:
"CCured is a source-to-source translator for C, which
analyzes the program to determine the smallest number of
run-time checks that must be inserted in the program to
prevent all memory safety violations."
http://manju.cs.berkeley.edu/ccured/index.html
Tim.
Gopal V
> "CCured is a source-to-source translator for C, which
> analyzes the program to determine the smallest number of
> run-time checks that must be inserted in the program to
> prevent all memory safety violations."
Yow ! .. the output looks __WILD ...
Gopal
--
The difference between insanity and genius is measured by success