<appendix id="techdocs">
<title>Documents for developers</title>
<sect1 id="translators">
<title>Translation (I18N) guide</title>
<para>Author: Nicolas Boichat &lt;nicolas -at- boichat.ch&gt;</para>
<para>
Do you want to translate ddccontrol to your favorite language? Then, this guide is for you!
</para>
<para>
The distribution is split in two packages: <filename>ddccontrol</filename>
(the main program), and <filename>ddccontrol-db</filename> (monitor database).
</para>
<para>
Tools you need: <filename>subversion</filename>,
<filename>automake</filename>/<filename>autoconf</filename>,
<filename>gettext</filename>, <filename>make</filename>,
<filename>poedit</filename> (or another tool, or a simple text editor).
</para>
<para>
First, you need to check-out the sources from the Subversion repository
(see
<ulink url="http://sourceforge.net/svn/?group_id=117933">project Subversion page</ulink>,
Subversion Access section).
</para>
<para>Note you need to perform the following operations
in both the trunk/ddccontrol and trunk/ddccontrol-db directories (there are
strings to translate in the main program, and in the database).
</para>
<para>
Then run:
<screen format='linespecific'>
# ./autogen.sh
# ./configure (maybe you will need some devel package to make it working)
# cd po
# make update-po
</screen>
</para>
<para>
If the po file for your language doesn't exist, simply copy
<filename>ddccontrol.pot</filename> to <filename>LANG.po</filename> 
(for example, for French, it is <filename>fr.po</filename>) and update the
fields in it (like <sgmltag class="attribute">AUTHOR</sgmltag>,
<sgmltag class="attribute">CHARSET</sgmltag>, etc...)
</para>
<para>
Then open your <filename>.po</filename> file, and translate the strings! I
recommend that you use a tool like <ulink url="http://poedit.sf.net/">poedit</ulink>,
as it warns you visually when strings are wrong, and offers spellcheck.
But it's your choice .
</para>
<para>
When you are finished, it would be nice to test if it works by installing and
running the software, but it is not mandatory, particularly if you don't have
the needed hardware (i.e. a monitor supporting DDC/CI).  Then, sending the completed
<filename>.po</filename> files to
<ulink url="mailto:ddccontrol-devel@lists.sourceforge.net">ddccontrol-devel</ulink>.
</para>
<para>
It is a good idea that you subscribe to <filename>ddccontrol-devel</filename>,
particularly if you have problems to translate some technical strings.
This way it is not necessary to explain the same terms repeatedly to all translators .
</para>
<para>
Also, if you encounter mistakes in the original English strings, please report those
as well.
</para>
<para>
List of languages with active translators:
<itemizedlist mark='bullet'>
<listitem>
French: Nicolas Boichat
</listitem>
<listitem>
Russian: Sergei Epiphanov
</listitem>
</itemizedlist>
</para>
<para>
I hope my explanations were complete, otherwise do not hesitate to contact me
(cc-ing the devel list) if you have questions.
</para>
<para>
THANK YOU.
</para>
</sect1>
<sect1 id="dbstruct">
<title>Monitor database structure</title>
<para>The monitor database is written in XML, it can be found in the
<filename>db</filename> directory of <filename>ddccontrol-db</filename>
package.</para>
<para>This directory contains the following files:
<itemizedlist mark='bullet'>
<listitem>
<filename>
options.xml
</filename>
</listitem>
<listitem>
<filename>
monitor/<replaceable>%monitor_id%</replaceable>.xml
</filename>
</listitem>
</itemizedlist>
</para>
<sect2 id="optionsxml">
<title>Control list</title>
<subtitle>XML file: <filename>options.xml</filename></subtitle>
<para><sgmltag class="element">control</sgmltag> elements (e.g.
<sgmltag class="attvalue">brightness</sgmltag>) are contained in
<sgmltag class="element">group</sgmltag> elements (e.g.
<sgmltag class="attvalue">color settings</sgmltag>).
<sgmltag class="element">group</sgmltag> and 
<sgmltag class="element">subgroup</sgmltag> elements allow the GUI to separate
the controls in different branches on the tree.</para>

<para><sgmltag class="element">options</sgmltag> attributes:
<itemizedlist mark='bullet'>
<listitem>
<sgmltag class="attribute">date</sgmltag>: indicates the release date of the
current database (YYYYMMDD format).
</listitem>
<listitem>
<sgmltag class="attribute">dbversion</sgmltag>: indicates which version of
database format is used (must be set to 3).
</listitem>
</itemizedlist></para>

<para><sgmltag class="element">group</sgmltag> attributes:
<itemizedlist mark='bullet'>
<listitem>
<sgmltag class="attribute">name</sgmltag>: full English group name.
</listitem>
</itemizedlist></para>

