360 lines
13 KiB
XML
360 lines
13 KiB
XML
<appendix id="techdocs">
|
|
<title>Documents for developers</title>
|
|
<sect1 id="translators">
|
|
<title>Translation (I18N) guide</title>
|
|
<para>Author: Nicolas Boichat <nicolas -at- boichat.ch></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>
|