Merge pull request #706 from jfbercher/latex_envs

latex_envs: update readme

src/jupyter_contrib_nbextensions/nbextensions/latex_envs/readme.md

@@ -1,7 +1,7 @@
 (some) LaTeX environments for Jupyter notebook
 ==============================================
 
-This extension for IPython 3.x or Jupyter enables to use some LaTeX commands and environments in the notebook's markdown cells. 
+This extension Jupyter notebook enables to use some LaTeX commands and environments in the notebook's markdown cells. 
 
 1. **LaTeX commands and environments**
  - support for some LaTeX commands within markdown cells, *e.g.* `\textit`, `\textbf`, `\underline`
@@ -14,52 +14,45 @@ This extension for IPython 3.x or Jupyter enables to use some LaTeX commands and
  -  support for `\cite` with creation of a References section, rendering of references can be customized (to some extent)
 3. **Document-wide numbering of equations, support for `\label` and `\ref`**
 4. **Configuration toolbar**
-5. Styles can be customized in the *latex\_env.css* stylesheet
+5. Styles can be customized in `latex\_env.css` or `custom.css` stylesheets. 
 
 More environments can be simply added in the source file (`thmsInNb4.js`). 
 
-The `conversion` directory contains scripts for converting the notebooks to html and LaTeX while taking into account the structures 
-enabled by the extension. Theses scripts require nodejs, perl, ipython3. Examples of such conversions are in the `doc` subdirectory that constains an example notebook and its html and pdf versions. This serves as the documentation.
+It is possible to export the notebooks to plain $\LaTeX$ and html while keeping all the features of the `latex_envs` notebook extension in the converted version. We provide specialized exporters, pre and post processors, templates. We also added entry-points to simplify the conversion process. It is now as simple asIt is now as simple as
+```bash
+jupyter nbconvert --to html_lenvs FILE.ipynb
+```
+or 
+```bash
+jupyter nbconvert --to latex_lenvs FILE.ipynb
+```
+to convert `FILE.ipynb` into html/latex while keeping all the features of the `latex_envs` notebook extension in the converted version. The LaTeX converter also expose several conversion options (read the docs). 
 
 
 Demo/documentation
 ==================
 
-A demo notebook `latex_env_doc.ipynb` is provided. Its html version is [latex_env_doc.html](https://rawgit.com/jfbercher/latex_envs/master/doc/latex_env_doc.html) and a pdf resulting 
-from conversion to LaTeX is available as [documentation](https://rawgit.com/jfbercher/latex_envs/master/doc/latex_env_doc.html). 
+The `doc` subdirectory that constains an example notebook and its html and pdf versions. This serves as the documentation. 
+A demo notebook `latex_env_doc.ipynb` is provided. Its html version is [latex_env_doc.html](https://rawgit.com/ipython-contrib/jupyter_contrib_nbextensions/master/src/jupyter_contrib_nbextensions/nbextensions/latex_envs/doc/latex_env_doc.html) and a pdf resulting 
+from conversion to LaTeX is available as [documentation](https://rawgit.com/ipython-contrib/jupyter_contrib_nbextensions/master/src/jupyter_contrib_nbextensions/nbextensions/latex_envs/doc/documentation.pdf). 
 
 
 Installation
 ============
 
-You should follow the instructions in the [wiki](https://github.com/ipython-contrib/jupyter_contrib_nbextensions/wiki).
-- Manual installation: Clone the repository and then copy the files to the notebook extension directory, usually ~/.local/share/jupyter/nebextensions (Jupyter) or ~/.ipython/nbextensions (IPython 3.x). Copy the scripts in conversion/ to some directory (preferably in your path).
-- Automated installation
-
-An even more simple procedure is to issue
-
-``` bash
-jupyter nbextension install https://rawgit.com/jfbercher/latex_envs/master/latex_envs.zip  --user
-```
+The extension consists in several javascript scripts: `latex_envs.js`, `thmsInNb4.js`, `bibInNb4.js` and `initNb.js`, together with a stylesheet `latex_envs.css`. You may follow the instructions in the [wiki](https://github.com/ipython-contrib/Jupyter-notebook-extensions/wiki) to install the extension.
 
-at the command line.
-Either load the extension from your `custom.js` or use a code cell with
+Definitively, the simplest way to install and enable the extension is to follow the instrutions in the [Jupyter-notebook-extensions repo](https://github.com/ipython-contrib/Jupyter-notebook-extensions/blob/master/README.md). Once this is done, you can open a tab at `http://localhost:8888/nbextensions` to enable and configurate the various extensions. 
 
-```jupyter
-%%javascript
-require("base/js/utils").load_extensions("latex_envs/latex_envs")
-```
 
-You can automatically load the extension via
+Disclaimer, sources and acknowledgments
+=======================================
 
-```bash
-jupyter nbextension enable latex_envs/latex_envs
-```
 
+This is done in the hope it can be useful. However there are many impovements possible, in the code and in the documentation. 
+**Contributions will be welcome and deeply appreciated.** 
 
-Disclaimer, sources and acknowledgments
-=======================================
+Originally, I used a piece of code from the nice online markdown editor `stackedit` [https://github.com/benweet/stackedit/issues/187](https://github.com/benweet/stackedit/issues/187), where the authors also considered the problem of incorporating LaTeX markup in their markdown. 
 
-Code certainly needs improvements. **Contributions, comments, issues are most welcome and will be deeply appreciated.**
+I also studied and used examples and code from [https://github.com/ipython-contrib/IPython-notebook-extensions](https://github.com/ipython-contrib/IPython-notebook-extensions). 
 
-The original idea and starting code come from a discussion here: [https://github.com/benweet/stackedit/issues/187](https://github.com/benweet/stackedit/issues/187). Examples and code from [https://github.com/ipython-contrib/jupyter_contrib_nbextensions](https://github.com/ipython-contrib/jupyter_contrib_nbextensions) were also used. The bibliography part was inspired by the nice extension  [icalico-document-tools](https://bitbucket.org/ipre/calico/downloads/).