update doc

doc/jsweet-language-specifications.md

@@ -1394,13 +1394,19 @@ We provide a quick start project to help you starting with such a use case: <htt
 Extending the transpiler
 ------------------------
 
-JSweet is an Open Transpiler. It means that it provides ways for programmers to tune/extend how JSweet generates the intermediate TypeScript code. Tuning the transpiler is a solution to avoid repetitive tasks and automatize them. For instance, say you have a legacy Java code that uses the Java API for serializing objects (`writeObject`/`readObject`). With JSweet, you can easily erase these methods from your program, so that the generated JavaScript code is free from any Java-specific serialization idioms. As another example, say you have a Java legacy code base that uses a Java API, which is close to (but not exactly) a JavaScript API you want to use in your final JavaScript code. With JSweet, you can write an adapter that will automatically map all the Java calls to the corresponding JavaScript calls. Last but not least, you can tune JSweet to take advantage of some specific APIs depending on the context. For instance, you may use ES6 maps if you know that your targeted browser supports them, or just use an emulation or a simpler implementation in other cases. You may adapt the code to avoid using some canvas or WebGL primitives when knowing they are not well supported for a given mobile browser. An so on... Using an Open Transpiler such as JSweet has many practical applications, which you may or may not have to use, but in any case it is good to be aware of what is possible.
+JSweet is an Open Transpiler. It means that it provides ways for programmers to tune/extend how JSweet generates the intermediate TypeScript code. Tuning the transpiler is a solution to avoid repetitive tasks and automatize them.
 
-Tuning can be done declaratively (as opposed to programmatically) using annotations. Annotations can be added to the Java program (hard-coded), or they can be centralized in a unique configuration file so that they don’t even appear in the Java code (we call them soft annotations). Using annotations is quite simple and intuitive. However, when complex customization of the transpiler is required, it is most likely that annotations are not sufficient anymore. In that case, programmers shall use the JSweet extension API, which entails all the tuning that can be done with annotations, and much more. The extension API gives access to a Java AST (Abstract Syntax Tree) withing the context of so-called printer adapters. Printer adapters follow a decorator pattern so that they can be chained to extend and/or override the way JSweet will print out the intermediate TypeScript code.
+For instance, say you have a legacy Java code that uses the Java API for serializing objects (`writeObject`/`readObject`). With JSweet, you can easily erase these methods from your program, so that the generated JavaScript code is free from any Java-specific serialization idioms.
+
+As another example, say you have a Java legacy code base that uses a Java API, which is close to (but not exactly) a JavaScript API you want to use in your final JavaScript code. With JSweet, you can write an adapter that will automatically map all the Java calls to the corresponding JavaScript calls.
+
+Last but not least, you can tune JSweet to take advantage of some specific APIs depending on the context. For instance, you may use ES6 maps if you know that your targeted browser supports them, or just use an emulation or a simpler implementation in other cases. You may adapt the code to avoid using some canvas or WebGL primitives when knowing they are not well supported for a given mobile browser. An so on... Using an Open Transpiler such as JSweet has many practical applications, which you may or may not have to use, but in any case it is good to be aware of what is possible.
+
+Tuning can be done declaratively (as opposed to programmatically) using annotations. Annotations can be added to the Java program (hard-coded), or they can be centralized in a unique configuration file so that they don’t even appear in the Java code (we call them soft annotations). Using annotations is quite simple and intuitive. However, when complex customization of the transpiler is required, it is most likely that annotations are not sufficient anymore. In that case, programmers shall use the JSweet extension API, which entails all the tuning that can be done with annotations, and much more. The extension API gives access to a Java AST (Abstract Syntax Tree) within the context of so-called *printer adapters*. Printer adapters follow a decorator pattern so that they can be chained to extend and/or override the way JSweet will print out the intermediate TypeScript code.
 
 ### Core annotations
 
-The package `jsweet.lang` defines various annotation that can be used to tune the way JSweet generates the intermediate TypeScript code. Here we explain these annotations and give examples on how to use them.
+The package `jsweet.lang` defines various annotations that can be used to tune the way JSweet generates the intermediate TypeScript code. Here we explain these annotations and give examples on how to use them.
 
 -   `@Erased`: This annotation type is used on elements that should be erased at generation time. It can be applied to any program element. If applied to a type, casts and constructor invocations will automatically be removed, potentially leading to program inconsistencies. If applied to a method, invocations will be removed, potentially leading to program inconsistency, especially when the invocation’s result is used in an expression. Because of potential inconsistencies, programmers should use this annotation carefully, and applied to unused elements (also erasing using elements).
 
@@ -1414,7 +1420,7 @@ The package `jsweet.lang` defines various annotation that can be used to tune th
 
     -   `{{methodName}}`: the current method name.
 
-    -   `{{body}}`: the body of the current method. A typical use of this variable is to wrap the original behavior in a lambda. For instance: `/* before code */ let _result = () => { {{body}} }(); /* after code */ return result;`.
+    -   `{{body}}`: the body of the current method. A typical use of this variable is to wrap the original behavior in a lambda. For instance: `/* before code */ let _result = () => { {{body}} }(); /* after code */ return _result;`.
 
     -   `{{baseIndent}}`: the indentation of the replaced method. Can be used to generate well-formatted code.
 

doc/jsweet-language-specifications.tex

