added doc for packaging

doc/jsweet-language-specifications.md

@@ -38,6 +38,7 @@ Content
     -   [Packages and modules](#packages-and-modules)
     -   [Root packages](#root-packages)
     -   [External modules](#external-modules)
+    -   [Packaging a JSweet jar (candy)](#packaging-a-jsweet-jar-candy)
 -   [Appendix 1: JSweet transpiler options](#appendix-1-jsweet-transpiler-options)
 -   [Appendix 2: JSweet strict mode](#appendix-2-jsweet-strict-mode)
 
@@ -999,6 +1000,30 @@ The above code shows an excerpt of the JSweet jQuery API. As we can notice, the
 
 Note: the notion of manual require of a module may be available in future releases. However, automatic require is sufficient for most programmers and hides the complexity of having to require modules explicitly. It also brings the advantage of having the same code whether modules are used or not.
 
+### Packaging a JSweet jar (candy)
+
+When creating a program (especially a library or a component) with JSweet, one may want to package it in a JSweet jar (a.k.a. a candy) and deploy it on a Maven repository, so that it can be used by other JSweet programs.
+
+Candies are regular Jars that can be generated with the Maven `package` goal. To be a valid candy and recognized as such by the JSweet transpiler, your jar file must contain two additional resources (to be placed in the resources directory of your Maven project so that they end up being packaged in your jar by Maven).
+
+1.  A `META-INF/candy-metadata.json` file that contains the expected target version of the transpiler (to be adapted to your target transpiler version).
+
+2.  The program’s declarations in `d.ts` files, to be placed in the `src/typings` directory of the jar.
+
+Here is an example of the `META-INF/candy-metadata.json` file:
+
+``` java
+{
+   "transpilerVersion": "1.0.0"
+}
+```
+
+Typically, `d.ts` files shall be generated by the JSweet transpiler using the following options:
+
+-   `–declaration`: turns on the generation of the `d.ts` files.
+
+-   `–dtsout`: tells where to put the generated `d.ts` files (for packaging, place them in `RESOURCES/src/typings`, where `RESOURCES` is your Maven project resources directory).
+
 Appendix 1: JSweet transpiler options
 -------------------------------------
 
@@ -1031,6 +1056,15 @@ Appendix 1: JSweet transpiler options
             Specify where to place generated JavaScript files (ignored if jsFile is
             specified). (default: js)
 
+      [--declaration]
+            Tells the transpiler to generate the d.ts files along with the js files,
+            so that other programs can use them to compile.
+
+      [--dtsout <dtsout>]
+            Specify where to place generated d.ts files when the declaration option
+            is set (by default, d.ts files are generated in the JavaScript output
+            directory - next to the corresponding js files).
+
       [--classpath <classpath>]
             The JSweet transpilation classpath (candy jars). This classpath should
             at least contain the core candy.

doc/jsweet-language-specifications.tex

@@ -1027,6 +1027,32 @@ The above code shows an excerpt of the JSweet jQuery API. As we can notice, the
 
 Note: the notion of manual require of a module may be available in future releases. However, automatic require is sufficient for most programmers and hides the complexity of having to require modules explicitly. It also brings the advantage of having the same code whether modules are used or not.
 
+\section{Packaging a JSweet jar (candy)}
+
+When creating a program (especially a library or a component) with JSweet, one may want to package it in a JSweet jar (a.k.a. a candy) and deploy it on a Maven repository, so that it can be used by other JSweet programs.
+
+Candies are regular Jars that can be generated with the Maven \texttt{package} goal. To be a valid candy and recognized as such by the JSweet transpiler, your jar file must contain two additional resources (to be placed in the resources directory of your Maven project so that they end up being packaged in your jar by Maven).
+
+\begin{enumerate}
+\item A \texttt{META-INF/candy-metadata.json} file that contains the expected target version of the transpiler (to be adapted to your target transpiler version).
+\item The program's declarations in \texttt{d.ts} files, to be placed in the \texttt{src/typings} directory of the jar.
+\end{enumerate}
+
+Here is an example of the \texttt{META-INF/candy-metadata.json} file:
+
+\begin{lstlisting}[language=Java]
+{
+   "transpilerVersion": "1.0.0"
+}
+\end{lstlisting}
+
+Typically, \texttt{d.ts} files shall be generated by the JSweet transpiler using the following options:
+
+\begin{itemize}
+\item \texttt{--declaration}: turns on the generation of the \texttt{d.ts} files. 
+\item \texttt{--dtsout}: tells where to put the generated \texttt{d.ts} files (for packaging, place them in \texttt{RESOURCES/src/typings}, where \texttt{RESOURCES} is your Maven project resources directory). 
+\end{itemize}
+
 \chapter*{Appendix 1: JSweet transpiler options}
 
 \begin{verbatim}
@@ -1059,6 +1085,15 @@ Note: the notion of manual require of a module may be available in future releas
         Specify where to place generated JavaScript files (ignored if jsFile is
         specified). (default: js)
 
+  [--declaration]
+        Tells the transpiler to generate the d.ts files along with the js files,
+        so that other programs can use them to compile.
+
+  [--dtsout <dtsout>]
+        Specify where to place generated d.ts files when the declaration option
+        is set (by default, d.ts files are generated in the JavaScript output
+        directory - next to the corresponding js files).
+
   [--classpath <classpath>]
         The JSweet transpilation classpath (candy jars). This classpath should
         at least contain the core candy.
@@ -1090,7 +1125,6 @@ Note: the notion of manual require of a module may be available in future releas
   [--ignoreAssertions]
         Set the transpiler to ignore 'assert' statements, i.e. no code is
         generated for assertions.
-
 \end{verbatim}
 
 \chapter*{Appendix 2: JSweet strict mode}