<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
<!--ArborText, Inc., 1988-1999, v.4002-->
<!--ARC : LSARC 2005/734 GNOME For Nevada-->
<!--ARC : LSARC 2003/085 libtiff, libjpeg, and libpng-->
<!ENTITY exam-tt "EXAMPLES">
<!ENTITY cmd "wrjpgcom">
<!ENTITY % commonents SYSTEM "smancommon.ent">
%commonents;
<!ENTITY % booktitles SYSTEM "booktitles.ent">
%booktitles;
<!ENTITY suncopy "Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.">
]>
<?Pub UDT _bookmark _target>
<?Pub Inc>
<refentry id="wrjpgcom-1">
<!-- %Z%%M% %I% %E% SMI; -->
<refmeta><refentrytitle>wrjpgcom</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="date">26 Mar 2004</refmiscinfo>
<refmiscinfo class="sectdesc">&man1;</refmiscinfo>
<refmiscinfo class="software">&release;</refmiscinfo>
<refmiscinfo class="arch">generic</refmiscinfo>
<refmiscinfo class="copyright">&suncopy;</refmiscinfo>
</refmeta>
<indexterm><primary>wrjpgcom</primary></indexterm><indexterm><primary>insert
text comments into a JPEG file</primary></indexterm>
<refnamediv id="wrjpgcom-1-name"><refname>wrjpgcom</refname><refpurpose>insert
text comments into a JPEG file</refpurpose></refnamediv>
<refsynopsisdiv id="wrjpgcom-1-synp"><title>&synp-tt;</title>
<cmdsynopsis><command>&cmd;</command><arg choice="opt"><option>replace</option></arg>
<arg choice="opt"><option>comment <replaceable>text</replaceable></option></arg>
<arg choice="opt"><option>cfile <replaceable>name</replaceable></option></arg>
<arg choice="opt"><option role="nodash"><replaceable>filename</replaceable></option></arg>
</cmdsynopsis></refsynopsisdiv>
<refsect1 id="wrjpgcom-1-desc"><title>&desc-tt;</title>
<para><command>&cmd;</command> reads the named JPEG or JFIF file, or the standard
input if no file is named, and generates a new JPEG or JFIF file on the standard
output. A comment block is added to the file.</para>
<para>The JPEG standard allows "comment" (COM) blocks to occur within a JPEG
file. Although the standard does not actually define the intended function
of COM blocks, they are widely used to hold user-supplied text strings. This
enables you to add annotations, titles, index terms, and so on to your JPEG
files, and later retrieve the COM blocks as text. COM blocks do not interfere
with the image stored in the JPEG file. The maximum size of a COM block is
64K, but you can have many COM blocks in one JPEG file.</para>
<para><command>&cmd;</command> adds a COM block, containing text that you
provide, to a JPEG file. Ordinarily, the COM block is added after any existing
COM blocks, but you can delete the old COM blocks if you wish.</para>
</refsect1>
<refsect1 id="wrjpgcom-1-opts"><title>&opts-tt;</title>
<para>The following options are supported:</para>
<variablelist termlength="narrow">
<varlistentry><term><option>cfile <replaceable>name</replaceable></option></term>
<listitem><para>Read the text for a new COM block from the named file.</para>
</listitem></varlistentry>
<varlistentry><term><option>comment <replaceable>text</replaceable></option></term>
<listitem><para>Supply the text for a new COM block on the command line.</para>
</listitem></varlistentry>
<varlistentry><term><option>replace</option></term><listitem><para>Delete
any existing COM blocks from the file.</para>
</listitem></varlistentry>
</variablelist></refsect1>
<refsect1 id="wrjpgcom-1-oper"><title>&oper-tt;</title>
<para>The following operands are supported:</para>
<variablelist termlength="narrow">
<varlistentry><term><option role="nodash"><replaceable>filename</replaceable></option></term>
<listitem><para>The name of the JPEG file to which you want to add text comments.
</para>
</listitem></varlistentry>
</variablelist></refsect1>
<refsect1 id="wrjpgcom-1-exde"><title>&exde-tt;</title>
<para>To add only one line of comment text, use the <option>comment</option>
option to provide the text on the command line. Specify the comment text within
quotes, so that the text is treated as a single argument. Longer comments
can be read from a text file.</para>
<para>If you specify neither the <option>comment</option> nor the <option>
cfile</option> option, <command>&cmd;</command> reads the comment text from
standard input. In such cases, you must supply an input image filename. You
can enter multiple lines, up to 64KB. Type an end-of-file indicator, usually
Ctrl-D, to terminate the comment text entry.</para>
<para><command>&cmd;</command> does not add a COM block if the provided comment
string is empty. Therefore, you can use <option>replace</option> <option>
comment ""</option> to delete all COM blocks from a file.</para>
</refsect1>
<refsect1 id="wrjpgcom-1-exam"><title>&exam-tt;</title>
<example role="example">
<title>Adding a Short Comment to in.jpg to Produce out.jpg</title>
<para><screen>example% <userinput>&cmd; -c "View of my back yard" in.jpg > out.jpg
</userinput></screen></para>
</example>
<example role="example">
<title>Attaching a Long Comment Previously Stored in comment.txt</title>
<para><screen>example% <userinput>&cmd; in.jpg &lt; comment.txt > out.jpg
</userinput></screen></para>
<para>or</para>
<para><screen>example% <userinput>&cmd; -cfile comment.txt &lt; in.jpg > out.jpg
</userinput></screen></para>
<para>In this example, 1000 is a number that is larger than the number of
rows in the source file.</para>
</example>
</refsect1>
<refsect1 id="wrjpgcom-1-attr"><title>&attr-tt;</title>
<para>See <olink targetdocent="REFMAN5" localinfo="attributes-5"><citerefentry>
<refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>
for descriptions of the following attributes:</para>
<informaltable frame="all">
<tgroup cols="2" colsep="1" rowsep="1"><colspec colname="COLSPEC0" colwidth="1*">
<colspec colname="COLSPEC1" colwidth="1*">
<thead>
<row><entry align="center" valign="middle">ATTRIBUTE TYPE</entry><entry align="center"
valign="middle">ATTRIBUTE VALUE</entry></row>
</thead>
<tbody>
<row><entry><para>Availability</para></entry><entry><para>image/library/libjpeg</para></entry>
</row>
<row><entry colname="COLSPEC0"><para>Interface stability</para></entry><entry
colname="COLSPEC1"><para>Volatile</para></entry></row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="wrjpgcom-1-also"><title>&also-tt;</title>
<!--Reference to another man page-->
<!--Reference to a Help manual-->
<!--Reference to a book.-->
<para><citerefentry><refentrytitle>cjpeg</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>, <citerefentry><refentrytitle>djpeg</refentrytitle><manvolnum>
1</manvolnum></citerefentry>, <citerefentry><refentrytitle>jpegtran</refentrytitle>
<manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>rdjpgcom
</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
</refsect1>
<refsect1 id="wrjpgcom-1-note"><title>&note-tt;</title>
<para>This man page was originally written by the Independent JPEG Group.
Updated by Breda McColgan, Sun Microsystems Inc., 2004. </para>
</refsect1>
</refentry>
