Avoid bad style - thanks to Mark

2025-02-02 10:40:38 +01:00 · 2013-06-21 16:19:49 +00:00 · 2013-06-21 16:19:49 +00:00 · 4683c45e2b
commit 4683c45e2b
parent bb2700ea27
1 changed files with 92 additions and 91 deletions
--- a/doc/README.plugins.html
+++ b/doc/README.plugins.html
@ -1,11 +1,11 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <HTML>
 <HEAD>
-	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
+	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
 	<TITLE></TITLE>
 	<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.4.1  (Unix)">
 	<META NAME="CREATED" CONTENT="20130417;16154700">
-	<META NAME="CHANGED" CONTENT="20130418;17490000">
+	<META NAME="CHANGED" CONTENT="20130621;20102600">
 	<STYLE TYPE="text/css">
 	<!--
 		@page { margin: 0.79in }
@ -19,24 +19,24 @@
 </P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Since version 3, Firebird
 supports plugins architecture. This means that for a number of
-predefined points in Firebird code, user can write his own fragment of
+predefined points in Firebird code, user can write his own fragment
-code which will be executed when needed. Plugin is not necessarily
+of code which will be executed when needed. Plugin is not necessarily
-always written be user - Firebird already has a number of plugins
+always written by user - Firebird already has a number of plugins
-which are its native part. Moreover, as you will see later, some
+which are its native part. Moreover, as you will see later, some core
-core parts of Firebird are implemented as plugins. </FONT>
+parts of Firebird are implemented as plugins. </FONT>
 </P>
 <P STYLE="margin-bottom: 0in"><BR>
 </P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>First of all a few words
-about the term “plugin”. Unfortunately, it's often used to define
+about the term &ldquo;plugin&rdquo;. Unfortunately, it's often used
-related but different things. Plugin is used to name:</FONT></P>
+to define related but different things. Plugin is used to name:</FONT></P>
 <UL>
 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>dynamic library,
 	containing code to be loaded as plugin (often called plugin module)
 	and stored in $FIREBIRD/plugins directory;</FONT></P>
 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>code implementing
-	plugin – slightly different from the library cause single dynamic
+	plugin &ndash; slightly different from the library cause single
-	library may contain code for more than one plugin;</FONT></P>
+	dynamic library may contain code for more than one plugin;</FONT></P>
 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>plugin's factory - an
 	object created by that code (pure virtual C++ class), creating
 	plugin instances on Firebird request;</FONT></P>
@ -44,20 +44,21 @@ related but different things. Plugin is used to name:</FONT></P>
 	created by factory.</FONT></P>
 </UL>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>In most cases it's clear
-from context what “plugin” do we talk about. If not it will be
+from context what &ldquo;plugin&rdquo; do we talk about. If not it
-clarified explicitly.</FONT></P>
+will be clarified explicitly.</FONT></P>
 <P STYLE="margin-bottom: 0in"><BR>
 </P>
-<P STYLE="margin-bottom: 0in"><FONT SIZE=4>One should not expect that
+<P STYLE="margin-bottom: 0in"><FONT SIZE=4>Firebird plugin
-Firebird plugin architecture will make it possible to create any kind
+architecture supports creation of any plugin type for any purpose &ndash;
-of plugin you want. To be able to have plugin (for example)
+but first of all this requires changes in Firebird code. Plugin can't
-encrypting database on the disk, Firebird code should be prepared for
+be added at any desired point &ldquo;magically&rdquo;. To be able to
-it – must have a point from which plugin is called. I.e. each
+have plugin (for example) encrypting database on the disk, Firebird
-version has a fixed set of plugins which are supported. To add one
+code should be prepared for it &ndash; must have a point from which
-more type, first of all Firebird code should be modified. What DOES
+plugin is called. I.e. each version has a fixed set of plugins which
-our plugin architecture – it helps to make both adding new types of
+are supported. To add one more type, first of all Firebird code
-plugins and writing plugin code simple and as universal between
+should be modified. What DOES our plugin architecture &ndash; it
-plugins as possible.</FONT></P>
+helps to make both adding new types of plugins and writing plugin
 code simple and as universal between plugins as possible.</FONT></P>
 <P STYLE="margin-bottom: 0in"><BR>
 </P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Firebird 3 has a following