@@ -1407,13 +1407,19 @@ We provide a quick start project to help you starting with such a use case: \url
 \chapter{Extending the transpiler}
 \label{extending-the-transpiler}
 
-JSweet is an Open Transpiler. It means that it provides ways for programmers to tune/extend how JSweet generates the intermediate TypeScript code. Tuning the transpiler is a solution to avoid repetitive tasks and automatize them. For instance, say you have a legacy Java code that uses the Java API for serializing objects (\texttt{writeObject}/\texttt{readObject}). With JSweet, you can easily erase these methods from your program, so that the generated JavaScript code is free from any Java-specific serialization idioms. As another example, say you have a Java legacy code base that uses a Java API, which is close to (but not exactly) a JavaScript API you want to use in your final JavaScript code. With JSweet, you can write an adapter that will automatically map all the Java calls to the corresponding JavaScript calls. Last but not least, you can tune JSweet to take advantage of some specific APIs depending on the context. For instance, you may use ES6 maps if you know that your targeted browser supports them, or just use an emulation or a simpler implementation in other cases. You may adapt the code to avoid using some canvas or WebGL primitives when knowing they are not well supported for a given mobile browser. An so on... Using an Open Transpiler such as JSweet has many practical applications, which you may or may not have to use, but in any case it is good to be aware of what is possible.
+JSweet is an Open Transpiler. It means that it provides ways for programmers to tune/extend how JSweet generates the intermediate TypeScript code. Tuning the transpiler is a solution to avoid repetitive tasks and automatize them.
 
-Tuning can be done declaratively (as opposed to programmatically) using annotations. Annotations can be added to the Java program (hard-coded), or they can be centralized in a unique configuration file so that they don't even appear in the Java code (we call them soft annotations). Using annotations is quite simple and intuitive. However, when complex customization of the transpiler is required, it is most likely that annotations are not sufficient anymore. In that case, programmers shall use the JSweet extension API, which entails all the tuning that can be done with annotations, and much more. The extension API gives access to a Java AST (Abstract Syntax Tree) withing the context of so-called printer adapters. Printer adapters follow a decorator pattern so that they can be chained to extend and/or override the way JSweet will print out the intermediate TypeScript code.
+For instance, say you have a legacy Java code that uses the Java API for serializing objects (\texttt{writeObject}/\texttt{readObject}). With JSweet, you can easily erase these methods from your program, so that the generated JavaScript code is free from any Java-specific serialization idioms. 
+
+As another example, say you have a Java legacy code base that uses a Java API, which is close to (but not exactly) a JavaScript API you want to use in your final JavaScript code. With JSweet, you can write an adapter that will automatically map all the Java calls to the corresponding JavaScript calls. 
+
+Last but not least, you can tune JSweet to take advantage of some specific APIs depending on the context. For instance, you may use ES6 maps if you know that your targeted browser supports them, or just use an emulation or a simpler implementation in other cases. You may adapt the code to avoid using some canvas or WebGL primitives when knowing they are not well supported for a given mobile browser. An so on... Using an Open Transpiler such as JSweet has many practical applications, which you may or may not have to use, but in any case it is good to be aware of what is possible.
+
+Tuning can be done declaratively (as opposed to programmatically) using annotations. Annotations can be added to the Java program (hard-coded), or they can be centralized in a unique configuration file so that they don't even appear in the Java code (we call them soft annotations). Using annotations is quite simple and intuitive. However, when complex customization of the transpiler is required, it is most likely that annotations are not sufficient anymore. In that case, programmers shall use the JSweet extension API, which entails all the tuning that can be done with annotations, and much more. The extension API gives access to a Java AST (Abstract Syntax Tree) within the context of so-called \emph{printer adapters}. Printer adapters follow a decorator pattern so that they can be chained to extend and/or override the way JSweet will print out the intermediate TypeScript code.
 
 \section{Core annotations}
 
-The package \texttt{jsweet.lang} defines various annotation that can be used to tune the way JSweet generates the intermediate TypeScript code. Here we explain these annotations and give examples on how to use them.
+The package \texttt{jsweet.lang} defines various annotations that can be used to tune the way JSweet generates the intermediate TypeScript code. Here we explain these annotations and give examples on how to use them.
 
 \begin{itemize}
 \item \texttt{@Erased}: This annotation type is used on elements that should be erased at generation time. It can be applied to any program element. If applied to a type, casts and constructor invocations will automatically be removed, potentially leading to program inconsistencies. If applied to a method, invocations will be removed, potentially leading to program inconsistency, especially when the invocation's result is used in an expression. Because of potential inconsistencies, programmers should use this annotation carefully, and applied to unused elements (also erasing using elements).
@@ -1428,7 +1434,7 @@ The package \texttt{jsweet.lang} defines various annotation that can be used to
 \item \texttt{\{\{methodName\}\}}: the current method name.
 \item \texttt{\{\{body\}\}}: the body of the current method. A typical use of this variable
  is to wrap the original behavior in a lambda. For instance:
- \texttt{/* before code */ let \_result = () => \{ \{\{body\}\} \}(); /* after code */ return result;}.
+ \texttt{/* before code */ let \_result = () => \{ \{\{body\}\} \}(); /* after code */ return \_result;}.
 \item \texttt{\{\{baseIndent\}\}}: the indentation of the replaced method. Can be used to generate well-formatted code.
 \item \texttt{\{\{indent\}\}}: substituted with an indentation. Can be used to generate well-formatted code.
 \end{itemize}