SpecCommandLineDrawing

Outline

At the moment, Inkscape does not allow users to enter commands to Inkscape in a text-based format. This specification proposed to add that functionality, both at the command line and internally, possibly using a command-line box similar to Rhino's. In this way, a user will be able to directly enter precise instruction to Inkscape with minimal effort. For example, a command such as "circle r:50" could be entered and Inkscape will produce a circle of radius 50px, with all other attributes set to default values. In this way, technical drawing becomes easier, and the interface to Inkscape from external programs is vastly increased.

UI Changes

The only UI integration this proposal needs is a command line text box and an "Enter" button. Rhino has an advanced text entry system, using a long text box under the toolbars. Eagle, a piece of electrical CAD software, also has this system.

In Inkscape, I anticipate this being located under the context toolbar, but above the ruler and drawing area. Ideally, a button would be provided on the main toolbar to allow this command entry box to be toggled on or off to save space for those who don't need this feature.

Functionality Overview

This proposal would add following functionality:

• Creation of SVG items in Inkscape using just text input. Default options should be supplied so that properties not important to a user can be left out of the command, but still be taken care of.
• Manipulation of existing objects (scaling, duplication, deletion, etc)
• Allow the request of document information by external applications (eg. request document size or the properties of a given object etc)
• Increasing document manipulation by textual means (page size, exporting etc)
• Allow extensions and 3D party applications to have a simple way of editing Inkscape documents. All they would have to do is supply the command string, rather than as they do now, mess around with inkex helper modules, etc.

Basic Command Structure

This section is extremely preliminary and is mostly based on a Python mock-up rather than practical reasons. Hopefully, at some point a formal grammar will be established.

More than one command can be entered at once. These are separated by a semicolon. The last command should not need a semicolon.

cmd1; cmd2; cmd3

Each command is made up of a command header and a zero or more of parameters, separated by spaces:

cmd 1
cmd2 param2
cmd3 param31 param32

Each parameter is made up of one or more arguments, separated by colons:

cmd1 p1:arg1
cmd2 p21:arg211 p22:arg221:arg222

If an argument represents an item that needs more than one value (such as coordinates), these are separated by commas:

cmd1 p1:arg11,arg12 p2:arg2

For example, a circle with a radius of 50px and centre (500,400)px could be entered as:

circle r:50 c:500,400

It should also be possible to enter an expression. In this way:

circle r:25/2

should end up as a circle with a radius of 12.5px. This would dramatically reduce the time spend moving data between calculator apps and Inkscape in the case especially of technical drawing.

Different units should be easily used, so that one may easily use Inkscape software for engineering purposes.

circle r:10mm

should be automatically translated into px and render as a circle 10mm across.

Error Handling

The parser for these commands should catch errors wherever possible, and be able to give detailed reasons why it failed. This will help third parties develop an understanding of Inkscape's command structure (useful for encourage its use as a technical drawing aid) and allow easy debugging of external code.

For example the entry (say)

circle er:45

should fail with the reason that 'er' is not a known command header.

The same goes for incorrect numbers of arguments or sub-arguments, incorrect units (eg one should not be able to specify 'px' for a colour)

Documentation

The Inkscape command structure should have a detailed and thorough explanation on the Inkscape wiki or elsewhere. Ideally, one should be able to summon the help for a function using a command such as

help:circle

Which will link to the relevant online resource.

Suggestion to the original author: Given the command spec detailed in section "Basic Command Structure", the help command should look more like

help circle

Extensibility & Scriptability

The command structure should be easily extended to new functions and commands. I see two contenders for this system:

1. A global XML-based list of commands and available parameters can be provided to allow quick integration of new functions, as well as providing brief help if needed.

   • A draft command list is found here: Draft Command List

2. Commands are provided as stand-alone packages in a dedicated sub-directory. Each command file contains its own command dictionary, as well as the routines for generating the SVG elements.

   This means that the commands are extremely easy to add, as all that is required is to add a single file to the correct folder. This makes a future automated system for adding new commands very easy to implement, and reduces the possibility that such a system will damage the global file though mistakes made in writing updates.

   A short module containing the associations between what you write (eg. circle) and the module containing the functions for that command (eg. cl_circle.py) would seem to be the best way to allow the central script to keep track of what does and doesn't exist in the directory. I suggest that the functions are loaded dynamically so that only the needed functions are loaded. While this module could be included in the central script, breaking it out reduces the exposure of an inexperienced user to the main code, and reduces the chances of damage.

   • A sample module is provided here.
   • A sample association directory is provided here.

Here, accessibility is the name of the game, as we want new capabilities to the command line tool to be easy to produce and implement.

It should also be very easy to script for this command-line system. While I believe making the command line instuctions a scripting language in itself is entirely unnecessary, I think it would be good if Inkscape provided a way to either enter a multiline Python script (as Python is already included with Inkscape) or run one from a remote location which was made with another editor, or ideally both.

In this way, a user can quickly enter a command like:

for i in range(5):
   ink(circle r:50*i)

and get 5 circles of increasing radius. If Inkscape had a small window for entering scripts like this, saving them loading them, it would save time and make the interface even more useful. It would allow people with no knowledge of Python (but some programming know-how such as for, if statements, etc.) to be able to very easily script Inkscape.

This script window should incorporate the code entered there into a standard "container" script, which would deal with loading of the relevant modules (eg. the one containing the ink() command in this case). Thus the user is freed from having to know why the script works, and only needs to know how to use it.

External Links

• Rhino3D modeller with command line tool
• An Introduction to the Rhino Interface
• Eagle CAD System for electrical design. Includes a command line interface