Difference between revisions of "INX extension descriptor format"

From Inkscape Wiki
Jump to navigation Jump to search
(start about INX file)
(change outdated links to Gitlab)
 
(40 intermediate revisions by 17 users not shown)
Line 1: Line 1:
How an extension must work and how to write an INX file.
+
== Introduction ==
  
''It's only an working draft!''
+
In order for Inkscape to make use of an external script or program, you must describe that script to inkscape using an INX file. See the inkscape share directory for examples. The INX file allows the author to:
 +
* label strings for translation
 +
* define parameters
 +
* chain extensions
 +
* etc
 +
Be sure to read through the INX files that come with Inkscape. Nothing beats a working example.
  
== About the Inkscape Extension Interface ==
+
== Translation of extensions ==
  
The inkscape call a program with some arguments and as the last argumet it tells to the extension program where is the temporay SVG file to do the work. The temporay SVG file represents the actual state of the working SVG.
+
Extension dialog windows, described in INX files, can be prepared for translation or localisation by adding an <code>_</code> (underscore) to the XML tags or attributes. Only add underscores when text need to be translated (not numeric values, for example!).
  
After the extension program work it writes the modified SVG to the default output, the Inkscape get this and update the SVG for the user.
+
Example:
 +
<pre>
 +
<_name>Some translatable extension name</_name>
 +
</pre>
  
''An Inkscape Developer can say it better...''
+
Or:
 +
<pre>
 +
<param name="..." type="..." _gui-text="Some translatable label text">
 +
</pre>
  
 +
