We already apply xslthl to the code samples. Is there some improvement we can make to this?

I think this is related to my comment "...I started to wonder if a consistent color-coding of the examples might help. I don't know if the way the docs are generated support this but knowing at a glance which 'word' is a built-in call (like dependencies) versus a task name versus a configuration name might at least help."

From here: http://old.nabble.com/Re%3A-where-to-start-for-a-beginner-p26751041ef31415.html

It may be infeasible but we're talking about something beyond basic syntax highlighting since it would necessarily need to understand the example and the context within which it is used.

And it makes more sense in examples that include more user-like content versus the really simple examples but still it might be nice to know at a glance what different main types are.

I tried to include a sample using confluence mark-up here but I can't get it to let me do colors and "pre" style formatting at the same time.

Adam,
I think we should first create a Gradle highlight rules file (like the one that exists for Java, C, etc.) and then we will have a really nice visible code. If we don't have such file, only common terms like "if" or "new" will be highlighted (as it is now).

BTW. I'm a xslthl noob

–
Tomek

I'll try what I can do here and you will see then if it is any good.

–
Tomek

an example of what is possible

on the left - new version
on the right - current version

Highlighted words are customizable. But this is not so simple and they should be chosen carefully - for example it is nice to have "name" highlighted in dependencies section, but it will also be highlighted in this snippet of code:
println "$file.name Checksum: ${ant.properties["cs_$file.name"]}"
(probably because many "" will "stupify" xstl) which is rather not expected.

This is way beyond my XSLT-fu to repair such cases. But if we choose the words carefully, there will be no problem.

Paul, is it close to what you intended ?

–
Tomek

Similar. I would have maybe gone further and used different colors for things like "dependencies", "repositories", "usePlugin", etc. as built in calls... versus compile, testCompile as configurations, etc..

It's hard to figure out exactly where to draw the line but a little goes a long way.

For example, in my editor's Java syntax highlighting, Java keywords show up as a different color. Standard JDK classes show up in yet another color... and so on.

With potentially ambiguous words like "compile", I think reinforcing that this is a dependency configuration point through some additional highlighting is a good thing for new readers. And knowing that "dependencies" is base construct versus uploadArchives which is a task is also good. A bonus would be to give that gradle-provided tasks a different color than a user's own tasks would have.

Paul, I get what you would like to have, but that would be much more complicated.

At the moment we can improve userguide listings by having chosen Gradle keywords highlighted instead of having Java keywords highlighted. IMHO definitely an improvement.

–
Tomek

As announced on the Gradle blog we are planning to completely migrate issues from JIRA to GitHub.

We intend to prioritize issues that are actionable and impactful while working more closely with the community. Many of our JIRA issues are inactionable or irrelevant. We would like to request your help to ensure we can appropriately prioritize JIRA issues you’ve contributed to.

Please confirm that you still advocate for your JIRA issue before December 10th, 2016 by:

• Checking that your issues contain requisite context, impact, behaviors, and examples as described in our published guidelines.
• Leave a comment on the JIRA issue or open a new GitHub issue confirming that the above is complete.

We look forward to collaborating with you more closely on GitHub. Thank you for your contribution to Gradle!

Thanks again for reporting this issue. We haven't heard back from you after our inquiry from November 15th. We are closing this issue now. Please create an issue on GitHub if you still feel passionate about getting it resolved.