Search code examples
documentationsubmissionprettifygoogle-code-prettify

Guidelines for Google Code Prettify

I'm hoping to pick up Issue 295 from Google's Code-Prettify project; i.e. to add support for lang-powershell.

Whilst I've found some code examples, I can't find any documentation on how this code should be written, or any submission guidelines (e.g. should syntax highlighting work for invalid code, or should it attempt to highlight such errors)?

Ironically I've tried Googling, but with no joy. The best I could find was their Style Guide.

Question

Please could someone point me to documentation for submitting a new language support script to Google Code Prettify?

Solution

  • should syntax highlighting work for invalid code or should it attempt to highlight such errors

    Prettify is often applied to code fragments, so you can assume that the fragment starts at a token boundary, but should not assume that it starts at a top level production.

    On sites like SO, prettify is applied to inputs written by novices and maintainers who have a passing familiarity with other languages and are trying to make spot edits to an existing snippet of code.

    Prettify should make it easy for people with a deep understanding of the language to quickly scan for problems in the snippet of code.

    You should make a best effort to recover from errors. For example, if the snippet only includes single-line tokens, then an invalid token on one line shouldn't prevent prettifying of every subsequent line. If that's unavoidable, then an invalid token shouldn't prevent prettifying of previous tokens -- seeing where tokenizing fails can convey useful information to someone scanning a code snippet for problems.

    If you want to call out obvious errors like unclosed string literals, that's great. I'd apply .err and then a style that wants to apply a wiggly underline in red could do so. I'd be happy to accept a change to the default stylesheet for that.

    The way I think about it is that prettify bridges the gap between two concepts of language:

    1. In parser theory, a "language" is a set of strings. The PowerShell language is the set of strings defined by a grammar in a spec document.
    2. In common descriptivist usage, a "language" relates that which is produced by a speaker or author in the associated linguistic community to that which is in their mind when they produce the string. When a programmer sits down to produce a PowerShell script, what they produce is a string in the language even if they do a bad job or their mental model of PowerShell differs significantly from the spec document.

    In the first sense, there is no such thing as a malformed PowerShell program, just a string that is not in the language and hence has no semantics per the spec. In the second, a malformed PowerShell program is a PowerShell program.

    Please keep the second definition in mind, and remember that prettify does not need to work on the output of code generators.