<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [

<!--ArborText, Inc., 1988-1999, v.4002-->

<!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">

<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>

<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>