File: techdocs.xml

package info (click to toggle)
ddccontrol 0.6.0-4
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, sid
  • size: 1,144 kB
  • sloc: ansic: 7,068; xml: 1,862; makefile: 174; sh: 116; sed: 16
file content (359 lines) | stat: -rw-r--r-- 13,439 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
<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>