add instructions for screenshots

3 files changed, 213 insertions, 7 deletions

diff --git a/acknowledgments-en.xml b/acknowledgments-en.xml
index 536b3c1..df438be 100644
--- a/acknowledgments-en.xml
+++ b/acknowledgments-en.xml
@@ -21,12 +21,18 @@
     
     <para>
       A patch from Gavin Henry (ghenry at suretecsystems.com) has been applied to
-      add the <xref linkend="ch-emacs-nxml"></xref>.
+      add <xref linkend="ch-emacs-nxml"></xref>.
     </para>
 
     <para>
       A patch from Joshua Daniel Franklin (joshuadfranklin at yahoo.com) has been
-      applied to add the <xref linkend="ch-vim"></xref>.
+      applied to add <xref linkend="ch-vim"></xref>.
     </para>
 
+    <para>
+      A patch from Karsten Wade (kwade at redhat.com) has been applied to add
+      <xref linkend="s1-screenshots"></xref>. It was edited by Paul
+      W. Friends (stickstr5 at hotmail.com).
+  </para>
+
   </chapter>
diff --git a/docs-rh-guidelines-en.xml b/docs-rh-guidelines-en.xml
index fd4f72c..c799abc 100644
--- a/docs-rh-guidelines-en.xml
+++ b/docs-rh-guidelines-en.xml
@@ -181,14 +181,14 @@
 
 <screen>
 <computeroutput>
-&lt;!-- $Id: docs-rh-guidelines-en.xml,v 1.1 2003/09/22 16:34:23 tfox Exp $ --&gt;
+&lt;!-- $Id: docs-rh-guidelines-en.xml,v 1.2 2004/08/31 15:45:29 tfox Exp $ --&gt;
 </computeroutput>
 </screen>
 
     </sect1>
 
     <sect1 id="s1-xml-admon">
-      <title>Working with Admonitions</title>
+      <title>Admonitions</title>
 
       <indexterm>
 	<primary>admonitions</primary>
@@ -379,6 +379,206 @@
 
     </sect1>
 
