common/locale/en-US/developer.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>
   3
   4 <!DOCTYPE document SYSTEM "dactyl://content/dtd" [
   5     <!ENTITY tab "&#xa0;&#xa0;&#xa0;">
   6 ]>
   7
   8 <document
   9     name="developer"
  10     title="&dactyl.appName; Developer information"
  11     xmlns="&xmlns.dactyl;"
  12     xmlns:html="&xmlns.html;">
  13
  14 <h1 tag="developer-information developer">Developer information</h1>
  15 <toc start="2"/>
  16
  17 <h2 tag="writing-docs documentation">Writing documentation</h2>
  18
  19 <p>
  20     In order for any user-visible change to be accepted into the mainline, it
  21     must be accompanied by accurate documentation. The docs are written in an
  22     XML dialect similar to XHTML, with a few tags specific to our
  23     documentation. For example:
  24 </p>
  25
  26 <xml-block><item>
  27     <tags>:help :h help</tags>
  28     <spec>:h<oa>elp</oa> <oa>subject</oa></spec>
  29     <description>
  30         <p>
  31             Open the help page. The default page, as specified by <o>helpfile</o> is shown
  32             unless <oa>subject</oa> is specified. If you need help for a specific topic, try
  33             <ex>:help overview</ex>.
  34         </p>
  35     </description>
  36 </item></xml-block>
  37
  38 <p>
  39     creates a new help section for the command <ex>:help</ex>. It
  40     also creates help tags for the command, its shortcuts, the key
  41     binding, and the general topic, ‘help’. These tags enable
  42     linking to this section from other mentions of the topic and
  43     from the <ex>:help</ex> command.
  44 </p>
  45
  46 <h3 tag="help-tags help-xml">Help tags</h3>
  47
  48 <p>
  49     The following is a list of the more common XML tags used in help pages,
  50     along with their highlight groups.
  51 </p>
  52
  53 <dl>
  54     <dt>Layout</dt><dd/>
  55     <dt>p</dt>         <dd>A paragraph (HelpParagraph)</dd>
  56     <dt>h1</dt>        <dd>A first-level heading (HelpHead1)</dd>
  57     <dt>h2</dt>        <dd>A second-level heading (HelpHead2)</dd>
  58     <dt>h3</dt>        <dd>A third-level heading (HelpHead3)</dd>
  59     <dt>h4</dt>        <dd>A fourth-level heading (HelpHead4)</dd>
  60     <dt>code</dt>      <dd>A pre-formatted code block. (HelpCode)</dd>
  61     <dt>note</dt>      <dd><note>A note paragraph. (HelpNote)</note></dd>
  62     <dt>strut</dt>     <dd>A horizontal strut which prevents any previous floating elements from appearing below it.</dd>
  63     <dt>warning</dt>   <dd><warning>A warning paragraph. (HelpWarning)</warning></dd>
  64 </dl>
  65 <dl>
  66     <dt>Generic</dt><dd/>
  67     <dt>link</dt>         <dd>A generic link. (HelpLink)</dd>
  68     <dt>&tab;@topic</dt>  <dd>The topic of the link. Either a help topic or a fully-qualified URI.</dd>
  69     <dt>em</dt>           <dd><em>Emphasized</em> text. (HelpEm)</dd>
  70     <dt>str</dt>          <dd>A <str>string</str>, with its contents wrapped in quotes. (HelpString)</dd>
  71     <dt>logo</dt>         <dd>&dactyl.appName;'s logo. (Logo)</dd>
  72 </dl>
  73 <dl>
  74     <dt>Items</dt><dd/>
  75     <dt>item</dt>       <dd>A help entry (HelpItem)</dd>
  76     <dt>&tab;tags</dt>  <dd>See the 'Tagging' section (HelpTags)</dd>
  77     <dt>&tab;spec</dt>  <dd>The specification for this item, such as an example command line. (HelpSpec)</dd>
  78     <dt>&tab;strut</dt> <dd>A horizontal formatting strut which ensures that all previous &lt;tags> and &lt;spec> elements appear above the ones that follow.</dd>
  79     <dt>&tab;type</dt>  <dd>For options, the type of the option.
  80                             <em>number</em>, <em>boolean</em>, <em>string</em>, <em>stringlist</em>, or <em>charlist</em>.
  81                             (HelpType)
  82                         </dd>
  83     <dt>&tab;default</dt>     <dd>For options, the default value. (HelpDefault)</dd>
  84     <dt>&tab;description</dt> <dd>The description of this help item. (HelpDescription)</dd>
  85     <dt>&tab;&tab;@short</dt> <dd>Indicates that this is a short description which should appear between the specs and tags.</dd>
  86     <dt>a</dt>  <dd>Required <a>argument</a>. (HelpArg)</dd>
  87     <dt>oa</dt> <dd>Optional <oa>argument</oa>. (HelpOptionalArg)</dd>
  88 </dl>
  89 <dl>
  90     <dt>Tagging</dt><dd/>
  91     <dt>tags</dt>   <dd>Space-separated list of strings to tag. Displayed right-aligned, and used for cross-linking. (HelpTags)</dd>
  92     <dt>@tag</dt>   <dd>The tag attribute. Applied to any element, generates a &lt;tags> element for the given tags. (HelpTag)</dd>
  93 </dl>
  94 <dl>
  95     <dt>Linking</dt><dd/>
  96     <dt>o</dt>          <dd>Link to an option. (HelpOpt)</dd>
  97     <dt>ex</dt>         <dd>Link to an Ex command. (HelpEx)</dd>
  98     <dt>k</dt>          <dd>Link to a key. (HelpKey)</dd>
  99     <dt>&tab;@name</dt> <dd>The name attribute to &lt;k>. When provided, &lt;<a>value</a>> is prepended to
 100                             the element's contents, i.e., <em>&lt;k name="Tab"/></em> becomes <em><k name="Tab"/></em>.
 101                         </dd>
 102     <dt>&tab;@mode</dt> <dd>The mode attribute to &lt;k>. Some keys have different functions in different modes.
 103                             You can use this attribute to specify which of the modes (other than Normal) a key pertains to.
 104                             The &lt;<a>value</a>> is prepended to the element's contents, i.e., <em>&lt;k name="C-i" mode="I"/></em>
 105                             becomes <em><k name="C-i" mode="I"/></em>, and <em>&lt;k mode="t">i&lt;/k></em> becomes <em><k mode="t">i</k></em>.
 106                         </dd>
 107     <dt>t</dt>          <dd>Links to an arbitrary help topic. (HelpTopic)</dd>
 108 </dl>
 109 <dl>
 110     <dt>Plugins</dt><dd/>
 111     <dt>@lang</dt>             <dd>When applied to any element under
 112         &lt;plugin>, that element is only visible for a specific
 113         locale.</dd>
 114     <dt>plugin</dt>            <dd>The container tag used for describing a plugin.</dd>
 115     <dt>&tab;@name</dt>        <dd>The name of the plugin. Used as the plugin's help tag.</dd>
 116     <dt>&tab;@version</dt>     <dd>The plugin's version number.</dd>
 117     <dt>&tab;@href</dt>        <dd>The plugin's home page.</dd>
 118     <dt>&tab;@summary</dt>     <dd>A short description of the plugin, shown in its section head.</dd>
 119
 120     <dt>info</dt>              <dd>An element with the same
 121         attributes as plugin, which may override the latter for
 122         specific locales</dd>
 123
 124     <dt>project</dt>           <dd>The project for which this plugin was intended.</dd>
 125     <dt>&tab;@name</dt>        <dd>The name of the project (i.e., <str>&dactyl.appName;</str>)</dd>
 126     <dt>&tab;@min-version</dt>  <dd>The minimum version of the project for which this plugin is intended to work.</dd>
 127     <dt>&tab;@max-version</dt>  <dd>The maximum version of the project for which this plugin is intended to work.</dd>
 128
 129     <dt>author</dt>            <dd>The plugin's author. May appear more than once.</dd>
 130     <dt>&tab;@href</dt>        <dd>The author's home page.</dd>
 131     <dt>&tab;@email</dt>       <dd>The author's email address.</dd>
 132
 133     <dt>license</dt>           <dd>The plugin's license. May appear more than once.</dd>
 134     <dt>&tab;@href</dt>        <dd>The URI of a page which shows or explains the license.</dd>
 135 </dl>
 136
 137 <h2 tag="generating-docs">Generating documentation</h2>
 138
 139 <p>
 140     You can also autogenerate most of the XML help after you have
 141     written a new command, mapping or option.
 142 </p>
 143
 144 <example><ex>:echo dactyl.generateHelp(commands.get(<str>addons</str>), <![CDATA[<p>Extra text</p>]]>)</ex></example>
 145
 146 <h2 tag="writing-plugins">Writing plugins</h2>
 147
 148 <p>
 149     Writing &dactyl.appName; plugins is incredibly simple. Plugins are
 150     simply JavaScript files which run with full chrome privileges and
 151     have full access to the &dactyl.appName; and &dactyl.host; APIs.
 152     Each plugin has its own global object, which means that the
 153     variables and functions that you create won't pollute the global
 154     <em>window</em> or private <em>dactyl</em> namespaces. This means
 155     that there's no need to wrap your plugin in a closure, as is often
 156     the practice in JavaScript development. Furthermore, any plugin
 157     which is installed in your <o>runtimepath</o><em>/plugins</em>
 158     directory will find its context stored in
 159     <em>plugins.&lt;pluginName></em>, which is often invaluable during
 160     development and testing.
 161 </p>
 162
 163 <p>
 164     Plugins are always initialized after the main window is loaded, so
 165     there is no need to write <str>load</str> event handlers. Beyond
 166     that, what you may do with your plugins is practically limitless.
 167     Plugins have full access to all of the chrome resources that
 168     ordinary &dactyl.host; does, along with the entire power of the
 169     &dactyl.appName; API. If you need a starting point, have a look at some
 170     <link topic="&dactyl.plugins;">existing plugins</link> or
 171     <link topic="http://addon.mozilla.org/">extensions</link>,
 172     especially the
 173     <link topic="&dactyl.code;source/browse/">&dactyl.appName;</link>
 174     source.
 175 </p>
 176
 177 <h3 tag="plugin-documentation">Plugin documentation</h3>
 178
 179 <p>
 180     Plugins should provide inline documentation, which will appear on the
 181     <ex>:help <str delim="">plugins</str></ex> page. The markup for help entries is the same
 182     as the above, along with a few extra plugin-specific entries. Here is an
 183     example from the popular <em>flashblock</em> extension:
 184 </p>
 185
 186 <xml-block><escape><hl key="HelpXMLString">use strict</hl>;
 187 XML.ignoreWhitespace = <hl key="Boolean">false</hl>;
 188 XML.prettyPrinting   = <hl key="Boolean">false</hl>;
 189 <hl key="HelpXMLBase">var</hl> INFO = <!-- Cursed manual XML highlighting! -->
 190 <hl key="HelpXMLTagStart">&lt;plugin
 191     <hl key="HelpXMLAttribute">name</hl><hl key="HelpXMLString">flashblock</hl>
 192     <hl key="HelpXMLAttribute">version</hl><hl key="HelpXMLString">1.0</hl>
 193     <hl key="HelpXMLAttribute">href</hl><hl key="HelpXMLString">http://5digits.org/pentadactyl/plugins#flashblock-plugin</hl>
 194     <hl key="HelpXMLAttribute">summary</hl><hl key="HelpXMLString">Flash Blocker</hl>
 195     <hl key="HelpXMLAttribute">xmlns</hl>{NS}></hl></escape>
 196     <author email="maglione.k@gmail.com">Kris Maglione</author>
 197     <license href="http://opensource.org/licenses/mit-license.php">MIT</license>
 198     <project name="Pentadactyl" min-version="1.0"/>
 199     <p>
 200         This plugin provides the same features as the ever popular FlashBlock
 201         Firefox addon. Flash animations are substituted with place holders which
 202         play the original animation when clicked. Additionally, this plugin provides
 203         options to control which sites can play animations without restrictions, and
 204         triggers to toggle the playing of animation on the current page.
 205     </p>
 206     <item>
 207         <tags>'fb' 'flashblock'</tags>
 208         <spec>'flashblock' 'fb'</spec>
 209         <type>boolean</type>
 210         <default>true</default>
 211         <description>
 212             <p>
 213                 Controls the blocking of flash animations. When true, place
 214                 holders are substituted for flash animations on untrusted sites.
 215             </p>
 216         </description>
 217     </item>
 218     <escape><oa>…</oa>
 219 <hl key="HelpXMLTagEnd">&lt;/plugin></hl></escape>;</xml-block>
 220
 221 <p>
 222     The inline XML is made possible by
 223     <link topic="https://developer.mozilla.org/en/E4X">E4X</link>.
 224     It is important that the documentation be assigned to the
 225     <em>INFO</em> variable, or &dactyl.appName; will not be able
 226     to find it. The XML property changes are not compulsory, but
 227     they do prevent certain formatting problems that may occur
 228     otherwise. Beginning your file with <str>use strict</str>, while
 229     not required, helps to prevent a lot of common errors.
 230 </p>
 231
 232 <p>
 233     The documentation that you provide behaves exactly as other
 234     &dactyl.appName; documentation, which means that the tags you
 235     provide are available via <ex>:help</ex> with full tag
 236     completion and cross-referencing support. Although documentation
 237     is not required, we strongly recommend that all plugin authors
 238     provide at least basic documentation of the functionality of
 239     their plugins and of each of the options, commands, and
 240     especially mappings that they provide.
 241 </p>
 242
 243 </document>
 244
 245 <!-- vim:se sts=4 sw=4 et: -->