When extensions are included in the [https://gitlab.com/inkscape/extensions Inkscape Extensions Repository], various scripts will scan each INX file for translatable text and prepare [https://gitlab.com/inkscape/inkscape/-/tree/master/po translation files] for others to translate.
  
== How an Extension Must Work ==
+
See also: [http://gould.cx/ted/blog/Translating_Custom_XML Ted's blog].
  
* Recive the inkscape arguments.
 
* Clear temp files if it creates one.
 
* Write full changed SVG to the default output.
 
* Don't break an xml:space="preserve" area.
 
* Send error text to the error output and help the user.
 
  
''An Inkscape Developer can say more?''
+
== Attributes description ==
  
 +
{| class="wikitable"
 +
|-
 +
! Attribute name
 +
! Allowed values
 +
! Comment
 +
|-
 +
| <code>implements-custom-gui</code> (''new in 1.0'')
 +
| <code>"true"</code> <nowiki>|</nowiki> <code>"false"</code> (default)
 +
| If set to <code>true</code> '''requires''' effect extension to implement custom GUI. Implementation detail: "extension is working" window is not show for this kind of extensions.
 +
|-
 +
| <code>needs-document</code>
 +
| <code>"true"</code> <nowiki>|</nowiki> <code>"false"</code> (default)
 +
| '''''(please fill in!)'''''
 +
|-
 +
| <code>needs-live-preview</code>
 +
| <code>"true"</code> <nowiki>|</nowiki> <code>"false"</code> (default)
 +
| '''''(please fill in!)'''''
 +
|-
 +
|}
  
== How to Write an INX File ==
+
== Example ==
 +
More example INX files are available in the Inkscape distribution, which takes its files from the [https://gitlab.com/inkscape/extensions Inkscape Extensions Repository].
  
'''Example:'''
+
<small><pre>
  <inkscape-extension>
+
<?xml version="1.0" encoding="UTF-8"?>
    <_name>{Friendly Extension Name}</_name>
+
<inkscape-extension xmlns="http://www.inkscape.org/namespace/inkscape/extension">
    <id>{org.domain.sub-domain.extension-name}</id>
+
  <_name>{Friendly Extension Name}</_name>
      <dependency type="executable"
+
  <id>{org.domain.sub-domain.extension-name}</id>
                  location="[extensions|{location}]">program.ext</dependency>
+
  <dependency type="executable" location="[extensions|path|plugins|{location}]">program.ext</dependency>
       <param name="{argumentName}" type="[int|float|string]"
+
  <param name="tab" type="notebook"> 
            min="{number}" max="{number}"
+
    <page name="controls" _gui-text="Controls">
            _gui-text="{Friendly Argument Name}">{default value}</param>
+
       <param name="{argumentName}" type="[int|float|string|boolean|description]" min="{number}" max="{number}"
     <effect>
+
        _gui-text="{Friendly Argument Name}">{default value}</param>
      <object-type>[all|{element type}]</object-type>
+
     </page>
        <effects-menu>
+
    <page name="help" _gui-text="Help">
          <submenu _name="{Extension Group Name}"/>
+
      <param name="help_text" type="description">{Friendly Extension Help}</param>
        </effects-menu>
+
    </page>
    </effect>
+
  </param>
    <script>
+
  <effect>
      <command reldir="extensions"
+
    <object-type>[all|{element type}]</object-type>
              interpreter="[python|perl|bash|{some other}]">program.ext</command>
+
      <effects-menu>
    </script>
+
        <submenu _name="{Extension Group Name}"/>
  </inkscape-extension>
+
      </effects-menu>
 +
  </effect>
 +
  <script>
 +
    <command reldir="extensions" interpreter="[python|perl|ruby|bash|{some other}]">program.ext</command>
 +
  </script>
 +
</inkscape-extension>
 +
</pre></small>
  
 +
For a full list of currently supported interpreters, please see [[Extension Interpreters]].
 +
 +
== DTD XML schema==
 +
The following XML schema may not fully describe the current ING file structure. The actual XML schema used is described in the [[INX extension descriptor format#RELAX NG XML schema|next paragraph]].
 +
<small><pre>
 +
<!ELEMENT inkscape-extension (name, id, dependency*, param*,(input|output|effect),(script|plugin))>
 +
<!ELEMENT input (extension, mimetype, filetype, filetypetooltip, output_extension?)>
 +
<!ELEMENT output (extension, mimetype, filetype, filetypetooltip, dataloss?)>
 +
<!ELEMENT effect (object-type|submenu?)>
 +
<!ELEMENT script (command, helper_extension*, check*)>
 +
<!ELEMENT plugin (name)>
 +
<!ELEMENT name (#PCDATA)>
 +
<!ELEMENT id (#PCDATA)>
 +
<!ELEMENT item (#PCDATA)>
 +
<!ELEMENT option (#PCDATA)>
 +
<!ELEMENT dependency (#PCDATA)>
 +
<!ELEMENT param (#PCDATA|page|item|option)*>
 +
<!ELEMENT page (#PCDATA, param*)>
 +
<!ELEMENT extension (#PCDATA)>
 +
<!ELEMENT mimetype (#PCDATA)>
 +
<!ELEMENT filetype (#PCDATA)>
 +
<!ELEMENT filetooltip (#PCDATA)>
 +
<!ELEMENT object-type (#PCDATA)>
 +
<!ELEMENT command (#PCDATA)>
 +
<!ELEMENT check (#PCDATA)>
 +
<!ELEMENT dataloss (#PCDATA)>
 +
<!ELEMENT helper_extension (#PCDATA)>
 +
<!ELEMENT output_extension (#PCDATA)>
 +
 +
<!ATTLIST check reldir (absolute|path|extensions|plugins) #REQUIRED>
 +
<!ATTLIST command reldir (absolute|path|extensions|plugins) #REQUIRED>
 +
<!ATTLIST command interpreter CDATA #REQUIRED>
 +
<!ATTLIST dependency type (executable|extension) #REQUIRED>
 +
<!ATTLIST dependency location (absolute|path|extensions|plugins) #IMPLIED>
 +
<!ATTLIST dependency description CDATA #IMPLIED>
 +
<!ATTLIST effect needs-live-preview (true|false) #REQUIRED>
 +
<!ATTLIST effect implements-custom-gui (true|false) #IMPLIED>
 +
<!ATTLIST page name CDATA #REQUIRED>
 +
<!ATTLIST page gui-text CDATA #IMPLIED>
 +
<!ATTLIST param name CDATA #REQUIRED>
 +
<!ATTLIST param type (int|float|string|boolean|enum|notebook|description|optiongroup|color) #REQUIRED>
 +
<!ATTLIST param min CDATA #IMPLIED>
 +
<!ATTLIST param max CDATA #IMPLIED>
 +
<!ATTLIST param max_length CDATA #IMPLIED>
 +
<!ATTLIST param precision CDATA #IMPLIED>
 +
<!ATTLIST param gui-text CDATA #IMPLIED>
 +
<!ATTLIST param gui-tip CDATA #IMPLIED>
 +
<!ATTLIST param gui-description CDATA #IMPLIED>
 +
<!ATTLIST param scope CDATA #IMPLIED>
 +
<!ATTLIST param gui-hidden CDATA #IMPLIED>
 +
<!ATTLIST param appearance (minimal|) "">
 +
<!ATTLIST submenu name CDATA #REQUIRED>
 +
</pre></small>
 +
 +
== RELAX NG XML schema ==
 +
The XML schema for INX files is available in the [https://gitlab.com/inkscape/extensions/-/blob/master/inkscape.extension.rng Inkscape extensions Git repository]. This is a [http://www.relaxng.org/ RELAX NG schema].
 +
 +
== See Also ==
 +
*[[INX Parameters]]
 +
*[[ScriptingHOWTO]]
  
 
[[Category:Developer Documentation]]
 
[[Category:Developer Documentation]]
 
[[Category:Help Wanted]]
 
[[Category:Help Wanted]]
 +
[[Category:Extensions]]

Latest revision as of 08:55, 2 May 2020

Introduction

In order for Inkscape to make use of an external script or program, you must describe that script to inkscape using an INX file. See the inkscape share directory for examples. The INX file allows the author to:

  • label strings for translation
  • define parameters
  • chain extensions
  • etc

Be sure to read through the INX files that come with Inkscape. Nothing beats a working example.

Translation of extensions

Extension dialog windows, described in INX files, can be prepared for translation or localisation by adding an _ (underscore) to the XML tags or attributes. Only add underscores when text need to be translated (not numeric values, for example!).

Example:

<_name>Some translatable extension name</_name>

Or:

<param name="..." type="..." _gui-text="Some translatable label text">

When extensions are included in the Inkscape Extensions Repository, various scripts will scan each INX file for translatable text and prepare translation files for others to translate.

See also: Ted's blog.


Attributes description

Attribute name Allowed values Comment
implements-custom-gui (new in 1.0) "true" | "false" (default) If set to true requires effect extension to implement custom GUI. Implementation detail: "extension is working" window is not show for this kind of extensions.
needs-document "true" | "false" (default) (please fill in!)
needs-live-preview "true" | "false" (default) (please fill in!)

Example

More example INX files are available in the Inkscape distribution, which takes its files from the Inkscape Extensions Repository.

<?xml version="1.0" encoding="UTF-8"?>
<inkscape-extension xmlns="http://www.inkscape.org/namespace/inkscape/extension">
  <_name>{Friendly Extension Name}</_name>
  <id>{org.domain.sub-domain.extension-name}</id>
  <dependency type="executable" location="[extensions|path|plugins|{location}]">program.ext</dependency>
  <param name="tab" type="notebook">  
    <page name="controls" _gui-text="Controls">
      <param name="{argumentName}" type="[int|float|string|boolean|description]" min="{number}" max="{number}"
        _gui-text="{Friendly Argument Name}">{default value}</param>
    </page>
    <page name="help" _gui-text="Help">
      <param name="help_text" type="description">{Friendly Extension Help}</param>
    </page>
  </param>
  <effect>
    <object-type>[all|{element type}]</object-type>
      <effects-menu>
        <submenu _name="{Extension Group Name}"/>
      </effects-menu>
  </effect>
  <script>
    <command reldir="extensions" interpreter="[python|perl|ruby|bash|{some other}]">program.ext</command>
  </script>
</inkscape-extension>

For a full list of currently supported interpreters, please see Extension Interpreters.

DTD XML schema

The following XML schema may not fully describe the current ING file structure. The actual XML schema used is described in the next paragraph.

 <!ELEMENT inkscape-extension (name, id, dependency*, param*,(input|output|effect),(script|plugin))>
 <!ELEMENT input (extension, mimetype, filetype, filetypetooltip, output_extension?)>
 <!ELEMENT output (extension, mimetype, filetype, filetypetooltip, dataloss?)>
 <!ELEMENT effect (object-type|submenu?)>
 <!ELEMENT script (command, helper_extension*, check*)>
 <!ELEMENT plugin (name)>
 <!ELEMENT name (#PCDATA)>
 <!ELEMENT id (#PCDATA)>
 <!ELEMENT item (#PCDATA)>
 <!ELEMENT option (#PCDATA)>
 <!ELEMENT dependency (#PCDATA)>
 <!ELEMENT param (#PCDATA|page|item|option)*>
 <!ELEMENT page (#PCDATA, param*)>
 <!ELEMENT extension (#PCDATA)>
 <!ELEMENT mimetype (#PCDATA)>
 <!ELEMENT filetype (#PCDATA)>
 <!ELEMENT filetooltip (#PCDATA)>
 <!ELEMENT object-type (#PCDATA)>
 <!ELEMENT command (#PCDATA)>
 <!ELEMENT check (#PCDATA)>
 <!ELEMENT dataloss (#PCDATA)>
 <!ELEMENT helper_extension (#PCDATA)>
 <!ELEMENT output_extension (#PCDATA)>
 
 <!ATTLIST check reldir (absolute|path|extensions|plugins) #REQUIRED>
 <!ATTLIST command reldir (absolute|path|extensions|plugins) #REQUIRED>
 <!ATTLIST command interpreter CDATA #REQUIRED>
 <!ATTLIST dependency type (executable|extension) #REQUIRED>
 <!ATTLIST dependency location (absolute|path|extensions|plugins) #IMPLIED>
 <!ATTLIST dependency description CDATA #IMPLIED>
 <!ATTLIST effect needs-live-preview (true|false) #REQUIRED>
 <!ATTLIST effect implements-custom-gui (true|false) #IMPLIED>
 <!ATTLIST page name CDATA #REQUIRED>
 <!ATTLIST page gui-text CDATA #IMPLIED>
 <!ATTLIST param name CDATA #REQUIRED>
 <!ATTLIST param type (int|float|string|boolean|enum|notebook|description|optiongroup|color) #REQUIRED>
 <!ATTLIST param min CDATA #IMPLIED>
 <!ATTLIST param max CDATA #IMPLIED>
 <!ATTLIST param max_length CDATA #IMPLIED>
 <!ATTLIST param precision CDATA #IMPLIED>
 <!ATTLIST param gui-text CDATA #IMPLIED>
 <!ATTLIST param gui-tip CDATA #IMPLIED>
 <!ATTLIST param gui-description CDATA #IMPLIED>
 <!ATTLIST param scope CDATA #IMPLIED>
 <!ATTLIST param gui-hidden CDATA #IMPLIED>
 <!ATTLIST param appearance (minimal|) "">
 <!ATTLIST submenu name CDATA #REQUIRED>

RELAX NG XML schema

The XML schema for INX files is available in the Inkscape extensions Git repository. This is a RELAX NG schema.

See Also