New 5/10: Fixed update bugs
New 4/1: Header and Footer support
New 3/25: Rich text definitions in doc / Refer to last computation using 'last' / Name your formula in @ notation (see cheat sheet)
New: Visually modify generated tables without helpers and rich text sequences.

Have you ever wished you could synchronize content within one Google doc? Do you need temporary placeholders that you will replace later? Do you want to generate text? Do you miss spreadsheets in docs?

If you answered yes to one of these questions, this Google doc extension is for you. It enables you to define names (a.k.a. variables) anywhere in the document or in a special box on the side panel, and to insert computations that produce rich text and images anywhere in the document.

plus: if you computations are simple enough, formulas are reversible. This means you can edit the result of a formula to change the formula itself, in the doc or in the computed values on the side panel (with a lightblue background). For now, strings, numbers, booleans, variables, comments and parentheses are the only reversible things. More will come (conditionals, concatenation, pure function calls, etc.)

# Quick start

Select some portion of text that you want to reuse.
Click on "Name selection", then enter "x" in the dialog box.
Now every time you want to use a clone of this selection, click on the button "x".
You can change the value of "x" either directly in the document, or on the side panel.

Click on the Cheat sheet to have a sense of everything you can do with this add-on.

# Advanced steps

## Define names

You can define a name anywhere in your document, or in the text zone under the button "Display values".
Definitions have to start with a name, the sign equal '=' and a non-empty space after it. If the content starts with an opening parenthesis or square bracket, or if it a number or a boolean (true/false), the content will be evaluated as raw JavaScript. Else, the remaining until the end of the newline is treated as raw rich text.
Definitions can depend on previous definitions, but they must be in order.
The following are all valid definitions of names:

    version = 1.0 beta
    name = ("MySoft" + version)
    citations = ({ mayer18: "https://dl.acm.org/citation.cfm?id=3276497", chugh16: "https://dl.acm.org/citation.cfm?id=2908103" })
    cite = (function (name) { return typeof citations[name] !== "undefined" ? ["[" + name + "]", {link: citations[name]}] : "[" + name + "???]"; })

## Write formulas in your document

Anywhere in the document, write = followed by either

* a name
* a name followed by a JavaScript expression in parentheses
* a JavaScript expression inside parentheses or square brackets

If the formula has the syntax `=customName@(blablah)`, not only it will output the result of evaluating `blablah`, but also assign it the name `customName` so that it can be reused in other formulas.

For example, in a document, you would write raw

    =name is out!
    =[name, {bold: true}] is a n=(function() { var x = ""; var i = 10; while(i-- > 0) x 
= x + "i"; return x} ())ce software based on =be@("bidirectional evaluation") =cite("mayer18") that goes beyond the original ideas of prodirect manipulation =cite("chugh16") because =be is more flexible.

# Display values

Click on "Display values". It will evaluate all formulas and replace them by their values, highlighted in green if the option "Highlight values" is set. If something is selected, only the formulas under the selection are evaluated. The document above would be rendered as:

    MySoft 1.0 beta is out!
    MySoft 1.0 beta is a niiiiiiiiiice software based on bidirectional evaluation [mayer18] that goes beyond the original ideas of prodirect manipulation [chugh16] because bidirectional evaluation is more flexible.

Formulas should either return raw text, rich text or elements.

Rich text consists in a 2-element array where the first element is the text, and the second is a Javascript object containing styling material. If the method setThing exists in this page https://developers.google.com/apps-script/reference/document/text, then thing : value is a valid style attribute. Here is a list of supported attributes and shortcuts

* backgroundColor (or background): a string representing a color like "#FF00FF".
* bold: boolean (true or false).
* fontFamily: string representing a valid font name.
* fontSize: integer representing a valid font size.
* foregroundColor (or color): a string representing a color like "#FF00FF".
* italic: boolean (true or false).
* linkUrl (or link): string representing an URL.
* strikeThrough (or strike): boolean (true or false).
* textAlignment (or align): either "normal", "superscript" or "subscript"
* underline: boolean (true or false).

Elements consist in a 3-element array where the first element is the tag (currently, only "img" supported, which is the same as "InlineImage"), the second is an object with the attributes (src required for images), and the third is a list of children ([] should be explicitly entered for images)

Here is a list of supported attributes for images:
* alt   (string)
* title (string)
* width (number in pixels)
* height (number in pixels)

# Reveal formulas

To change formulas behind values, click on "Display formulas". It will replace all computed values by their respective formulas, and highlight them in orange if the option "Highlight formulas" is set. If something is selected, only formulas within the selection are revealed. You can then edit any formula and click on "Display values" once you are done.

# Give a name to a selection

Select some part of text or mulltiple elements (such as table, paragraphs and list items), and give them a name to reuse it. If you select the option "Assign names inline", the names will be given using the =name@ notation, else they will be defined in the sidebar textarea.