You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@shindig.apache.org by ih...@gmail.com on 2008/01/18 04:46:28 UTC
Documenting Shindig - Caja interface
Hi folks,
In an attempt to document the results of a discussion about the
interface between Shindig and the Cajoler, I modified this document --
http://google-caja.googlecode.com/svn/trunk/doc/html/cajaOpenSocialGadgetRewriting/index.html
and the diffs since the last version are attached fyi.
I'm especially interested in knowing whether I got the format of the
embedded line number and source file annotations right. All other
comments are welcome too, of course! Cheers,
Ihab
--
Ihab A.B. Awad, Palo Alto, CA
Re: Documenting Shindig - Caja interface
Posted by Kevin Brown <et...@apache.org>.
Just to clarify this because of questions I've gotten from others: I'm
saying that Shindig will provide an implementation of the service, not the
actual infrastructure for said service. We would hope that existing
infrastructure providers such as google would provide that sort of community
infrastructure for those that might want it.
~Kevin
On Jan 18, 2008 1:14 AM, Kevin Brown <et...@apache.org> wrote:
> Thank you so much for this, Ihab (and the entire Caja team).
>
> We should probably also share our face to face discussion about building a
> Cajoling web service for people who aren't able to use the Caja java code
> directly. Do you feel that this should be maintained by Caja, or would you
> prefer that Shindig manage it? Speaking for the Shindig project, I think
> we'd be happy to manage this responsibility, and I will personally write the
> initial version of said web service. We should probably produce at least a
> semi-formal document outlining what this web service will look like as well.
>
>
> ~Kevin
>
> On Jan 17, 2008 7:46 PM, <ih...@gmail.com> wrote:
>
> > Hi folks,
> >
> > In an attempt to document the results of a discussion about the
> > interface between Shindig and the Cajoler, I modified this document --
> >
> > http://google-caja.googlecode.com/svn/trunk/doc/html/cajaOpenSocialGadgetRewriting/index.html
> >
> > and the diffs since the last version are attached fyi.
> >
> > I'm especially interested in knowing whether I got the format of the
> > embedded line number and source file annotations right. All other
> > comments are welcome too, of course! Cheers,
> >
> > Ihab
> >
> > --
> > Ihab A.B. Awad, Palo Alto, CA
> >
>
>
Re: Documenting Shindig - Caja interface
Posted by Kevin Brown <et...@apache.org>.
Thank you so much for this, Ihab (and the entire Caja team).
We should probably also share our face to face discussion about building a
Cajoling web service for people who aren't able to use the Caja java code
directly. Do you feel that this should be maintained by Caja, or would you
prefer that Shindig manage it? Speaking for the Shindig project, I think
we'd be happy to manage this responsibility, and I will personally write the
initial version of said web service. We should probably produce at least a
semi-formal document outlining what this web service will look like as well.
~Kevin
On Jan 17, 2008 7:46 PM, <ih...@gmail.com> wrote:
> Hi folks,
>
> In an attempt to document the results of a discussion about the
> interface between Shindig and the Cajoler, I modified this document --
>
>
> http://google-caja.googlecode.com/svn/trunk/doc/html/cajaOpenSocialGadgetRewriting/index.html
>
> and the diffs since the last version are attached fyi.
>
> I'm especially interested in knowing whether I got the format of the
> embedded line number and source file annotations right. All other
> comments are welcome too, of course! Cheers,
>
> Ihab
>
> --
> Ihab A.B. Awad, Palo Alto, CA
>
Re: Documenting Shindig - Caja interface
Posted by Kevin Brown <et...@google.com>.
Actually, the possibility of multi line __MSG_ substitutions probably makes
the hunking process necessary as well, so I guess I'm +1 on Ihab's proposal.
~Kevin
On Jan 18, 2008 4:04 PM, John Hjelmstad <fa...@google.com> wrote:
> With the introduction of multiple content sections, plus the fact you've
> already mentioned that messages and other substitution can lead to line
> number modification (and certainly column modification), I actually like
> the
> List<Hunk> idea.
>
> This will be especially so once we support some mechanism for inclusion of
> one content section in another.
>
> --John
>
> On Fri, Jan 18, 2008 at 3:56 PM, <ih...@gmail.com> wrote:
>
> > On Jan 18, 2008 3:11 PM, Kevin Brown <et...@apache.org> wrote:
> > > From what I can tell right now, we're probably going to only wind up
> > with 1
> > > "Hunk" anyway, since the inlining of the other files will wind up
> > happening
> > > in the cajoling process rather than in shindig itself.
> >
> > Okay, so we assume then that the only change you are making to the
> > content is message substitution, and that this does not substantially
> > affect file positions (i.e., it does not affect *line* number)? If so,
> > then you're right, we only need 1 hunk.
> >
> > If so, then the information we need is the start position for the
> > [one] hunk, right? And we don't need the inline annotations, right? So
> > we end up with --
> >
> > GadgetContentRewriter.rewriteContent(
> > ...,
> > FilePosition start,
> > Readable content,
> > ...);
> >
> > Does this look okay then? Does everyone -- Shindig and Caja -- like
> > this better? What are the limitations?
> >
> > Ihab
> >
> > --
> > Ihab A.B. Awad, Palo Alto, CA
> >
>
Re: Documenting Shindig - Caja interface
Posted by John Hjelmstad <fa...@google.com>.
With the introduction of multiple content sections, plus the fact you've
already mentioned that messages and other substitution can lead to line
number modification (and certainly column modification), I actually like the
List<Hunk> idea.
This will be especially so once we support some mechanism for inclusion of
one content section in another.
--John
On Fri, Jan 18, 2008 at 3:56 PM, <ih...@gmail.com> wrote:
> On Jan 18, 2008 3:11 PM, Kevin Brown <et...@apache.org> wrote:
> > From what I can tell right now, we're probably going to only wind up
> with 1
> > "Hunk" anyway, since the inlining of the other files will wind up
> happening
> > in the cajoling process rather than in shindig itself.
>
> Okay, so we assume then that the only change you are making to the
> content is message substitution, and that this does not substantially
> affect file positions (i.e., it does not affect *line* number)? If so,
> then you're right, we only need 1 hunk.
>
> If so, then the information we need is the start position for the
> [one] hunk, right? And we don't need the inline annotations, right? So
> we end up with --
>
> GadgetContentRewriter.rewriteContent(
> ...,
> FilePosition start,
> Readable content,
> ...);
>
> Does this look okay then? Does everyone -- Shindig and Caja -- like
> this better? What are the limitations?
>
> Ihab
>
> --
> Ihab A.B. Awad, Palo Alto, CA
>
Re: Documenting Shindig - Caja interface
Posted by ih...@gmail.com.
On Jan 18, 2008 3:11 PM, Kevin Brown <et...@apache.org> wrote:
> From what I can tell right now, we're probably going to only wind up with 1
> "Hunk" anyway, since the inlining of the other files will wind up happening
> in the cajoling process rather than in shindig itself.
Okay, so we assume then that the only change you are making to the
content is message substitution, and that this does not substantially
affect file positions (i.e., it does not affect *line* number)? If so,
then you're right, we only need 1 hunk.
If so, then the information we need is the start position for the
[one] hunk, right? And we don't need the inline annotations, right? So
we end up with --
GadgetContentRewriter.rewriteContent(
...,
FilePosition start,
Readable content,
...);
Does this look okay then? Does everyone -- Shindig and Caja -- like
this better? What are the limitations?
Ihab
--
Ihab A.B. Awad, Palo Alto, CA
Re: Documenting Shindig - Caja interface
Posted by Kevin Brown <et...@apache.org>.
>From what I can tell right now, we're probably going to only wind up with 1
"Hunk" anyway, since the inlining of the other files will wind up happening
in the cajoling process rather than in shindig itself. Not having an
implementation to base this on, it's hard to definitively say whether your
proposal or what we're doing right now is better.
~Kevin
On Jan 18, 2008 2:55 PM, <ih...@gmail.com> wrote:
> Hi Bruno & all,
>
> Thanks for the reply. Will work on all these issues but I thought I'd
> ask specifically about this one --
>
> On Jan 18, 2008 12:15 AM, Bruno Bowden <br...@google.com> wrote:
> > For the line comments, it looks like it can't be parsed. Can you just
> > mention the 'comment' prefix, e.g. "//" that will be used depending on
> where
> > it's shown.
>
> Parsing is indeed an issue -- see below.
>
> > Also, with styles being separated out, does this mean out of
> > sequence line numbers to group together styles that might have been
> > scattered throughout the original gadget spec.
>
> That would be the (desirable) effect, yes: the line numbers would
> ensure that errors referred to the original gadget spec even though
> the styles are lumped into one section at the top.
>
> * * * * *
>
> I'd like to propose a different API for the GadgetContentRewriter [*]
> that does not depend on parsing. Right now, the client specifies a
> Readable (essentially, a character stream). What would you folks think
> if, instead, the client gave us a more structured data type? Something
> like --
>
> class FilePosition {
> int lineNo, charNo;
> URI source;
> }
>
> class Hunk {
> FilePosition start;
> String content;
> }
>
> GadgetContentRewriter.rewriteContent(..., List<Hunk> content, ...);
>
> This would allow you to maintain progeny, down to the character level
> if you want, of where each piece of content came from. For
> compilation, we would concatenate all the Strings in order, but we
> would be able to maintain the progeny through our parsing.
>
> It seems like this is easy enough to do even if you are substituting
> hangman variables (_UP_*) via something so simple as a regex. It
> requires no deep parsing, no commenting and no escaping.
>
> Shinding ** and ** Caja people -- what are your thoughts?
>
> Ihab
>
> [*]
> http://google-caja.googlecode.com/svn/trunk/src/java/com/google/caja/opensocial/GadgetContentRewriter.java
>
>
> --
> Ihab A.B. Awad, Palo Alto, CA
>
Re: Documenting Shindig - Caja interface
Posted by ih...@gmail.com.
On Jan 18, 2008 3:09 PM, Bruno Bowden <br...@google.com> wrote:
> This indeed would have far more information but I'm not sure that it's
> needed. I think we should go with the simple parsing first then look at this
> again if find that we need more.
Yes but parsing is not simple, since commenting conventions are
different in HTML versus JavaScript, and you don't want to pre-parse
the content to figure out which convention to use, right?
> For other reasons, we'd like to avoid using _UP_* hangman variables, except
> for message substitution.
Ok, then, no _UP_*, but message substitution has the same effect on
character positions so perhaps the problem remains.
Ihab
--
Ihab A.B. Awad, Palo Alto, CA
Re: Documenting Shindig - Caja interface
Posted by Bruno Bowden <br...@google.com>.
> This would allow you to maintain progeny, down to the character level
> if you want, of where each piece of content came from. For
> compilation, we would concatenate all the Strings in order, but we
> would be able to maintain the progeny through our parsing.
This indeed would have far more information but I'm not sure that it's
needed. I think we should go with the simple parsing first then look at this
again if find that we need more.
It seems like this is easy enough to do even if you are substituting
> hangman variables (_UP_*) via something so simple as a regex. It
> requires no deep parsing, no commenting and no escaping.
For other reasons, we'd like to avoid using _UP_* hangman variables, except
for message substitution.
> Shinding ** and ** Caja people -- what are your thoughts?
>
> Ihab
>
> [*]
> http://google-caja.googlecode.com/svn/trunk/src/java/com/google/caja/opensocial/GadgetContentRewriter.java
>
>
> --
> Ihab A.B. Awad, Palo Alto, CA
>
Re: Documenting Shindig - Caja interface
Posted by ih...@gmail.com.
Hi Bruno & all,
Thanks for the reply. Will work on all these issues but I thought I'd
ask specifically about this one --
On Jan 18, 2008 12:15 AM, Bruno Bowden <br...@google.com> wrote:
> For the line comments, it looks like it can't be parsed. Can you just
> mention the 'comment' prefix, e.g. "//" that will be used depending on where
> it's shown.
Parsing is indeed an issue -- see below.
> Also, with styles being separated out, does this mean out of
> sequence line numbers to group together styles that might have been
> scattered throughout the original gadget spec.
That would be the (desirable) effect, yes: the line numbers would
ensure that errors referred to the original gadget spec even though
the styles are lumped into one section at the top.
* * * * *
I'd like to propose a different API for the GadgetContentRewriter [*]
that does not depend on parsing. Right now, the client specifies a
Readable (essentially, a character stream). What would you folks think
if, instead, the client gave us a more structured data type? Something
like --
class FilePosition {
int lineNo, charNo;
URI source;
}
class Hunk {
FilePosition start;
String content;
}
GadgetContentRewriter.rewriteContent(..., List<Hunk> content, ...);
This would allow you to maintain progeny, down to the character level
if you want, of where each piece of content came from. For
compilation, we would concatenate all the Strings in order, but we
would be able to maintain the progeny through our parsing.
It seems like this is easy enough to do even if you are substituting
hangman variables (_UP_*) via something so simple as a regex. It
requires no deep parsing, no commenting and no escaping.
Shinding ** and ** Caja people -- what are your thoughts?
Ihab
[*] http://google-caja.googlecode.com/svn/trunk/src/java/com/google/caja/opensocial/GadgetContentRewriter.java
--
Ihab A.B. Awad, Palo Alto, CA
Re: Documenting Shindig - Caja interface
Posted by Bruno Bowden <br...@google.com>.
Hi Ihab,
nice document, thanks for updating it. In general it was very helpful. If I
had any slight niggles it would be the following:
Quotes are incorrectly shown as "“" and "â€" in several places. This is
due to copying text from a word document with 'smart quotes', which happen
to use non-standard characters. See here:
http://www.b2blog.com/2007/12/blog-post.htm
Caja should wrap the gadgets.* functions instead of _IG_*. The latter set of
function are being deprecated, though will be supported for some time
through wrapper functions for backward compatibility. Not sure if this
requires separating out the wrapper layer so that can be cajoled whilst the
real gadgets.* function are untouched? Please advise on this. There are some
slight syntax differences between the two versions.
Pursuant to our discussion, do you want to add that the first mention of a
new file requires mentioning both LINE and FILE? After that, it just needs
the LINE no.
For the line comments, it looks like it can't be parsed. Can you just
mention the 'comment' prefix, e.g. "//" that will be used depending on where
it's shown. Also, with styles being separated out, does this mean out of
sequence line numbers to group together styles that might have been
scattered throughout the original gadget spec.
On Jan 17, 2008 7:46 PM, <ih...@gmail.com> wrote:
> Hi folks,
>
> In an attempt to document the results of a discussion about the
> interface between Shindig and the Cajoler, I modified this document --
>
>
> http://google-caja.googlecode.com/svn/trunk/doc/html/cajaOpenSocialGadgetRewriting/index.html
>
> and the diffs since the last version are attached fyi.
>
> I'm especially interested in knowing whether I got the format of the
> embedded line number and source file annotations right. All other
> comments are welcome too, of course! Cheers,
>
> Ihab
>
> --
> Ihab A.B. Awad, Palo Alto, CA
>