+    <sect1 id="s1-screenshots">
+      <title>Screenshots</title>
+
+      <indexterm>
+	<primary>screenshots</primary>
+	<secondary>how to take</secondary>
+      </indexterm>
+      <indexterm>
+	<primary>screen captures</primary>
+	<see>screenshots</see>
+      </indexterm>
+      <indexterm>
+	<primary>screen grabs</primary>
+	<see>screenshots</see>
+      </indexterm>
+
+      <para>
+	There are two types of screenshots: graphical and textual.  The
+	philosophy on using these two types is <firstterm>rely on text over
+	graphics</firstterm>.  This means, if you can say it in text instead of
+	showing a graphic, do so.  A graphical screenshot of a GUI can create a good
+	setting of objects to then describe textually, but you don't want to create
+	a screenshot for each graphical step.
+      </para>
+      <para>
+	The main reason for this preference is that a block of text can usually
+	convey more meaning than the same physical space of graphics.  This is
+	highly dependent on the graphic; obviously, a photographic image of a
+	scene can convey more than 1000 words can.  A GUI screenshot is usually
+	full of blank space with a few elements that can just as easily be
+	described or listed.
+      </para>
+      <para>
+	The steps for taking a graphical screenshot illustrate how using text to
+	describe a procedure is more concise than a series of screenshots.
+      </para>
+      <variablelist>
+	<varlistentry>
+	  <term>Graphical Screenshot</term>
+	  <listitem>
+	    <procedure>
+	      <step>
+		<para>
+		  Set the theme to Bluecurve defaults.  This gives a look that
+		  is familiar to most readers, and makes &FDP; documents
+		  consistent. From the panel menu, choose
+		  <guimenu>Preferences</guimenu>,
+		  <guimenuitem>Theme</guimenuitem> and select
+		  <guimenuitem>Bluecurve</guimenuitem> from the theme list.
+		</para>
+	      </step>
+	      <step>
+	        <para>
+		  Set fonts to Bluecurve defaults as well. From the panel menu,
+		  choose <guimenu>Preferences</guimenu>,
+		  <guimenuitem>Fonts</guimenuitem>. Set the
+		  <guilabel>Application font</guilabel> and the
+		  <guilabel>Desktop font</guilabel> to Sans Regular 10. Set the
+		  <guilabel>Window Title font</guilabel> to Sans Bold 10. Set
+		  the <guilabel>Terminal font</guilabel> to Monospace Regular
+		  10.
+	        </para>
+ 	      </step>
+	      <step>
+		<para>
+		  Before taking the screenshot, try to resize the targeted GUI
+		  element(s) to the smallest possible size they can be.  Your
+		  target is an image of 500 pixels or less.  If you are doing a
+		  screenshot of more than one GUI element, you may need to
+		  resize the screenshot in a following step.
+		</para>
+	      </step>
+	      <step>
+		<para>
+		  To take the screenshot, select the GUI element with your
+		  mouse, bringing it to the forefront, or otherwise arranging
+		  the elements.  Press <keycombo> <keycap>Alt</keycap>
+		  <keycap>Print Screen</keycap> </keycombo> to capture a single
+		  GUI window.  For capturing the entire desktop use
+		  <keycap>Print Screen</keycap>.  If you are taking a shot of
+		  multiple elements and have grouped them closely together, you
+		  can crop the resulting image in <application>The
+		  GIMP</application>.  The image will be in the PNG format.
+		</para>
+	      </step>
+	      <step>
+		<para>
+		  If you need to, you can resize using <application>The
+		  GIMP</application>.  With the image open, right-click on it
+		  and choose <guimenu>Image</guimenu> -&gt; <guimenuitem>Scale
+		  Image...</guimenuitem>.  With the chain symbol intact, set the
+		  <guilabel>New Width</guilabel> to <guilabel>500 px</guilabel>,
+		  and click <guibutton>OK</guibutton>.  Be sure to <keycombo>
+		  <keycap>Ctrl</keycap> <keycap>s</keycap> </keycombo> to save
+		  your changes to your PNG before converting to EPS.
+		</para>
+	      </step>
+	      <step>
+		<para>
+		  With the image open in <application>The GIMP</application>,
+		  right-click on the image, selecting <guimenu>File</guimenu>
+		  -&gt; <guimenuitem>Save As...</guimenuitem>.  Under
+		  <guimenu>Determine File Type:</guimenu>, select
+		  <guimenuitem>PostScript</guimenuitem>, then click
+		  <guibutton>OK</guibutton>. Allow flattening of the image by
+		  clicking <guibutton>Export</guibutton>.
+		</para>
+		<para>
+		  In the <guilabel>Save as PostScript</guilabel> window, select
+		  <guilabel>Encapsulated PostScript</guilabel>, and click
+		  <guibutton>OK</guibutton>.
+		</para>
+	      </step>
+	    </procedure>
+	    <para>
+	      For more information about calling the images from the XML, refer
+	      to <xref linkend="s1-xml-tags-figure"/>.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>Text Screenshot</term>
+	  <listitem>
+	    <para>Textual screen information is also useful for readers. If you
+	      use a graphical screenshot to illustrate a function, and the
+	      textual mode has identical functions, you should not include
+	      both, unless omitting either would make your description
+	      unclear. You should make your information generic over specific.
+	      Omit the username and machine information, and separate what the
+	      user types from sample command output. Also, in
+	      <command>screen</command> tags, what the user types should be in
+	      <command>userinput</command> tags, and what the user is shown as
+	      output should be in <command>computeroutput</command> tags.
+	      For example, the usage in
+	      <xref linkend="ex-text-screenshot-bad"/> should look like <xref
+	      linkend="ex-text-screenshot-good"/>.
+	    </para>
+	    <example id="ex-text-screenshot-bad">
+	      <title>Incorrect Textual Screenshot</title>
+	      <screen>
+<userinput>ps ax | grep ssh</userinput>
+<computeroutput>
+ 2564 ?        S      0:23 /usr/sbin/sshd
+ 3092 ?        S      0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients
+ 8235 ?        S      0:00 ssh -Nf rocky@philadelphia.net -L 6667:localhost
+17223 pts/0    S      0:00 ssh rbalboa@core-router7
+17227 pts/2    S      0:10 ssh rbalboa@smbshare2
+21113 pts/7    S      1:19 ssh rocky@xxx.private
+</computeroutput>
+	      </screen>
+	    </example>
+	    <example id="ex-text-screenshot-good">
+	      <title>Correct Textual Screenshot</title>
+	      <para>
+		To find all the currently active ssh sessions, execute the
+		following command:
+	      </para>
+<screen>
+<command>ps ax | grep ssh</command>
+</screen>
+
+	      <para>
+		The output will appear similar to:
+	      </para>
+
+	      <screen>
+<computeroutput>
+ 2564 ?        S      0:23 /usr/sbin/sshd
+ 3092 ?        S      0:00 /usr/bin/ssh-agent /etc/X11/xinit/Xclients
+ 8032 pts/0    S      0:00 ssh user@host.example.com
+ 8032 pts/1    S      0:00 ssh root@backup.example.com
+</computeroutput>
+	      </screen>
+	    </example>
+	    <para>
+	      For more information about using screen, refer to <xref
+	      linkend="s1-xml-tags-screen"/>.
+	    </para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect1>
+ 
+    <sect1 id="s1-diagrams-images">
+      <title>Diagrams and Images</title>
+
+      <indexterm>
+	<primary>images</primary>
+      </indexterm>
+      <indexterm>
+	<primary>diagrams</primary>
+	<secondary>creating</secondary>
+      </indexterm>
+
+      <para>
+	To be written
+      </para>
+
+    </sect1>	
+
   </chapter>
 
 
diff --git a/documentation-guide-en.xml b/documentation-guide-en.xml
index 4ffd001..1ce16b5 100644
--- a/documentation-guide-en.xml
+++ b/documentation-guide-en.xml
@@ -1,4 +1,4 @@
-<!-- $Id: documentation-guide-en.xml,v 1.13 2004/08/13 16:08:48 tfox Exp $ -->
+<!-- $Id: documentation-guide-en.xml,v 1.14 2004/08/31 15:45:29 tfox Exp $ -->
 
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
@@ -6,9 +6,9 @@
 <!ENTITY % FEDORA-ENTITIES-EN SYSTEM "../common/fedora-entities-en.xml">
 %FEDORA-ENTITIES-EN;
 
-<!ENTITY VERSION "0.2.3"> <!-- version for this document -->
+<!ENTITY VERSION "0.2.4"> <!-- version for this document -->
 
-<!ENTITY BOOKID "documentation-guide-&VERSION; (2004-08-13)"> <!-- change date here and VERSION entity everytime a change is made-->
+<!ENTITY BOOKID "documentation-guide-&VERSION; (2004-08-31)"> <!-- change date here and VERSION entity everytime a change is made-->
 
 <!ENTITY LEGALNOTICE SYSTEM "../common/legalnotice-en.xml">