<para><sgmltag class="element">subgroup</sgmltag> attributes:
<itemizedlist mark='bullet'>
<listitem>
<sgmltag class="attribute">name</sgmltag>: full English subgroup name.
</listitem>
<listitem>
<sgmltag class="attribute">pattern</sgmltag>: name of the fullscreen
pattern <filename>gddccontrol</filename> must display to help the
user to adjust subgroup's controls (optional). For possible values, see
<filename>ddccontrol/src/gddccontrol/fspatterns.c</filename>.
</listitem>
</itemizedlist></para>

<para><sgmltag class="element">control</sgmltag> attributes:
<itemizedlist mark='bullet'>
<listitem>
<sgmltag class="attribute">id</sgmltag>: abbreviated control name.
</listitem>
<listitem>
<sgmltag class="attribute">name</sgmltag>: full English control name.
</listitem>
<listitem>
<sgmltag class="attribute">address</sgmltag>: DDC/CI address (optional).
</listitem>
<listitem>
<sgmltag class="attribute">type</sgmltag>: one of these values:
<itemizedlist mark='opencircle'>
<listitem>
<sgmltag class="attvalue">value</sgmltag>: The control accepts values in a
continuous range (e.g. brightness).
</listitem>
<listitem>
<sgmltag class="attvalue">command</sgmltag>: An action occurs when the value is
set to something greater than <sgmltag class="attvalue">0</sgmltag>
(e.g. degauss). If you don't define any <sgmltag class="element">value</sgmltag>
element in a command control, the default value
<sgmltag class="attvalue">0x01</sgmltag> will be used.
</listitem>
<listitem>
<sgmltag class="attvalue">list</sgmltag>: The control accepts a list of values
(e.g. OSD language).
</listitem>
</itemizedlist>
</listitem>
<listitem>
<sgmltag class="attribute">refresh</sgmltag> (only for list and command controls):
Set whether other controls must be refreshed after changing list value or running
the command associated with the control (optional). Possible values:
<itemizedlist mark='opencircle'>
<listitem>
<sgmltag class="attvalue">none</sgmltag>: Do not refresh anything. (default)
</listitem>
<listitem>
<sgmltag class="attvalue">all</sgmltag>: Refresh all controls.
</listitem>
</itemizedlist>
</listitem>
</itemizedlist></para>
<para><sgmltag class="element">value</sgmltag> attributes:
<itemizedlist mark='bullet'>
<listitem>
<sgmltag class="attribute">id</sgmltag>: abbreviated value name.
</listitem>
<listitem>
<sgmltag class="attribute">name</sgmltag>: full English value name (it is not
needed if there is only one value for command controls).
</listitem>
<listitem>
<sgmltag class="attribute">value</sgmltag>: DDC/CI control value (optional).
</listitem>
</itemizedlist></para>

<para>File format:</para>
<screen format='linespecific'>
<![CDATA[<?xml version="1.0"?>
<options date="%date%" dbversion="3">
  <group name="%groupname%">
    <subgroup name="%subgroupname%" pattern="%patternname%">
      <control id="%control_id%" type="value" name="%control_name%" address="%hex_address%"/>
        <!-- Command using the default 0x01 address -->
      <control id="%control_id%" type="command" name="%control_name%" address="%hex_address%"/>
      <control id="%control_id%" type="command" name="%control_name%" address="%hex_address%">
        <value id="%value_id%" value="%hex_value%"/>
      </control>
      <control id="%control_id%" type="list" name="%control_name%" address="%hex_address%">
        <value id="%value_id%" name="%value_name%" value="%hex_value%"/>
        <value...>
      </control>
      <control ...>
    </subgroup>
  </group>
  <group ...>
</options>]]></screen>
</sect2>
<sect2 id="monitorxml">
<title>Monitor Profiles</title>
<subtitle>XML files:
<filename>monitor/<replaceable>%monitor_id%</replaceable>.xml</filename></subtitle>
<sect3>
	<title><sgmltag class="element">caps</sgmltag> element</title>
	<para>The caps attribute is optional. Its format is defined in ACCESS.bus specifications.</para>
	<para>To add controls to caps, use the <sgmltag class="attribute">add</sgmltag> attribute.
	To remove controls from caps, use the <sgmltag class="attribute">remove</sgmltag> attribute.</para>
	<para>Note remove is handled before add, so if you remove and add a same control, it will
	finally be in caps.</para>