@ -79,9 +80,9 @@ set of plugin types:</FONT></P>
 	plugin KeyHolder, which is used to help maintaining secret key(s)
 	for DbCrypt;</FONT></P>
 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>and probably the most
-	important kind – Provider. Firebird 3 supports providers as a kind
+	important kind &ndash; Provider. Firebird 3 supports providers as a
-	of plugins, which has nothing outstanding compared with others. See
+	kind of plugins, which has nothing outstanding compared with others.
-	README.Providers for more information about providers. </FONT>
+	See README.Providers for more information about providers. </FONT>
 	</P>
 </UL>
 <P STYLE="margin-bottom: 0in"><BR>
@ -91,10 +92,10 @@ special Firebird interfaces (see README.interfaces about interfaces
 in Firebird). All plugin-specific interfaces are reference counted,
 i.e. have explicitly controlled lifetime. Interfaces are declared in
 Plugin.h include file. There is a simple example of writing plugin
-module – DbCrypt_example. It does not perform any actual encryption
+module &ndash; DbCrypt_example. It does not perform any actual
-– just a sample of how to write plugin. Complete instruction of how
+encryption &ndash; just a sample of how to write plugin. Complete
-to write plugins is out of this document's scope. Here is provided a
+instruction of how to write plugins is out of this document's scope.
-short list of plugin features:</FONT></P>
+Here is provided a short list of plugin features:</FONT></P>
 <UL>
 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>plugin may be written
 	using any language, supporting pure virtual interfaces (you will
@ -102,15 +103,15 @@ short list of plugin features:</FONT></P>
 	are missing);</FONT></P>
 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>like with UDFs you
 	are free to add any reasonable code yo your plugin, but pay
-	attention to word “reasonable” - asking a question from plugin
+	attention to word &ldquo;reasonable&rdquo; - asking a question from
-	at server's console is hardly good idea;</FONT></P>
+	plugin at server's console is hardly good idea;</FONT></P>
 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>it's OK to use
 	Firebird API calls in your plugin if needed (for example, default
 	authentication server and user manager are using Firebird database
 	to store accounts);</FONT></P>
 	<LI><P STYLE="margin-bottom: 0in"><FONT SIZE=4>additionally Firebird
 	provides a set of interfaces, helping you to configure your plugins
-	(certainly,  you are not forced to use them – plugin is generic
+	(certainly, you are not forced to use them &ndash; plugin is generic
 	code, which may use any way of providing configuration information,
 	but with standard tools you get common for the rest of Firebird
 	configuration style and sooner of all save you efforts).</FONT></P>
@ -118,11 +119,11 @@ short list of plugin features:</FONT></P>
 <P STYLE="margin-bottom: 0in"><BR>
 </P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Configuring plugins has 2
-parts – first, engine should be instructed what plugins it should
+parts &ndash; first, engine should be instructed what plugins it
-load, and next plugins themselves sometimes need some configuration.
+should load, and next plugins themselves sometimes need some
-What plugins to be loaded is defined in main configuration file –
+configuration. What plugins to be loaded is defined in main
-firebird.conf for each type of plugin. Like any other value in 
+configuration file &ndash; firebird.conf for each type of plugin.
-firebird.conf the have defaults:</FONT></P>
+Like any other value in firebird.conf the have defaults:</FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>AuthServer = Srp,
 Win_Sspi</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>AuthClient = Srp,
@ -134,7 +135,7 @@ Remote,Engine12,Loopback</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>WireCryptPlugin = Arc4</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>This provides normal
 operation in server, client and embedded cases. If you want to add
-other plugins, you must mention them in firebird.conf – except
+other plugins, you must mention them in firebird.conf &ndash; except
 other this is security measure to avoid loading unknown code. But
 what does for example fbtrace mean here? Is it a name of dynamic
 library to load? In trivial case yes, but exact answer is more
@ -142,42 +143,42 @@ complicated.</FONT></P>
 <P STYLE="margin-bottom: 0in"><BR>
 </P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>As it was already
-mentioned, single plugin module may implement more than single plugin.
+mentioned, single plugin module may implement more than single
-Moreover, single plugin may have at the same time more than one
+plugin. Moreover, single plugin may have at the same time more than
-configuration – and for each configuration separate plugin's
+one configuration &ndash; and for each configuration separate
-factory is created. Each of this 3 objects (module – implementation
+plugin's factory is created. Each of this 3 objects (module &ndash;
-– factory) has it's own name. Name of a module is a file name of
+implementation &ndash; factory) has it's own name. Name of a module
-dynamic library. Plugin implementation's name is one given to it by
+is a file name of dynamic library. Plugin implementation's name is
-plugin developer and hard-coded inside module. Factory's name by
+one given to it by plugin developer and hard-coded inside module.
-default equals to plugin implementation's name (and it's factory name
+Factory's name by default equals to plugin implementation's name (and
-which is actually used in firebird.conf). Certainly in typical
+it's factory name which is actually used in firebird.conf). Certainly
-trivial case, module contains one plugin, and that plugin works with
+in typical trivial case, module contains one plugin, and that plugin
-only one configuration, and all 3 names are equal, and no more
+works with only one configuration, and all 3 names are equal, and no
-configuration is needed – for example libEngine12.so or
+more configuration is needed &ndash; for example libEngine12.so or
 Engine12.dll contains implementation of provider Engine12, and
 nothing else except record </FONT>
 </P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Providers = Engine12</FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>in firebird.conf is needed
