Commit 79f8eb7e authored by Ingo Heimbach's avatar Ingo Heimbach

Updated and improved the README file

parent 2852de83
......@@ -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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment