Index: scripter-faq.html
===================================================================
RCS file: /cvs/Scribus/scribus/doc/en/scripter-faq.html,v
retrieving revision 1.3
diff -u -r1.3 scripter-faq.html
--- scripter-faq.html	29 Dec 2004 16:44:43 -0000	1.3
+++ scripter-faq.html	14 Feb 2005 10:06:34 -0000
@@ -21,11 +21,11 @@
     # -*- coding: ascii -*-
 </pre>
 </p>
-<p>Those lines MUST be the first two lines of your script. The coding MUST match the actual encoding of the file.</p>
+<p>Those lines <b>must</b> be the first two lines of your script. The coding <b>must</b> match the actual encoding of the file.</p>
 
 <p>To find out what the text encoding is in vim, type
 <code>    :set fileencoding?<enter></code>
-It will depend for other editors, it may match your locale.</p>
+How to find out the text encoding will vary for other editors, it may match your locale. The <code>file</code> command is <i>not</i> a reliable way to determine the text encoding of a file.</p>
 
 <p>You can convert files between encodings with the 'iconv' utility, but you will rarely need to given that Python can handle almost any text encoding if told what it is in the coding line.</p>
 
@@ -51,12 +51,13 @@
 
 <h3>I want to provide a more complex GUI than is provided by the dialogs built into the scripting interface. How can I do that?</h3>
 
-<p>wxPython, PyGtk or Tkinter are your best choices at present. There are security and technical issues that prevent the use of PyQt for normal scripts. It is not known when or if the PyQt issues will be resolved.</p>
+<p>For most scripting tasks, building a simple GUI in Tkinter is your best choices at present. If you're looking to extend the user interface or provide palettes the user can work with while they continue to work in Scribus, you'll need to look into writing an 'extension script' with PyQt.
 
-<p>There are experimental efforts at building a minimal Qt wrapper interface for scribus so you can load and run user interfaces created with Qt designer. Any assistance in this effort would be very welcome - please enquire on the Scribus IRC channel, #scribus on irc.freenode.net, or on the mailing list.</p>
+<p>In most cases it's recommended to just choose Tkinter. It's the only GUI toolkit that works reliably in normal Scribus scripts due to the way they're executed in sub-interpreters. It's also almost universally packaged in Linux distros, though not all install it by default, and it's highly portable. Users may not particularly love the appearance of Tkinter, but it works well.</p>
 
-<h3>So ... which GUI should I choose?</h3>
-<p>PyGtk is likely to be fairly widely packaged in Linux distros and is quite a nice interface, but may not be availible on other platforms. Tkinter is supported on all major platforms, but can be rather clunky to use and has a very old-school, motif look and feel. wxPython simply wraps Gtk under Linux, but will generally require additional install steps by the user. Tkinter is also the best tested with Scribus, so it is probably the safest choice at present.</p>
+<p>If you're looking to write more advanced GUIs, the best choice is currently PyQt. You can write your own custom dialogs and palettes using PyQt, giving you the ability to extend the Scribus interface to a limited extent. PyQt will not work reliably from a normal script, but works fine from scripts that are run using the &quot;Load Extension Script...&quot; menu item. Please see the advanced section of the scripter manual for more details on this.</p>
+
+<p>Issues with event loop integration and initialization in sub-interpreters mean that PyGtk and wxPython are not currently recommended and probably won't work properly. Given that Tkinter works well for normal scripts, and PyQt for more advanced tasks, this isn't seen as a major problem.</p>
 
 <h3>Should I use 'from scribus import *' or 'import scribus'?</h3>
 <p>In general, 'import scribus' is preferred. 'from ... import' can get confusing in import loops, when reloading modules, when importing packages, and in some other circumstances. More info <a href="http://effbot.org/zone/import-confusion.htm" title="Extern link">http://effbot.org/zone/import-confusion.htm</a>.</p>
@@ -74,36 +75,43 @@
 <p>Yes, there are a few differences you should be aware of:</p>
 
 <ul>
-	<li>Python scripts running in Scribus may not create threads. Qt, the toolkit       Scribus is built with, provides its own threading framework that doesn't play well with the Python threading system. A interface to QThread may be provided if sufficient need for it can be shown, and if it can be made to work.</li>
-
-	<li>PyQt does not currently work correctly from Python scripts run from Scribus. Please enquire on the mailing list if you think you may be able to assist in solving this. Experience with the Python/C API, sub-interpreters, and PyQt would probably be required.</li>
+	<li>Python scripts running in Scribus may not create threads. Qt, the toolkit Scribus is built with, provides its own threading framework that doesn't play well with the Python threading system. A interface to QThread may be provided if sufficient need for it can be shown, and if it can be made to work.</li>
 
-	<li>The Scribus python plug-in changes the Python default string encoding       (sysdefaultencoding) to utf-8. Python defaults to ASCII. Because utf-8 is a (large) superset of ASCII, this should not affect scripts that only use ASCII-encoded strings. The Scribus functions have been tested to work correctly with this for unicode text, so there should not be any issues there either.</li>
+	<li>PyQt does not currently work correctly from Python scripts run from normal Scribus scripts, though it can now be used from the 'extension script' mode. Please enquire on the mailing list if you think you may be able to assist in solving this. Experience with the Python/C API, sub-interpreters, and PyQt would probably be required.</li>
 
-	<li>Nonetheless, it is possible that third party C extension modules may have problems with this, if the author failed to consider the encoding of incoming text. Any such problems are almost always bugs that should be reported to the author of the module, and should be few and far between. If you encounter such an issue, please enquire on the mailing list or on IRC.</li>
+	<li>The Scribus python plug-in changes the Python default string encoding (sysdefaultencoding) to utf-8. Python defaults to ASCII. Because utf-8 is a (large) superset of ASCII, this should not affect scripts that only use ASCII-encoded strings. The Scribus functions have been tested to work correctly with this for unicode text, so there should not be any issues there either.<br>
+	Nonetheless, it is possible that third party C extension modules may have problems with this, if the author failed to consider the encoding of incoming text. Any such problems are almost always bugs that should be reported to the author of the module, and should be few and far between. If you encounter such an issue, please enquire on the mailing list or on IRC.</li>
 
-	<li>Python runs embedded inside Scribus. It is possible that loading certain C extension modules that perform complex initialization tricks may disrupt Scribus or the Python interpreter. If you encounter such a module, please report it on the mailing list or drop in on IRC.</li>
+	<li>Python runs embedded inside Scribus. It is possible that loading certain C extension modules that perform complex initialization tricks may disrupt Scribus or the Python interpreter. If you encounter such a module, please report it on the mailing list or drop in on IRC. Anything that wants to run its own event loop is likely to be problematic, and interfaces to GUI toolkits also seem to be troublesome. Anything that spawns threads is also likely to cause issues.</li>
 </ul>
 
 <h3>Can I use the rest of the Python standard library or add-in modules?</h3>
-<p>Yes, and yes. Scribus imposes no restrictions on access to the rest of Python, and that's one of the things that makes the scripter so powerful. It is possible that some Python functions such as threading may be affected by the way the interpreter has been embedded, but most should be usable as normal.</p>
+<p>Yes, and yes. Scribus imposes no restrictions on access to the rest of Python (except for the technical limitations explained above), and that's one of the things that makes the scripter so powerful. It is possible that some Python functions such as threading may be affected by the way the interpreter has been embedded, but most should be usable as normal.</p>
 
 <h3>I'd like to extend Scribus using Python, not just automate things with it...</h3>
-<p>Currently, that's not really possible. There is work on making it possible to extend Scribus with Python to some extent, especially the GUI. The Scribus core is not well suited to extension from Python at present. More advanced or tightly integrated extensions are probably better written as C++ plug-ins.</p>
+<p>Currently, that's not really possible. There is work on making it possible to extend Scribus with Python to some extent, especially the GUI. It's now possible to use PyQt to write your own palettes, but you won't be able to use custom Scribus widgets or get into the innards of the application. The Scribus core is unfortunately not well suited to extension from Python. More advanced or tightly integrated extensions are probably better written as C++ plug-ins.</p>
 
 <h3>What about security? Can I trust scripts not to destroy my data or compromise my computer?</h3>
-<p>No. Do not run a script if it is not from a trusted source, and preferably not unless you have read it. The downside of the power of the Python scripting interface is that it imposes almost no security restrictions. Anything you can do from the shell without a password, a script can do too.</p>
+<p><b>No. Do not run a script if it is not from a trusted source, and preferably not unless you have read it.</b> The downside of the power of the Python scripting interface is that it imposes almost no security restrictions. Anything you can do from the shell without a password, a script can do too.</p>
+
+<p>If Python ever gets support for a restricted execution environment like versions &lt; 2.2 had, support for it may be added, but currently there are essentially no restrictions. It would be interesting to investigate a simple automation-only macro language for embedding in Scribus, but currently there aren't the resources to do this.</p>
+
+<h3>So ... can I embed scripts in documents or templates?</h3>
+<p>No, see above. We can't provide a restricted execution environment, so it's not safe to let scripts travel with documents. Otherwise a malicious script could use a document as a vector to infect other systems. Remember Word macro viruses? Yeah. We do too.</p>
+
+<h3>What about a startup script or event-triggered scripts?</h3>
+
+<p>Startup scripts are supported, and scripts that run when certain events happen may be supported in future. If a script is in a position to "infect" a startup script or your application, it's also able to modify your .bashrc or your X startup script. In other words, if you choose to run untrusted code on your machine, it's too late - having it insert its self into a Scribus startup script would be the least of your problems. This is not unique to Scribus, and is true of bash scripts, normal programs, and most plug-ins as well. <b>Remember, do not run scripts that are not from trusted sources, scripts are programs like any other you might run on your computer.</b>.
 
-<p>If Python ever gets support for a restricted execution environment like versions &lt; 2.2 had, support for it may be added, but currently there are essentially no restrictions.</p>
+<p>It's as safe for Scribus to load a script on startup as it is for the shell (e.g. <code>bash</code>), or your graphical login system. Scribus cannot protect you if you choose to run untrusted programs on your system. What it <i>can</i> prevent is providing any vector for untrusted code to spread. That is why Scribus supports startup scripts (though they are not run by default) and why scripts will not be permitted to be embedded in or run from documents.</p>
 
-<h3>So ... can I get a script to run at start-up / when I open a document / when I perform some other action?</h3>
-<p>No, see above. We can't provide a restricted execution environment, so it's not safe to let scripts run themselves. Otherwise a malicious script could make sure it gets run automatically in future or even attack documents. Remember Word macro viruses? Yeah. We do too.</p>
+<p><b>Do not run a program, script, or plug-in, of any sort, from any source, unless you have verified that the program is not malicious.</b> This is an important rule of basic computer security and applies to any program and operating system.</p>
 
-<h3>What about C++ plugins? Are they secure?</h3>
+<h3>What about C++ plugins for Scribus? Are they secure?</h3>
 <p>Not at all. A Scribus C++ plug-in can do almost anything any other program on your computer can do, so do not download and run one you do not absolutely trust the author of. This is true of plug-ins for most programs, as it is very difficult to restrict what a plug-in written in C/C++ can do.</p>
 
-<h3>I can't find a way to do <i>blah</i> from Python, but the main Scribus application supports it. What do I do?</h3>
-<p>The scripting interface requires each function to be written by hand - no automatic code generation / wrapping mechanism is used. This is partly because there isn't currently any tidy and stable underlying public API to wrap.</p>
+<h3>I can't find a way to do <i>something</i> from Python, but the main Scribus application supports it. What do I do?</h3>
+<p>The scripting interface currently requires each function to be written by hand - no automatic code generation / wrapping mechanism is used. This is partly because there isn't currently any tidy and stable underlying public API to wrap.</p>
 
 <p>In general, if a function is missing it is because nobody has found the time or need to write it yet.  Sometimes the function is more complicated than it seems, and may be quite a lot of work to wrap. Sometimes it's five minutes work. Ask politely on IRC or the mailing list, and if someone has the time and inclination they may write one for you.</p>
 

Index: codingstandards.html
===================================================================
RCS file: /cvs/Scribus/scribus/doc/en/codingstandards.html,v
retrieving revision 1.4
diff -u -r1.4 codingstandards.html
--- codingstandards.html	20 Nov 2004 16:53:40 -0000	1.4
+++ codingstandards.html	14 Feb 2005 10:05:54 -0000
@@ -42,9 +42,9 @@
 void foo::bar(f *b)
 {
 	int j;
-	string g = b->passed_in;
+	string g = b->passed_in;
 	double fg, m, c;
-	which_string(g, &j);
+	which_string(g, &j);
 	if (j == true)
 		return;
 	// rest of the code
@@ -193,8 +193,8 @@
 <p>If braces are not required, don't use them. For example, braces wouldn't be needed here</p>
 <blockquote><table width="100%" border="1" bgcolor="#eeeeee"><tr><td border="0"><small>
 <pre>
-for (int j = 0; j < 10; ++j)
-	cout << j << "\n"?;
+for (int j = 0; j &lt; 10; ++j)
+	cout &lt;&lt; j &lt;&lt; &quot;\n&quot;?;
 </pre>
 </small></td></tr></table></blockquote>
 <h4>Pre or post increments</h4>
@@ -204,8 +204,8 @@
 <pre>
 if (b == true)
 {
-	m->wibble(c);
-	m->wobble(c++);
+	m-&gt;wibble(c);
+	m-&gt;wobble(c++);
 }
 </pre>
 </small></td></tr></table></blockquote>
@@ -247,7 +247,7 @@
 <p>All calls to <code>new</code> should be trapped. This is not currently implemented in the 1.1.x releases, but will be implemented in the 1.2. The preferred method would be:</p>
 <blockquote><table width="100%" border="1" bgcolor="#eeeeee"><tr><td border="0"><small>
 <pre>
-#include <new>
+#include &lt;new&gt;
 
 try
 {
@@ -256,7 +256,7 @@
 
 catch(bad_exception)
 {
-  cout << "memory allocation to m failed - <method name>" << endl;
+  cout &lt;&lt; "memory allocation to m failed - &lt;method name&lt;" &lt;&lt; endl;
   exit(EXIT_FAILURE);
 }
 </pre>
@@ -269,7 +269,7 @@
 <h4>Submitting of patches</h4>
 
 <p>Code patches should be sent to Franz and Paul. Documentation patches should be sent to Peter and Craig. This is subject to change. Scripting matters should be addressed to Petr.</p>
-<p>Patches should be in plain text. diff -u old_file.cpp new_file.cpp >difference.diff is the best way of sending them. Please do not send patches to the main list.</p>
+<p>Patches should be in plain text. <code>diff -u old_file.cpp new_file.cpp &gt;difference.diff</code> is the best way of sending them. Please do not send patches to the main list.</p>
 <p>Please ensure that when you have changed something you put a comment immediately before the change. Ensure you put a date and who made the change and what the change is for. Make sure that the comments include the original line of code. Over time, these will be weeded out, but it useful to see what has been altered.</p>
 <p>Send a single diff for each file altered. It makes committing the changes far more simple for us!</p>