From 4736b10accf6fc5c350120b69838b1a35170793a Mon Sep 17 00:00:00 2001 From: Nik Clayton Date: Sun, 29 Oct 2000 20:20:25 +0000 Subject: Describe how to go about adding images to the documentation. A little rushed, but it should be enough to get people using it, and, more importantly, improving on it. --- .../books/fdp-primer/sgml-markup/chapter.sgml | 233 ++++++++++++++++++++- 1 file changed, 232 insertions(+), 1 deletion(-) (limited to 'en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml') diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml index d5cfbfc947..39b0feb120 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -27,7 +27,7 @@ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.14 2000/07/16 16:40:09 nik Exp $ + $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.15 2000/07/17 19:01:58 ben Exp $ --> @@ -2103,6 +2103,237 @@ This is the file called 'foo2' + + Images + + + Image support in the documentation is currently extremely + experimental. I think the mechanisms described here are unlikely to + change, but that's not guaranteed. + + You will also need to install the + graphics/ImageMagick port, which is used to + convert between the different image formats. This is a big port, + and most of it is not required. However, while we're working on the + Makefiles and other infrastructure it makes + things easier. This port is not in the + textproc/docproj meta port, you must install it + by hand. + + The best example of what follows in practice is the + en_US.ISO_8859-1/articles/vm-design/ document. + If you're unsure of the description that follows, take a look at the + files in that directory to see how everything hangs togther. + Experiment with creating different formatted versions of the + document to see how the image markup appears in the formatted + output. + + + + Image formats + + We currently support two formats for images. The format you + should use will depend on the nature of your image. + + For images that are primarily vector based, such as network + diagrams, timelines, and similar, use Encapsulated Postscript, and + make sure that your images have the .eps + extension. + + For bitmaps, such as screen captures, use the Portable Network + Graphic format, and make sure that your images have the + .png extension. + + These are the only formats in which images + should be committed to the CVS repository. + + Use the right format for the right image. It is to be expected + that your documentation will have a mix of EPS and PNG images. The + Makefiles ensure that the correct format image + is chosen depending on the output format that you use for your + documentation. Do not commit the same image to the + repository in two different formats. + + + It is anticipated that the Documentation Project will switch to + using the Scalable Vector Graphic (SVG) format for vector images. + However, the current state of SVG capable editing tools makes this + impractical. + + + + + Markup + + The markup for an image is relatively simple. First, markup a + mediaobject. The mediaobject + can contain other, more specific objects. We are concerned with + two, the imageobject and the + textobject. + + You should include one imageobject, and two + textobject elements. The + imageobject will point to the name of the image + file that will be used (without the extension). The + textobject elements contain information that will + be presented to the user as well as, or instead of, the + image. + + There are two circumstances where this can happen. + + + + When the reader is viewing the documentation in HTML. In + this case, each image will need to have associated alternate + text to show the user, typically whilst the image is loading, or + if they hover the mouse pointer over the image. + + + + When the reader is viewing the documentation in plain text. + In this case, each image should have an ASCII art equivalent to + show the user. + + + + An example will probably make things easier to understand. + Suppose you have an image, called fig1, that + you want to include in the document. This image is of a rectangle + with an A inside it. The markup for this would be as + follows. + + <mediaobject> + <imageobject> + <imagedata fileref="fig1"> + </imageobject> + + <textobject> + <literallayout class="monospaced">+---------------+ +| A | ++---------------+</literallayout> + </textobject> + + <textobject> + <phrase>A picture</phrase> + </textobject> +</mediaobject> + + + + Include an imagedata element inside the + imageobject element. The + fileref attribute should contain the filename + of the image to include, without the extension. The stylesheets + will work out which extension should be added to the filename + automatically. + + + + The first textobject should contain a + literallayout element, where the + class attribute is set to + monospaced. This is your opportunity to + demonstrate your ASCII art skills. This content will be used if + the document is converted to plain text. + + Notice how the first and last lines of the content of the + literallayout element butt up next to the + element's tags. This ensures no extraneous white space is + included. + + + + The second textobject should contain a + single phrase element. The contents of this + will become the alt attribute for the image + when this document is converted to HTML. + + + + + + <filename>Makefile</filename> entries + + Your images must be listed in the + Makefile in the IMAGES + variable. This variable should contain the name of all your + source images. For example, if you have + created three figures, fig1.eps, + fig2.png, fig3.png, then + your Makefile should have lines like this in + it. + + … +IMAGES= fig1.eps fig2.png fig3.png +… + + or + + … +IMAGES= fig1.eps +IMAGES+= fig2.png +IMAGES+= fig3.png +… + + Again, the Makefile will work out the + complete list of images it needs to build your source document, you + only need to list the image files you + provided. + + + + Images and chapters in subdirectories + + You must be careful when you separate your documentation in to + smaller files (see ) in + different directories. + + Suppose you have a book with three chapters, and the chapters + are stored in their own directories, called + chapter1/chapter.sgml, + chapter2/chapter.sgml, and + chapter3/chapter.sgml. If each chapter has + images associated with it, I suggest you place those images in each + chapter's subdirectory (chapter1/, + chapter2/, and + chapter3/). + + However, if you do this you must include the directory names in + the IMAGES variable in the + Makefile, and you must + include the directory name in the imagedata + element in your document. + + For example, if you have chapter1/fig1.png, + then chapter1/chapter.sgml should + contain + + <mediaobject> + <imageobject> + <imagedata fileref="chapter1/fig1"> + </imageobject> + + … + +</mediaobject> + + + + The directory name must be included in the + fileref attribute + + + + The Makefile must contain + + … +IMAGES= chapter1/fig1.png +… + + Then everything should just work. + + + Links -- cgit v1.2.3