-to load it. But if you have something complex – file  will help
+to load it. But if you have something complex &ndash; file will help
 you to have such plugin factories which you really want.</FONT></P>
 <P STYLE="margin-bottom: 0in"><BR>
 </P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>File plugins.conf has 2
-types of records – config and plugin. Plugin record is a set of
+types of records &ndash; config and plugin. Plugin record is a set of
 rules for plugin's loading and activating. Plugin record has the
 following format:</FONT></P>
-<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = PlugName		##
+<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = PlugName ##
 this is name to be referenced in firebird.conf</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>{</I></FONT></P>
-<P STYLE="margin-bottom: 0in">  <FONT SIZE=4><I>Module = LibName		##
+<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Module = LibName ##
 name of dynamic library</I></FONT></P>
-<P STYLE="margin-bottom: 0in">  <FONT SIZE=4><I>RegisterName =
+<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>RegisterName = RegName
-RegName	## name given to plugin by it's developer</I></FONT></P>
+## name given to plugin by it's developer</I></FONT></P>
-<P STYLE="margin-bottom: 0in">  <FONT SIZE=4><I>Config = ConfName		##
+<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Config = ConfName ##
 name of config record to be used</I></FONT></P>
-<P STYLE="margin-bottom: 0in">  <FONT SIZE=4><I>ConfigFile = ConfFile
+<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>ConfigFile = ConfFile
- 		## name of a file, containing plugin's configuration</I></FONT></P>
+## name of a file, containing plugin's configuration</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>}</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>i.e. when plugin PlugName
 is needed Firebird loads library LibName, finds in it plugin
@ -185,35 +186,35 @@ registered with name RegName and passes it configuration from config
 record ConfName or config file ConfFile (config record is used if
 both are given). Each parameter in this record may be missing, in
 that case the default PlugName is used. The only exception is
-ConfigFile – by default, file with same name as module's dynamic
+ConfigFile &ndash; by default, file with same name as module's
-library but .conf extension is used. ConfigFile is expected to have
+dynamic library but .conf extension is used. ConfigFile is expected
-format Key=Value (like other Firebird configuration files), same
+to have format Key=Value (like other Firebird configuration files),
-format is used for plugin record:</FONT></P>
+same format is used for plugin record:</FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Config = ConfName</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>{</I></FONT></P>
-<P STYLE="margin-bottom: 0in">  <FONT SIZE=4><I>Key1 = Value1</I></FONT></P>
+<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Key1 = Value1</I></FONT></P>
-<P STYLE="margin-bottom: 0in">  <FONT SIZE=4><I>Key2 = Value2</I></FONT></P>
+<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Key2 = Value2</I></FONT></P>
-<P STYLE="margin-bottom: 0in">  <FONT SIZE=4><I>...</I></FONT></P>
+<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>...</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>}</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><BR>
 </P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Let's have a sample.
 Suppose some clients of your server trust wire encryption from one
-vendor and others – from another one (and have different licenses
+vendor and others &ndash; from another one (and have different
-for appropriate client parts), but each vendor calls his plugin
+licenses for appropriate client parts), but each vendor calls his
-BestCrypt. Certainly, first of all you have to rename libraries to
+plugin BestCrypt. Certainly, first of all you have to rename
-something like WC1 and WC2 – one can't have 2 files with same name
+libraries to something like WC1 and WC2 &ndash; one can't have 2
-in one directory. But after it, modules stop to load automatically –
+files with same name in one directory. But after it, modules stop to
-they are not named BestCrypt any more. To fix it, plugins.conf should
+load automatically &ndash; they are not named BestCrypt any more. To
-contain something like this:</FONT></P>
+fix it, plugins.conf should contain something like this:</FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = WC1</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>{</I></FONT></P>
-<P STYLE="margin-bottom: 0in">  <FONT SIZE=4><I>RegisterName =
+<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>RegisterName =
 BestCrypt</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>}</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>Plugin = WC2</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>{</I></FONT></P>
-<P STYLE="margin-bottom: 0in">  <FONT SIZE=4><I>RegisterName =
+<P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>RegisterName =
 BestCrypt</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>}</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Module names will be
@ -250,16 +251,16 @@ plugins is used.</FONT></P>
 and Arc4 plugins mean?</FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>A. Srp implements Secure
 Remote Passwords protocol which is default way of authenticating
-users in Firebird 3. It has efficient password’s length equal to 20
+users in Firebird 3. It has efficient password&rsquo;s length equal
-bytes, resistant to most of attacks (including man in the middle) and
+to 20 bytes, resistant to most of attacks (including man in the
-does not require exchanging any keys between client and server to
+middle) and does not require exchanging any keys between client and
-work. Arc4 means Alleged RC4 - an implementation of RC4 cypher. The
+server to work. Arc4 means Alleged RC4 - an implementation of RC4
-advantage of SRP is that it can generate unique cryptographically
+cypher. The advantage of SRP is that it can generate unique
-strong key on both client and server and it's impossible to guess it
+cryptographically strong key on both client and server and it's
-capturing data transferred over the wire during password validation
+impossible to guess it capturing data transferred over the wire
-by SRP. That key is used after SRP handshake by Arc4, which makes
+during password validation by SRP. That key is used after SRP
-wire encryption secure without need to exchange any keys between
+handshake by Arc4, which makes wire encryption secure without need to
-client and server explicitly.</FONT></P>
+exchange any keys between client and server explicitly.</FONT></P>
 <P STYLE="margin-bottom: 0in"><BR>
 </P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>Q. And what do Win_Sspi
@ -267,11 +268,11 @@ and Legacy_Auth mean?</FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4>A. Windows SSPI was used
 since FB 2.1 for windows trusted authentication. Legacy_Auth is
 compatibility plugin. It's enabled by default on client to let it
-connect to pre-FB3 servers. (Yes – it still transfers almost plain
+connect to pre-FB3 servers. (Yes &ndash; it still transfers almost
-passwords over the wire. Compatibility...) On server it works with
+plain passwords over the wire. Compatibility...) On server it works
-security database from FB 2.5, and should be avoided except cases
+with security database from FB 2.5, and should be avoided except
-when you understand well what are you doing. To use  Legacy_Auth on
+cases when you understand well what are you doing. To use Legacy_Auth
-server you should also disable network traffic encryption in
+on server you should also disable network traffic encryption in
 firebird.conf:</FONT></P>
 <P STYLE="margin-bottom: 0in"><FONT SIZE=4><I>WireCrypt = Disabled</I></FONT></P>
 <P STYLE="margin-bottom: 0in"><BR>