From 5e45211a64149b3c659b90ff2de6fa982a5a93ed Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 4 May 2024 14:17:33 +0200 Subject: Adding upstream version 15.5. Signed-off-by: Daniel Baumann --- doc/src/sgml/images/README | 65 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 doc/src/sgml/images/README (limited to 'doc/src/sgml/images/README') diff --git a/doc/src/sgml/images/README b/doc/src/sgml/images/README new file mode 100644 index 0000000..07c4580 --- /dev/null +++ b/doc/src/sgml/images/README @@ -0,0 +1,65 @@ +Images +====== + +This directory contains images for use in the documentation. + +Creating an image +----------------- + +A variety of tools can be used to create an image. The appropriate +choice depends on the nature of the image. We prefer workflows that +involve diffable source files. + +These tools are acceptable: + +- Graphviz (https://graphviz.org/) +- Ditaa (http://ditaa.sourceforge.net/) + +We use SVG as the format for integrating the image into the ultimate +output formats of the documentation, that is, HTML, PDF, and others. +Therefore, any tool used needs to be able to produce SVG. + +This directory contains makefile rules to build SVG from common input +formats, using some common styling. + +fixup-svg.xsl applies some postprocessing to the SVG files produced by +those external tools to address assorted issues. See comments in +there, and adjust and expand as necessary. + +Both the source and the SVG output file are committed in this +directory. That way, we don't need all developers to have all the +tools installed. While we accept that there could be some gratuitous +diffs in the SVG output depending the specific tool, let's keep an eye +on that and keep it to a minimum. + +Using an image in DocBook +------------------------- + +Here is an example for using an image in DocBook: + +
+ GIN Internals + + + + + +
+ +Notes: + +- The real action is in the element, but typically a +
should be wrapped around it and an to the figure + should be put into the text somewhere. Don't just put an image into + the documentation without a link to it and an explanation of it. + +- Things are set up so that we only need one element, even + with different output formats. + +- The attribute format="SVG" is required. If you omit it, it will + still appear to work, but the stylesheets do a better job if the + image is declared as SVG explicitly. + +- The width should be set to something. This ensures that the image + is scaled to fit the page in PDF output. (Other widths than 100% + might be appropriate.) -- cgit v1.2.3