</sect3>
<sect3>
	<title><sgmltag class="element">controls</sgmltag> element</title>
	<para>List of controls supported by a monitor (optional if you have an
	<sgmltag class="attribute">include</sgmltag> element).</para>
	<para><sgmltag class="element">control</sgmltag>
	<sgmltag class="attribute">id</sgmltag> attributes are defined in
	<filename>options.xml</filename>. If <sgmltag class="element">control</sgmltag>
	<sgmltag class="attribute">type</sgmltag> is
	<sgmltag class="attvalue">list</sgmltag> or
	<sgmltag class="attvalue">command</sgmltag> without default values, supported
	values must be defined.</para>
	<para><sgmltag class="attribute">address</sgmltag> attribute for 
	<sgmltag class="element">control</sgmltag> elements and
	<sgmltag class="attribute">value</sgmltag> attribute for 
	<sgmltag class="element">value</sgmltag> elements are optional if they are
	defined in the general options file.</para>
	
	<para>The <sgmltag class="attribute">init</sgmltag> attribute in
	<sgmltag class="element">monitor</sgmltag> element define the type of the
	initialization: DDC/CI standard (<sgmltag class="attvalue">standard</sgmltag>),
	or Samsung (<sgmltag class="attvalue">samsung</sgmltag>). This attribute is
	optional, as long as the monitor profile includes another profile which defines
	this attribute.</para>
	
	<para>
	You can set a <sgmltag class="attribute">delay</sgmltag> attribute in
	<sgmltag class="element">control</sgmltag> elements to set the time in
	milliseconds to wait after changing the value of this control.
	If you don't, a default value is used.
	</para>
</sect3>

<sect3>
	<title><sgmltag class="element">include</sgmltag> element</title>
	<para>Includes another monitor, manufacturer or standard profile, specified
	by the <sgmltag class="attribute">file</sgmltag> attribute.</para>
</sect3>

<note>Monitor profile are read sequentially. Control and init mode redifinitions
are ignored, so define specific controls and init mode before including a generic
profile. Caps are also treated sequentially, so if a control is not in CAPS at the
time it is defined, it won't be supported by ddccontrol.</note>

<para>File format:</para>
<screen format='linespecific'>
<![CDATA[<?xml version="1.0"?>
<monitor name="%full_monitor_name%" init="[standard|samsung]">
  <caps add="%add_caps%" remove="%remove_caps%"/>
  <controls>
    <!--- value -->
    <control id="%control_id%" address="%hex_address%" delay="%wait_time%"/>
    <!--- command using a default 0x01 value-->
    <control id="%control_id%" address="%hex_address%" delay="%wait_time%"/>
    <!--- command -->
    <control id="%control_id%" address="%hex_address%" delay="%wait_time%">
      <value id="activate" value="%hex_value%"/>
    </control>
    <!--- list -->
    <control id="%control_id%" address="%hex_address%" delay="%wait_time%">
      <value id="%value_id%" value="%hex_value%"/>
      <value...>
    </control>
    <control...>
  </controls>
  <!--- Including VESA generic profile is generally a good idea. -->
  <include file="VESA"/>
</monitor>
]]></screen>
<para>If a monitor supports exactly the same controls as another one, you can
define it as shown:</para>
<screen format='linespecific'>
<![CDATA[<?xml version="1.0"?>
<monitor name="%full_monitor_name%">
  <caps add="%add_caps%" remove="%remove_caps%"/>
  <include file="%include_monitor_id%"/>
</monitor>
]]></screen>
</sect2>
</sect1>

<sect1 id="profilestruct">
<title>Profile file structure</title>
<para>Profile files are used to save the value of some controls.</para>
<para><sgmltag class="element">profile</sgmltag> attributes:
	<itemizedlist mark='bullet'>
		<listitem>
			<sgmltag class="attribute">pnpid</sgmltag>: indicates the PNP id of the
			monitor that this profile applies to.
		</listitem>
		<listitem>
			<sgmltag class="attribute">name</sgmltag>: profile name.
		</listitem>
		<listitem>
			<sgmltag class="attribute">version</sgmltag>: indicates which version of
			profile format is used (must be set to 1).
		</listitem>
	</itemizedlist>
</para>
<para><sgmltag class="element">control</sgmltag> attributes:
	<itemizedlist mark='bullet'>
		<listitem>
			<sgmltag class="attribute">address</sgmltag>: DDC/CI address of the control.
		</listitem>
		<listitem>
			<sgmltag class="attribute">value</sgmltag>: DDC/CI control value.
		</listitem>
	</itemizedlist>
</para>
<para>File format:</para>
<screen format='linespecific'>
<![CDATA[<?xml version="1.0"?>
<profile pnpid="%pnp_id%" name="%profile_name%" version="1">
  <control address="%hex_address%" value="%control_value%"/>
  <control...>
</profile>
]]></screen>
</sect1>

</appendix>