Updated and improved the README file

README.md

@@ -17,19 +17,44 @@ pip install git+https://iffgit.fz-juelich.de/doc-utils/doc-utils
 After installing you can use the extended rst writers `rst2latex-extended` and `rst2html-extended` that are compatible
 with the standard versions but offer additional features:
 
-- Code blocks are formatted with the `minted` package (LaTeX only)
-- Images can be embedded into the generated document (`embedded-image` directive, HTML only; for LaTeX this is already
-  the default behavior)
-- Support for TikZ images by `tikz` and `tikz-figure` directives. TikZ code can be loaded from an external file or
-  written as embedded source. `rst2html-extended` needs either `pdf2svg` or `mupdf-tools` to support TikZ pictures.
-  `pdf2svg` is recommended because it produces SVG images without any quality loss.
+-   Code blocks are formatted with the `minted` package (LaTeX only).
+-   Images can be embedded into the generated document (`embedded-image` and `embedded-figure` directives). Adds an
+    additional convert step if the graphics format is not suitable for the output (SVG images are converted to PDF and
+    GIF to PNG for LaTeX output). If the image path is a web link, the image is downloaded before.
+-   Support for TikZ images by `tikz` and `tikz-figure` directives. TikZ code can be loaded from an external file or
+    written as embedded source. `rst2html-extended` needs either `pdf2svg` or `mupdf-tools` to support TikZ pictures.
+    `pdf2svg` is recommended because it produces SVG images without any quality loss.
+
+
+### Directive options
+
+-   `tikz` and `tikz-figure`:
+
+    -   Both directives inherit `alt`, `height`, `width`, `scale`, `align`, `name`, `target` and `class` from the `image`
+        directive.
+    -   Both directives have the additional options:
+
+        -   `document_options`: Extra options for the LaTeX
+            [`standalone` document class](https://ctan.org/pkg/standalone?lang=en)
+        -   `lang`: Babel language
+        -   `do_not_use_default_packages`: Do not load these default packages: `inputenc`, `fontenc`, `lmodern`,
+            `babel`, `xcolor`, `graphicx`
+        -   `extra_packages`: Extra packages to load, can be used like this: `[options]{package};[options]{package}`
+        -   `tikz_libs`: Additional TikZ libraries to load, separated by comma, e.g.: `arrows,calc`
+        -   `tikzpicture_options`: Additional tikzpicture options, for example: `overlay`
+
+    -   The `tikz-figure` directive has the additional options `figwidth` and `caption` like other `figure` objects.
+
+-   `embedded-image` and `embedded-figure`:
+
+    -   All options are identical to the usual `image` and `figure` directives.
 
 
 ## Files
 
-- `styles/rst2html_githublike_fzj.css`: Stylesheet for `rst2html` with fzj blue for strong emphasized text; Using
-  `--syntax-highlight=short` option with `rst2html` is recommended but long class names are also included in the this
-  CSS file
-- `styles/rst2latex_fzj.sty`: Style with fzj colors and a custom title page
-- `styles/rst2luatex_fzj.sty`: Style with fzj colors and a custom title page for use with LuaTex / LuaLaTeX
-- `utils/Makefile`: Example Makefile for generating PDFs and HTML pages from Markdown and reStructuredText documents
+-   `styles/rst2html_githublike_fzj.css`: Stylesheet for `rst2html` with fzj blue for strong emphasized text; Using
+    `--syntax-highlight=short` option with `rst2html` is recommended but long class names are also included in the this
+    CSS file.
+-   `styles/rst2latex_fzj.sty`: Style with fzj colors and a custom title page
+-   `styles/rst2luatex_fzj.sty`: Style with fzj colors and a custom title page for use with LuaTex / LuaLaTeX
+-   `utils/Makefile`: Example Makefile for generating PDFs and HTML pages from Markdown and reStructuredText documents