[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / doc / graphics.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="doc.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="doc.html" title='Documenting Python' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="futures.html" />
<link rel="prev" href="tools.html" />
<link rel="parent" href="doc.html" />
<link rel="next" href="futures.html" />
<meta name='aesop' content='information' />
<title>8 Including Graphics </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.3 Working on Cygwin"
  href="cygwin.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="Documenting Python"
  href="doc.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="9 Future Directions"
  href="futures.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Documenting Python</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="cygwin.html">7.3 Working on Cygwin</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="doc.html">Documenting Python</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="futures.html">9 Future Directions</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION000900000000000000000"></A><A NAME="graphics"></A>
<BR>
8 Including Graphics 
</H1>

<P>
The standard documentation included with Python makes no use of
  diagrams or images; this is intentional.  The outside tools used to
  format the documentation have not always been suited to working with
  graphics.  As the tools have evolved and been improved by their
  maintainers, support for graphics has improved.

<P>
The internal tools, starting with the <b class="program">mkhowto</b> script, do
  not provide any direct support for graphics.  However,
  <b class="program">mkhowto</b> will not interfere with graphics support in the
  external tools.

<P>
Experience using graphics together with these tools and the
  <code>howto</code> and <code>manual</code> document classes is not extensive,
  but has been known to work.  The basic approach is this:

<P>

<OL>
<LI>Create the image or graphic using your favorite
          application.

<P>
</LI>
<LI>Convert the image to a format supported by the conversion to
          your desired output format.  If you want to generate HTML or
          PostScript, you can convert the image or graphic to
          encapsulated PostScript (a <span class="file">.eps</span> file); <span class="LaTeX">LaTeX</span>2HTML
          can convert that to a <span class="file">.gif</span> file; it may be possible
          to provide a <span class="file">.gif</span> file directly.  If you want to
          generate PDF, you need to provide an ``encapsulated'' PDF
          file.  This can be generated from encapsulated PostScript
          using the <b class="program">epstopdf</b> tool provided with the te<span class="TeX">TeX</span>
          distribution on Linux and <span class="Unix">Unix</span>.

<P>
</LI>
<LI>In your document, add this line to ``import'' the general
          graphics support package <code>graphicx</code>:

<P>
<div class="verbatim"><pre>
\usepackage{graphicx}
</pre></div>

<P>
</LI>
<LI>Where you want to include your graphic or image, include
          markup similar to this:

<P>
<div class="verbatim"><pre>
\begin{figure}
  \centering
  \includegraphics[width=5in]{myimage}
  \caption{Description of my image}
\end{figure}
</pre></div>

<P>
In particular, note for the <tt class='macro'>&#92;includegraphics</tt> macro
          that no file extension is provided.  If you're only
          interested in one target format, you can include the
          extension of the appropriate input file, but to allow
          support for multiple formats, omitting the extension makes
          life easier.

<P>
</LI>
<LI>Run <b class="program">mkhowto</b> normally.
  
</LI>
</OL>

<P>
If you're working on systems which support some sort of
  <b class="program">make</b> facility, you can use that to ensure the intermediate
  graphic formats are kept up to date.  This example shows a
  <span class="file">Makefile</span> used to format a document containing a diagram
  created using the <b class="program">dia</b> application:

<P>
<div class="verbatim"><pre>
default: pdf
all:     html pdf ps

html:   mydoc/mydoc.html
pdf:    mydoc.pdf
ps:     mydoc.ps

mydoc/mydoc.html:  mydoc.tex mygraphic.eps
        mkhowto --html $&lt;

mydoc.pdf:  mydoc.tex mygraphic.pdf
        mkhowto --pdf $&lt;

mydoc.ps:   mydoc.tex mygraphic.eps
        mkhowto --postscript $&lt;

.SUFFIXES: .dia .eps .pdf

.dia.eps:
        dia --nosplash --export $@ $&lt;

.eps.pdf:
        epstopdf $&lt;
</pre></div> 
<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.3 Working on Cygwin"
  href="cygwin.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="Documenting Python"
  href="doc.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="9 Future Directions"
  href="futures.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Documenting Python</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="cygwin.html">7.3 Working on Cygwin</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="doc.html">Documenting Python</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="futures.html">9 Future Directions</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
86530b38 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="doc.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="doc.html" title='Documenting Python' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='last' href='about.html' title='About this document...' />
	10	<link rel='help' href='about.html' title='About this document...' />
	11	<link rel="next" href="futures.html" />
	12	<link rel="prev" href="tools.html" />
	13	<link rel="parent" href="doc.html" />
	14	<link rel="next" href="futures.html" />
	15	<meta name='aesop' content='information' />
	16	<title>8 Including Graphics </title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="7.3 Working on Cygwin"
	24	href="cygwin.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="Documenting Python"
	27	href="doc.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="9 Future Directions"
	30	href="futures.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Documenting Python</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><img src='../icons/blank.png'
	37	border='0' height='32' alt='' width='32' /></td>
	38	<td class='online-navigation'><img src='../icons/blank.png'
	39	border='0' height='32' alt='' width='32' /></td>
	40	</tr></table>
	41	<div class='online-navigation'>
	42	<b class="navlabel">Previous:</b>
	43	<a class="sectref" rel="prev" href="cygwin.html">7.3 Working on Cygwin</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="doc.html">Documenting Python</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="futures.html">9 Future Directions</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H1><A NAME="SECTION000900000000000000000"></A><A NAME="graphics"></A>
	54	<BR>
	55	8 Including Graphics
	56	</H1>
	57
	58	<P>
	59	The standard documentation included with Python makes no use of
	60	diagrams or images; this is intentional. The outside tools used to
	61	format the documentation have not always been suited to working with
	62	graphics. As the tools have evolved and been improved by their
	63	maintainers, support for graphics has improved.
	64
65	<P>
66	The internal tools, starting with the <b class="program">mkhowto</b> script, do
67	not provide any direct support for graphics. However,
68	<b class="program">mkhowto</b> will not interfere with graphics support in the
69	external tools.
70
71	<P>
72	Experience using graphics together with these tools and the
73	<code>howto</code> and <code>manual</code> document classes is not extensive,
74	but has been known to work. The basic approach is this:
75
76	<P>
77
78	<OL>
79	<LI>Create the image or graphic using your favorite
80	application.
81
82	<P>
83	</LI>
84	<LI>Convert the image to a format supported by the conversion to
85	your desired output format. If you want to generate HTML or
86	PostScript, you can convert the image or graphic to
87	encapsulated PostScript (a <span class="file">.eps</span> file); <span class="LaTeX">LaTeX</span>2HTML
88	can convert that to a <span class="file">.gif</span> file; it may be possible
89	to provide a <span class="file">.gif</span> file directly. If you want to
90	generate PDF, you need to provide an ``encapsulated'' PDF
91	file. This can be generated from encapsulated PostScript
92	using the <b class="program">epstopdf</b> tool provided with the te<span class="TeX">TeX</span>
93	distribution on Linux and <span class="Unix">Unix</span>.
94
95	<P>
96	</LI>
97	<LI>In your document, add this line to ``import'' the general
98	graphics support package <code>graphicx</code>:
99
100	<P>
101	<div class="verbatim"><pre>
102	\usepackage{graphicx}
103	</pre></div>
104
105	<P>
106	</LI>
107	<LI>Where you want to include your graphic or image, include
108	markup similar to this:
109
110	<P>
111	<div class="verbatim"><pre>
112	\begin{figure}
113	\centering
114	\includegraphics[width=5in]{myimage}
115	\caption{Description of my image}
116	\end{figure}
117	</pre></div>
118
119	<P>
120	In particular, note for the <tt class='macro'>\includegraphics</tt> macro
121	that no file extension is provided. If you're only
122	interested in one target format, you can include the
123	extension of the appropriate input file, but to allow
124	support for multiple formats, omitting the extension makes
125	life easier.
126
127	<P>
128	</LI>
129	<LI>Run <b class="program">mkhowto</b> normally.
130
131	</LI>
132	</OL>
133
134	<P>
135	If you're working on systems which support some sort of
136	<b class="program">make</b> facility, you can use that to ensure the intermediate
137	graphic formats are kept up to date. This example shows a
138	<span class="file">Makefile</span> used to format a document containing a diagram
139	created using the <b class="program">dia</b> application:
140
141	<P>
142	<div class="verbatim"><pre>
143	default: pdf
144	all: html pdf ps
145
146	html: mydoc/mydoc.html
147	pdf: mydoc.pdf
148	ps: mydoc.ps
149
150	mydoc/mydoc.html: mydoc.tex mygraphic.eps
151	mkhowto --html $<
152
153	mydoc.pdf: mydoc.tex mygraphic.pdf
154	mkhowto --pdf $<
155
156	mydoc.ps: mydoc.tex mygraphic.eps
157	mkhowto --postscript $<
158
159	.SUFFIXES: .dia .eps .pdf
160
161	.dia.eps:
162	dia --nosplash --export $@ $<
163
164	.eps.pdf:
165	epstopdf $<
166	</pre></div>
167	<P>
168
169	<DIV CLASS="navigation">
170	<div class='online-navigation'>
171	<p></p><hr />
172	<table align="center" width="100%" cellpadding="0" cellspacing="2">
173	<tr>
174	<td class='online-navigation'><a rel="prev" title="7.3 Working on Cygwin"
175	href="cygwin.html"><img src='../icons/previous.png'
176	border='0' height='32' alt='Previous Page' width='32' /></A></td>
177	<td class='online-navigation'><a rel="parent" title="Documenting Python"
178	href="doc.html"><img src='../icons/up.png'
179	border='0' height='32' alt='Up One Level' width='32' /></A></td>
180	<td class='online-navigation'><a rel="next" title="9 Future Directions"
181	href="futures.html"><img src='../icons/next.png'
182	border='0' height='32' alt='Next Page' width='32' /></A></td>
183	<td align="center" width="100%">Documenting Python</td>
184	<td class='online-navigation'><a rel="contents" title="Table of Contents"
185	href="contents.html"><img src='../icons/contents.png'
186	border='0' height='32' alt='Contents' width='32' /></A></td>
187	<td class='online-navigation'><img src='../icons/blank.png'
188	border='0' height='32' alt='' width='32' /></td>
189	<td class='online-navigation'><img src='../icons/blank.png'
190	border='0' height='32' alt='' width='32' /></td>
191	</tr></table>
192	<div class='online-navigation'>
193	<b class="navlabel">Previous:</b>
194	<a class="sectref" rel="prev" href="cygwin.html">7.3 Working on Cygwin</A>
195	<b class="navlabel">Up:</b>
196	<a class="sectref" rel="parent" href="doc.html">Documenting Python</A>
197	<b class="navlabel">Next:</b>
198	<a class="sectref" rel="next" href="futures.html">9 Future Directions</A>
199	</div>
200	</div>
201	<hr />
202	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
203	</DIV>
204	<!--End of Navigation Panel-->
205	<ADDRESS>
206	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
207	</ADDRESS>
208	</BODY>
209	</HTML>