Syntax highlighting for Gremlin

[Luis Bosquez Gonzalez <lb...@microsoft.com.INVALID>]

Hello Gremlin community,

I am a program manager at Microsoft working on Cosmos DB's Gremlin API implementation. We're currently looking at using a syntax colorizer/highlighter for our Gremlin docs, but I couldn't find any guidance or examples on how to go on about it.

Are there any existing rules/guidelines to follow? If not, I can write something up and send it out for review here. The idea is to implement the rules in highlight.js and contribute them.

Thanks,
Luis

Re: Syntax highlighting for Gremlin

[Stephen Mallette <sp...@gmail.com>]

I think that it could hold some value, though I'm not sure if we would make
specific use of it in TinkerPop documentation as we are heading down the
path of generating language specific code examples for each GLV and I would
imagine that we would stick to the standard language highlighting for
consistency. Of course, it still would be a worthwhile contribution in my
mind as others might find use for it in their work as a standalone thing,
but if the scope of it were to be shaped a bit more in the context of what
we had already have, it could be really useful to the project internally.
I'll try to outline that context in the rest of this post.

Now, I had thought that we might use it on the TinkerPop website which has
Gremlin snippets and I realized we already have some nice formatting there.
When I looked into that further I realized that we did have a specialized
Gremlin highlighter for prismjs (https://prismjs.com/) - you might want to
look at that for ideas if you go with highlight.js to stay consistent (or
if you have better ideas we could port them back to prismjs for the web
site). You can find that prismjs highlighter rules for Gremlin here:

https://github.com/apache/tinkerpop/blob/b75cfb8ec529aad957d5a631b15cc3afcf86186f/docs/site/home/js/prism.js#L268

I have no idea how prismjs works or who even did that work for the web site
in the first place, so I can't answer too many questions about it, but I do
like how it renders Gremlin in the website. I especially like that it
renders "Gremlin expressions" (i.e. such as the standalone values of P,
Column, T) differently than steps...I think that's important as many people
confuse those for steps. If you haven't read my Gremlin Anatomy tutorial:

http://tinkerpop.apache.org/docs/3.3.3/tutorials/gremlins-anatomy/

you might want to consider taking a look at that for more information on
how Gremlin is organized (though you likely have already internalized these
concepts - i just give names to them there).

As a final point, that may be related, I would love to have a
"gremlin-groovy-console" syntax highlighter. Right now we just use
"groovy", but I dislike that. The problem is that when we render output
from the console it displays the various prompts and toString() values and
those are not properly highlighted. For example:

gremlin> graph = TinkerFactory.createModern()
==>tinkergraph[vertices:6 edges:6]

Really the only "groovy" here is:

graph = TinkerFactory.createModern()

The rest is up for grabs as to how it should be highlighted. We get a weird
mix of things sometimes when it comes to rendering that output. It would be
awesome to have something that makes that nice, perhaps based on the
prismjs format or the format that you come up with??? note that for our
documentation (generated by asciidoc) we don't use prismjs - we instead use
coderay (http://coderay.rubychan.de/). I can't remember if there is a
reason for that, but I think it may have just been a style choice - we
simply liked the look of coderay best. Note that without some form of
extension to asciidoc we can only support the following options: coderay,
highlightjs, prettify, and pygments.

Well, you came here to offer a simple syntax highlighter for Gremlin and
I've now turned it into "a project" :)   I just wanted to give you all the
information that I could on the topic to help maximize the usefulness of
your contribution and help define the borders of what you plan to do.
Looking forward to hearing what you think about all this.




On Tue, Jun 5, 2018 at 7:05 PM Luis Bosquez Gonzalez
<lb...@microsoft.com.invalid> wrote:

> Hi Stephen,
>
> In our docs we have specific Gremlin snippets (mostly commands from the
> Gremlin Console), that aren't meant to be called within any specific
> framework. For now we can use some standard C# or Java highlighting, but I
> wanted to know if there was any interest in starting such an initiative.
>
> -----Original Message-----
> From: Stephen Mallette <sp...@gmail.com>
> Sent: Monday, June 4, 2018 2:17 PM
> To: dev@tinkerpop.apache.org
> Cc: Ashwini Singh <as...@microsoft.com>
> Subject: Re: Syntax highlighting for Gremlin
>
> I don't believe we have anything like that - specific to Gremlin itself i
> mean. Typically, we fall back to the native language for highlighting. So,
> if you write gremlin in java you would use Java highlighting, if you wrote
> your Gremlin in C# then you would get c# highlighting, and so on. Do you
> feel like there's a nicer highlighting format that should be considered?
>
> As an aside, related to formatting Gremlin, we do have this Style Guide:
>
>
> https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Ftinkerpop.apache.org%2Fdocs%2Fcurrent%2Frecipes%2F%23style-guide&data=02%7C01%7Clbosq%40microsoft.com%7C9827da9bcd8245713d6108d5ca609a3a%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C1%7C636637438609543174&sdata=7%2FGgXgrEbTl2UXxzIKQ7VPj%2FyrzztUC17CuXwrkKt6U%3D&reserved=0
>
>
>
> On Mon, Jun 4, 2018 at 5:09 PM Luis Bosquez Gonzalez
> <lb...@microsoft.com.invalid> wrote:
>
> > Hello Gremlin community,
> >
> > I am a program manager at Microsoft working on Cosmos DB's Gremlin API
> > implementation. We're currently looking at using a syntax
> > colorizer/highlighter for our Gremlin docs, but I couldn't find any
> > guidance or examples on how to go on about it.
> >
> > Are there any existing rules/guidelines to follow? If not, I can write
> > something up and send it out for review here. The idea is to implement
> > the rules in highlight.js and contribute them.
> >
> > Thanks,
> > Luis
> >
>

RE: Syntax highlighting for Gremlin

[Luis Bosquez Gonzalez <lb...@microsoft.com.INVALID>]

Hi Stephen,

In our docs we have specific Gremlin snippets (mostly commands from the Gremlin Console), that aren't meant to be called within any specific framework. For now we can use some standard C# or Java highlighting, but I wanted to know if there was any interest in starting such an initiative.

-----Original Message-----
From: Stephen Mallette <sp...@gmail.com> 
Sent: Monday, June 4, 2018 2:17 PM
To: dev@tinkerpop.apache.org
Cc: Ashwini Singh <as...@microsoft.com>
Subject: Re: Syntax highlighting for Gremlin

I don't believe we have anything like that - specific to Gremlin itself i mean. Typically, we fall back to the native language for highlighting. So, if you write gremlin in java you would use Java highlighting, if you wrote your Gremlin in C# then you would get c# highlighting, and so on. Do you feel like there's a nicer highlighting format that should be considered?

As an aside, related to formatting Gremlin, we do have this Style Guide:

https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Ftinkerpop.apache.org%2Fdocs%2Fcurrent%2Frecipes%2F%23style-guide&data=02%7C01%7Clbosq%40microsoft.com%7C9827da9bcd8245713d6108d5ca609a3a%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C1%7C636637438609543174&sdata=7%2FGgXgrEbTl2UXxzIKQ7VPj%2FyrzztUC17CuXwrkKt6U%3D&reserved=0



On Mon, Jun 4, 2018 at 5:09 PM Luis Bosquez Gonzalez <lb...@microsoft.com.invalid> wrote:

> Hello Gremlin community,
>
> I am a program manager at Microsoft working on Cosmos DB's Gremlin API 
> implementation. We're currently looking at using a syntax 
> colorizer/highlighter for our Gremlin docs, but I couldn't find any 
> guidance or examples on how to go on about it.
>
> Are there any existing rules/guidelines to follow? If not, I can write 
> something up and send it out for review here. The idea is to implement 
> the rules in highlight.js and contribute them.
>
> Thanks,
> Luis
>

Re: Syntax highlighting for Gremlin

[Stephen Mallette <sp...@gmail.com>]

I don't believe we have anything like that - specific to Gremlin itself i
mean. Typically, we fall back to the native language for highlighting. So,
if you write gremlin in java you would use Java highlighting, if you wrote
your Gremlin in C# then you would get c# highlighting, and so on. Do you
feel like there's a nicer highlighting format that should be considered?

As an aside, related to formatting Gremlin, we do have this Style Guide:

http://tinkerpop.apache.org/docs/current/recipes/#style-guide



On Mon, Jun 4, 2018 at 5:09 PM Luis Bosquez Gonzalez
<lb...@microsoft.com.invalid> wrote:

> Hello Gremlin community,
>
> I am a program manager at Microsoft working on Cosmos DB's Gremlin API
> implementation. We're currently looking at using a syntax
> colorizer/highlighter for our Gremlin docs, but I couldn't find any
> guidance or examples on how to go on about it.
>
> Are there any existing rules/guidelines to follow? If not, I can write
> something up and send it out for review here. The idea is to implement the
> rules in highlight.js and contribute them.
>
> Thanks,
> Luis
>