Revision: 1384 http://geany-plugins.svn.sourceforge.net/geany-plugins/?rev=1384&view=re... Author: colombanw Date: 2010-05-23 00:57:09 +0000 (Sun, 23 May 2010)
Log Message: ----------- GeanyGenDoc: Also distribute manual in HTML format
Add the generated HTML manual under VCS for the users not to need docutils.
Modified Paths: -------------- trunk/geany-plugins/geanygendoc/ChangeLog trunk/geany-plugins/geanygendoc/docs/help/Makefile.am
Added Paths: ----------- trunk/geany-plugins/geanygendoc/docs/help/manual.html
Modified: trunk/geany-plugins/geanygendoc/ChangeLog =================================================================== --- trunk/geany-plugins/geanygendoc/ChangeLog 2010-05-22 23:19:51 UTC (rev 1383) +++ trunk/geany-plugins/geanygendoc/ChangeLog 2010-05-23 00:57:09 UTC (rev 1384) @@ -1,3 +1,12 @@ +2010-05-23 Colomban Wendling <ban(at)herbesfolles(dot)org> + + * ChangeLog, Makefile.am, data/filetypes/Makefile.am, src/ggd-utils.c: + Temporary hackish fix for data installation. + * ChangeLog, docs/help/Makefile.am, docs/help/manual.html: + Add the generated HTML manual under VCS for the users not to need + docutils. + + 2010-05-22 Colomban Wendling <ban(at)herbesfolles(dot)org>
* src/ggd-plugin.c: @@ -7,8 +16,6 @@ Add an entry in the TODO-list * [All] Import into Geany-Plugins. - * ChangeLog, Makefile.am, data/filetypes/Makefile.am, src/ggd-utils.c: - Temporary hackish fix for data installation.
2010-05-21 Colomban Wendling <ban(at)herbesfolles(dot)org>
Modified: trunk/geany-plugins/geanygendoc/docs/help/Makefile.am =================================================================== --- trunk/geany-plugins/geanygendoc/docs/help/Makefile.am 2010-05-22 23:19:51 UTC (rev 1383) +++ trunk/geany-plugins/geanygendoc/docs/help/Makefile.am 2010-05-23 00:57:09 UTC (rev 1384) @@ -1,19 +1,17 @@ if ENABLE_GEANYGENDOC include $(top_srcdir)/build/vars.docs.mk plugin = geanygendoc -AIXFILES= endif ENABLE_GEANYGENDOC
EXTRA_DIST = manual.rst \ manual.css \ - html4css1.css + html4css1.css \ + manual.html
if ENABLE_GEANYGENDOC -if BUILD_RST plugindoc_DATA = manual.html
-EXTRA_DIST += manual.html - +if BUILD_RST manual.html: manual.rst manual.css $(AM_V_GEN) $(RST2HTML) -d --strict --stylesheet-path manual.css $< $@ endif BUILD_RST
Added: trunk/geany-plugins/geanygendoc/docs/help/manual.html =================================================================== --- trunk/geany-plugins/geanygendoc/docs/help/manual.html (rev 0) +++ trunk/geany-plugins/geanygendoc/docs/help/manual.html 2010-05-23 00:57:09 UTC (rev 1384) @@ -0,0 +1,602 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> +<title>GeanyGenDoc User Manual</title> +<style type="text/css"> + +/* +:Author: Colomban Wendling +:Contact: ban@herbesfolles.org +:Copyright: This stylesheet has been placed in the public domain. + +Stylesheet for use with Docutils. +*/ + +@import url(html4css1.css); + +html { + background-color: #eeeeec; + color: #2e3436; + font-family: bitstream vera sans, sans-serif; + margin: 0 1em; +} + + +h1, h2, h3, h4, h5, h6, p.topic-title { + font-family: georgia, times new roman, times, serif; +} + +h2.subtitle { + font-style: italic; + font-weight: normal; +} + +p, dd { + text-align: justify; +} + +.literal-block, +.literal { + background: #fff; +} +.literal-block { + border: 1px solid #babdb6; + padding: 1px 2px; +} +h1 .literal, h2 .literal, h3 .literal, h4 .literal, h5 .literal, h6 .literal +p.topic-title .literal { + background: inherit; + text-align: left; +} + + +.footnote-reference { + vertical-align: super; + font-size: 75%; +} + + +a { text-decoration: none; } +a:hover { text-decoration: underline } +a:link { color: #204a87; } +a:visited { color: #5c3566; } + +h1 a, h1 a:hover, h1 a:link, h1 a:visited, +h2 a, h2 a:hover, h2 a:link, h2 a:visited, +h3 a, h3 a:hover, h3 a:link, h3 a:visited, +h4 a, h4 a:hover, h4 a:link, h4 a:visited, +h5 a, h5 a:hover, h5 a:link, h5 a:visited, +h6 a, h6 a:hover, h6 a:link, h6 a:visited, +p.topic-title a, p.topic-title a:hover, p.topic-title a:link, p.topic-title a:visited +{ + text-decoration: none; + color: inherit; +} + +</style> +</head> +<body> +<div class="document" id="geanygendoc-user-manual"> +<h1 class="title">GeanyGenDoc User Manual</h1> +<h2 class="subtitle" id="a-handy-hand-guide-for-the-lazy-documenter-in-you">A handy hand guide for the lazy documenter in you</h2> + +<div class="section" id="introduction"> +<h1><a class="toc-backref" href="#id4">Introduction</a></h1> +<p>First of all, welcome to this manual. Then, what is GeanyGenDoc? It is a +plug-in for Geany as you might have noticed; but what is it meant to do? +Basically, it generates and inserts text chunks, particularly from document's +symbols. Its goal is to ease writing documentation for the good.</p> +<div class="contents topic" id="contents"> +<p class="topic-title first">Contents</p> +<ul class="simple"> +<li><a class="reference internal" href="#introduction" id="id4">Introduction</a></li> +<li><a class="reference internal" href="#design" id="id5">Design</a></li> +<li><a class="reference internal" href="#syntax" id="id6">Syntax</a><ul> +<li><a class="reference internal" href="#key-value-pairs" id="id7">Key-Value pairs</a></li> +<li><a class="reference internal" href="#naming" id="id8">Naming</a></li> +<li><a class="reference internal" href="#comments" id="id9">Comments</a></li> +<li><a class="reference internal" href="#value-types" id="id10">Value types</a></li> +</ul> +</li> +<li><a class="reference internal" href="#file-types" id="id11">File types</a><ul> +<li><a class="reference internal" href="#the-settings-group" id="id12">The <tt class="docutils literal">settings</tt> group</a></li> +<li><a class="reference internal" href="#the-doctypes-group" id="id13">The <tt class="docutils literal">doctypes</tt> group</a></li> +</ul> +</li> +<li><a class="reference internal" href="#documentation-types" id="id14">Documentation types</a><ul> +<li><a class="reference internal" href="#short-example" id="id15">Short example</a></li> +</ul> +</li> +<li><a class="reference internal" href="#rules-the-cool-thing" id="id16">Rules: the cool thing</a><ul> +<li><a class="reference internal" href="#type-hierarchy" id="id17">Type hierarchy</a><ul> +<li><a class="reference internal" href="#known-types" id="id18">Known types</a></li> +</ul> +</li> +<li><a class="reference internal" href="#rule-settings" id="id19">Rule settings</a></li> +</ul> +</li> +<li><a class="reference internal" href="#user-interface-in-geany" id="id20">User interface in Geany</a><ul> +<li><a class="reference internal" href="#menus" id="id21">Menus</a><ul> +<li><a class="reference internal" href="#editor-s-pop-up-menu" id="id22">Editor's pop-up menu</a></li> +<li><a class="reference internal" href="#tools-menu" id="id23">Tools menu</a></li> +</ul> +</li> +<li><a class="reference internal" href="#preferences-dialog" id="id24">Preferences dialog</a></li> +</ul> +</li> +<li><a class="reference internal" href="#miscellaneous" id="id25">Miscellaneous</a><ul> +<li><a class="reference internal" href="#configuration-directories" id="id26">Configuration directories</a></li> +</ul> +</li> +<li><a class="reference internal" href="#appendix" id="id27">Appendix</a><ul> +<li><a class="reference internal" href="#configuration-syntax-summary" id="id28">Configuration syntax summary</a></li> +</ul> +</li> +</ul> +</div> +</div> +<div class="section" id="design"> +<h1><a class="toc-backref" href="#id5">Design</a></h1> +<p>GeanyGenDoc has an extensible design based on three points: file type, +documentation type and rules.</p> +<dl class="docutils"> +<dt><a class="reference internal" href="#file-types">File type</a></dt> +<dd>The file type determines which configuration applies to which document. For +example, the "c" file type corresponds to C source, and so on.</dd> +<dt><a class="reference internal" href="#documentation-types">Documentation type</a></dt> +<dd>A documentation type is an arbitrary name for a set of rules. The goal of +documentation types is to allow different set of rules to be defined for each +file type. +One might want to have separate rules to generate for example <a class="reference external" href="http://www.doxygen.org">Doxygen</a> +and <a class="reference external" href="http://www.gtk.org/gtk-doc/">Gtk-Doc</a> documentation from C sources. She should then create two +documentation types in the C <a class="reference internal" href="#file-types">file type configuration file</a>, such as +"doxygen" and "gtkdoc".</dd> +<dt><a class="reference internal" href="#rules-the-cool-thing">Rule</a></dt> +<dd>A rule is a group of settings controlling how a documentation comment is +generated. For example, it can define a template, describe how to handle +particular imbrications and so on.</dd> +</dl> +</div> +<div class="section" id="syntax"> +<h1><a class="toc-backref" href="#id6">Syntax</a></h1> +<div class="section" id="key-value-pairs"> +<h2><a class="toc-backref" href="#id7">Key-Value pairs</a></h2> +<p>The syntax used by the configuration files is an extended key-value tree +definition based on common concepts (trees, string literals, semicolon-ended +values, etc.).</p> +<p>The key-value syntax is as follows:</p> +<pre class="literal-block"> +key = value +</pre> +<p>where value is either a semicolon-ended single value:</p> +<pre class="literal-block"> +value; +</pre> +<p>or a brace-surrounded list of key-value pairs that use the same syntax again:</p> +<pre class="literal-block"> +{ + key1 = value1 + key2 = value2 +} +</pre> +<p>Here a little example of the <em>syntax</em> (not any actual configuration example):</p> +<pre class="literal-block"> +key1 = value1; +key2 = { + sub-key1 = sub-value1; + sub-key2 = { + sub-sub-key1 = sub-sub-value1; + } +} +</pre> +</div> +<div class="section" id="naming"> +<h2><a class="toc-backref" href="#id8">Naming</a></h2> +<p>Key-value pairs are often referred as <em>group</em> when they are meant to have +multiple values and as <em>setting</em> when they have a single value.</p> +</div> +<div class="section" id="comments"> +<h2><a class="toc-backref" href="#id9">Comments</a></h2> +<p>Is considered as comment (and therefore ignored) everything between a number +sign (<tt class="docutils literal">#</tt>) and the following end of line, unless the <tt class="docutils literal">#</tt> occurs as part of +another syntactic element (such as a string literal).</p> +<p>A short example:</p> +<pre class="literal-block"> +# This is a comment +key = value; # This is also a comment +string = "A string. # This isn't a comment but a string"; +</pre> +</div> +<div class="section" id="value-types"> +<h2><a class="toc-backref" href="#id10">Value types</a></h2> +<dl class="docutils"> +<dt>string</dt> +<dd><p class="first">A string literal. String literals are surrounded by either single (<tt class="docutils literal">'</tt>) or +double (<tt class="docutils literal">"</tt>) quotes.</p> +<p>Some special characters can be inserted in a string with an escape sequence:</p> +<dl class="docutils"> +<dt><tt class="docutils literal">\t</tt></dt> +<dd>A tabulation.</dd> +<dt><tt class="docutils literal">\n</tt></dt> +<dd>A new line.</dd> +<dt><tt class="docutils literal">\r</tt></dt> +<dd>A carriage return.</dd> +<dt><tt class="docutils literal">\</tt></dt> +<dd>A backslash.</dd> +<dt><tt class="docutils literal">'</tt></dt> +<dd>A single quote (escaping only needed in single-quotes surrounded strings).</dd> +<dt><tt class="docutils literal">"</tt></dt> +<dd>A double quote (escaping only needed in double-quotes surrounded strings).</dd> +</dl> +<p>Note that backslashes are used as the escaping character, which means that it +must be escaped to be treated as a simple backslash character.</p> +<p>A simple example:</p> +<pre class="last literal-block"> +"This is a string with "special" characters.\nThis is another line!" +</pre> +</dd> +<dt>boolean</dt> +<dd>A boolean. It can take one of the two symbolic values <tt class="docutils literal">True</tt> and <tt class="docutils literal">False</tt>.</dd> +<dt>enumeration</dt> +<dd>An enumeration. It consists of a named constant, generally in capital letters. +The possible values depend on the setting that use this type.</dd> +<dt>flags</dt> +<dd><p class="first">A logical OR of named constants. This is like enumerations but can combine +different values.</p> +<p class="last">The syntax is common for such types and uses the pipe (<tt class="docutils literal">|</tt>) as +combination character. Considering the <tt class="docutils literal">A</tt>, <tt class="docutils literal">B</tt> and <tt class="docutils literal">C</tt> constants, a +valid value could be <tt class="docutils literal">A | C</tt>, which represents both <tt class="docutils literal">A</tt> and <tt class="docutils literal">C</tt> but +not <tt class="docutils literal">B</tt>.</p> +</dd> +<dt>list</dt> +<dd>A list of values (often referred as array).</dd> +</dl> +</div> +</div> +<div class="section" id="file-types"> +<h1><a class="toc-backref" href="#id11">File types</a></h1> +<p>The file type determines which configuration applies to which document. +<em>File type identifiers</em> are the lowercased name of the Geany's file type, for +example "c" or "python".</p> +<p>Configuration for a particular file type goes in a file named +<tt class="docutils literal"><span class="pre">file-type-identifier.conf</span></tt> in the <tt class="docutils literal">filetypes</tt> sub-directory of a +<a class="reference internal" href="#configuration-directories">configuration directory</a>.</p> +<p>A file type configuration can contain two type of things: file-type-wide +settings and any number of <a class="reference internal" href="#documentation-types">documentation types</a>.</p> +<div class="section" id="the-settings-group"> +<h2><a class="toc-backref" href="#id12">The <tt class="docutils literal">settings</tt> group</a></h2> +<p>This group contains the file-type-wide settings.</p> +<dl class="docutils"> +<dt><tt class="docutils literal">match_function_arguments</tt> (string)</dt> +<dd>A regular expression used to extract arguments from a function-style argument +list (functions, methods, macros, etc.). This regular expression should match +one argument at a time and capture only the argument's name. +This setting is a little odd but currently needed to extract argument list +from function definitions.</dd> +<dt><tt class="docutils literal">global_environment</tt> (string)</dt> +<dd>A description of a <a class="reference external" href="http://ctpl.tuxfamily.org/">CTPL</a> environment to add when parsing <a class="reference internal" href="#rules-the-cool-thing">rule</a>'s templates.</dd> +</dl> +</div> +<div class="section" id="the-doctypes-group"> +<h2><a class="toc-backref" href="#id13">The <tt class="docutils literal">doctypes</tt> group</a></h2> +<p>This group contains a list of <a class="reference internal" href="#documentation-types">documentation types</a>.</p> +</div> +</div> +<div class="section" id="documentation-types"> +<h1><a class="toc-backref" href="#id14">Documentation types</a></h1> +<p>A documentation type is a named set of <a class="reference internal" href="#rules-the-cool-thing">rules</a> for a <a class="reference internal" href="#file-types">file type</a>, describing how +to generate a particular type of documentation (i.e. <a class="reference external" href="http://www.doxygen.org">Doxygen</a>, <a class="reference external" href="http://www.gtk.org/gtk-doc/">Gtk-Doc</a>, +<a class="reference external" href="http://www.valadoc.org/">Valadoc</a> or whatever).</p> +<p>A documentation type is identified by its name and must therefore be unique +in a file type. But of course, different file types can define the same +documentation type. It is even recommended for a better consistency to use the +same identifier in different file types when they generate the same type of +documentation (even though it is completely up to you).</p> +<div class="section" id="short-example"> +<h2><a class="toc-backref" href="#id15">Short example</a></h2> +<pre class="literal-block"> +doxygen = { + struct.member = { + template = " /**< {cursor} */"; + position = AFTER; + } + struct.template = "/**\n * @brief: {cursor}\n * \n * \n */\n"; +} +</pre> +</div> +</div> +<div class="section" id="rules-the-cool-thing"> +<h1><a class="toc-backref" href="#id16">Rules: the cool thing</a></h1> +<p>Rules are the actual definition of how documentation is generated. A rule +applies to a symbol type and hierarchy, allowing fine control over which and +how symbols are documented.</p> +<p>A rule is represented as a group of <a class="reference internal" href="#rule-settings">settings</a> in a <a class="reference internal" href="#documentation-types">documentation type</a>. +The name of this group is the <a class="reference internal" href="#type-hierarchy">type hierarchy</a> to which the settings applies.</p> +<div class="section" id="type-hierarchy"> +<h2><a class="toc-backref" href="#id17">Type hierarchy</a></h2> +<p>A type hierarchy is a hierarchy of the types that a symbol must have to match +this rule.</p> +<p>In the symbol side, the type hierarchy is the types of the symbol's parents, +terminated by the symbol's own type. For example, a method in a class would +have a hierarchy like <tt class="docutils literal">class <span class="pre">-></span> method</tt>; and if the class is itself in a +namespace, the hierarchy would the look like <tt class="docutils literal">namespace <span class="pre">-></span> class <span class="pre">-></span> method</tt>, +and so on.</p> +<p>For a rule to apply, its type hierarchy must match <em>the end</em> of the symbol +type hierarchy. For example a rule with the type hierarchy <tt class="docutils literal">class</tt> will match +a symbol with the type hierarchy <tt class="docutils literal">namespace <span class="pre">-></span> class</tt> but not one with +<tt class="docutils literal">class <span class="pre">-></span> method</tt>.</p> +<p>A type hierarchy uses dots (<tt class="docutils literal">.</tt>) to separate types and build the hierarchy. +For example, the type hierarchy representing <tt class="docutils literal">namespace <span class="pre">-></span> class</tt> would be +written <tt class="docutils literal">namespace.class</tt>.</p> +<div class="section" id="known-types"> +<h3><a class="toc-backref" href="#id18">Known types</a></h3> +<dl class="docutils"> +<dt><tt class="docutils literal">class</tt></dt> +<dd>A class.</dd> +<dt><tt class="docutils literal">enum</tt></dt> +<dd>An enumeration.</dd> +<dt><tt class="docutils literal">enumval</tt></dt> +<dd>An enumeration value.</dd> +<dt><tt class="docutils literal">field</tt></dt> +<dd>A field (of a class for example).</dd> +<dt><tt class="docutils literal">function</tt></dt> +<dd>A function.</dd> +<dt><tt class="docutils literal">interface</tt></dt> +<dd>An interface.</dd> +<dt><tt class="docutils literal">member</tt></dt> +<dd>A member (of a structure for example).</dd> +<dt><tt class="docutils literal">method</tt></dt> +<dd>A method.</dd> +<dt><tt class="docutils literal">namespace</tt></dt> +<dd>A namespace.</dd> +<dt><tt class="docutils literal">package</tt></dt> +<dd>A package.</dd> +<dt><tt class="docutils literal">prototype</tt></dt> +<dd>A prototype.</dd> +<dt><tt class="docutils literal">struct</tt></dt> +<dd>A structure.</dd> +<dt><tt class="docutils literal">typedef</tt></dt> +<dd>A type alias definition (<em>typedef</em> in C).</dd> +<dt><tt class="docutils literal">union</tt></dt> +<dd>An union.</dd> +<dt><tt class="docutils literal">variable</tt></dt> +<dd>A variable.</dd> +<dt><tt class="docutils literal">extern</tt></dt> +<dd><cite>???</cite></dd> +<dt><tt class="docutils literal">define</tt></dt> +<dd>A definition (like the <em>define</em> C preprocessor macro).</dd> +<dt><tt class="docutils literal">macro</tt></dt> +<dd>A macro.</dd> +<dt><tt class="docutils literal">file</tt></dt> +<dd>A file (will never match).</dd> +</dl> +</div> +</div> +<div class="section" id="rule-settings"> +<h2><a class="toc-backref" href="#id19">Rule settings</a></h2> +<dl class="docutils"> +<dt><tt class="docutils literal">template</tt> (string)</dt> +<dd><p class="first">A <a class="reference external" href="http://ctpl.tuxfamily.org/">CTPL</a> template that can include references to the following predefined +variables in addition to the file-type-wide and the global environment:</p> +<dl class="docutils"> +<dt><tt class="docutils literal">argument_list</tt> (string list)</dt> +<dd>A list of the arguments of the currently documented symbol.</dd> +<dt><tt class="docutils literal">returns</tt> (boolean)</dt> +<dd>Indicates whether the currently documented symbol returns a value +(makes sense only for symbols that may return a value).</dd> +<dt><tt class="docutils literal">children</tt> (string list)</dt> +<dd>A list of the current symbol's first-level children. This is only set if +the rule's setting <tt class="docutils literal">children</tt> is set to <tt class="docutils literal">MERGE</tt>.</dd> +</dl> +<p><strong>[...]</strong></p> +<dl class="last docutils"> +<dt><tt class="docutils literal">cursor</tt> (special, described below)</dt> +<dd>This can be used to mark in the template the position where the editor's +cursor should be moved to after comment insertion. +This mark will be removed from the generated documentation. +Note that even if this mark may occur as many times as you want in a +template, only the first will be actually honored, the latter being +only removed.</dd> +</dl> +</dd> +<dt><tt class="docutils literal">position</tt> (enumeration)</dt> +<dd><p class="first">The position where the documentation should be inserted. Possible values are:</p> +<dl class="last docutils"> +<dt><tt class="docutils literal">BEFORE</tt> <a class="citation-reference" href="#default" id="id1">[default]</a></dt> +<dd>Inserts the documentation just before the symbol.</dd> +<dt><tt class="docutils literal">AFTER</tt></dt> +<dd>Inserts the documentation just after the symbol (currently quite limited, it +inserts the documentation at the end of the symbol's first line).</dd> +<dt><tt class="docutils literal">CURSOR</tt></dt> +<dd>Inserts the documentation at the current cursor position.</dd> +</dl> +</dd> +<dt><tt class="docutils literal">policy</tt> (enumeration)</dt> +<dd><p class="first">How the symbol is documented. Possible values are:</p> +<dl class="last docutils"> +<dt><tt class="docutils literal">KEEP</tt> <a class="citation-reference" href="#default" id="id2">[default]</a></dt> +<dd>The symbol documents itself.</dd> +<dt><tt class="docutils literal">FORWARD</tt></dt> +<dd>Forward the documentation request to the parent. This is useful for symbols +that are documented by their parent, such as <a class="reference external" href="http://www.gtk.org/gtk-doc/">Gtk-Doc</a>'s enumerations.</dd> +</dl> +</dd> +<dt><tt class="docutils literal">children</tt> (enumeration)</dt> +<dd><p class="first">How the symbol's children can be used in the template. Possible values are:</p> +<dl class="last docutils"> +<dt><tt class="docutils literal">SPLIT</tt> <a class="citation-reference" href="#default" id="id3">[default]</a></dt> +<dd>The symbol's children are provided as per-type lists.</dd> +<dt><tt class="docutils literal">MERGE</tt></dt> +<dd>The symbol's children are provided as a single list named <tt class="docutils literal">children</tt>.</dd> +</dl> +</dd> +<dt><tt class="docutils literal">matches</tt> (flags)</dt> +<dd>List of the children types that should be provided. Only useful if the +<tt class="docutils literal">children</tt> setting is set to <tt class="docutils literal">MERGE</tt>. +Defaults to all. +<strong>FIXME: check the exactitude of this description</strong></dd> +<dt><tt class="docutils literal">auto_doc_children</tt> (boolean)</dt> +<dd>Whether to also document symbol's children (according to their own rules).</dd> +</dl> +</div> +</div> +<div class="section" id="user-interface-in-geany"> +<h1><a class="toc-backref" href="#id20">User interface in Geany</a></h1> +<div class="section" id="menus"> +<h2><a class="toc-backref" href="#id21">Menus</a></h2> +<p>GeanyGenDoc adds an item named <cite>Insert Documentation Comment</cite> in the editor's +pop-up under the <cite>Insert Comments</cite> sub-menu; and a menu named +<cite>Documentation Generator</cite> into the <cite>Tools</cite> menu.</p> +<div class="section" id="editor-s-pop-up-menu"> +<h3><a class="toc-backref" href="#id22">Editor's pop-up menu</a></h3> +<p>The item <cite>Editor's pop-up → Insert Comments → Insert Documentation Comment</cite> +generates documentation for the current symbol. It has a keyboard shortcut +that can be configured through Geany's keybinding configuration system, under +<cite>GeanyGenDoc → Insert Documentation Comment</cite>.</p> +</div> +<div class="section" id="tools-menu"> +<h3><a class="toc-backref" href="#id23">Tools menu</a></h3> +<p>The <cite>Documentation Generator</cite> menu under <cite>Tools</cite> contains the following items:</p> +<dl class="docutils"> +<dt><cite>Document Current Symbol</cite></dt> +<dd>This generates documentation for the current symbol. It is equivalent to the +item <cite>Insert Documentation Comment</cite> that can be found in the editor's pop-up +menu.</dd> +<dt><cite>Document All Symbols</cite></dt> +<dd>This generates documentation for all symbols in the document. This is +equivalent to manually requesting documentation generation for each symbol in +the document.</dd> +<dt><cite>Reload Configuration Files</cite></dt> +<dd>This force reloading of all the <a class="reference internal" href="#file-types">file type</a> configuration files. It is +useful when a file type configuration file was modified, in order to the new +configuration to be used without reloading the plugin.</dd> +<dt><cite>Edit Current Language Configuration</cite></dt> +<dd>This opens the configuration file that applies to the current document for +editing. The opened configuration file has write permissions: if it was a +system configuration file it is copied under your personal <a class="reference internal" href="#configuration-directories">configuration +directory</a> transparently.</dd> +<dt><cite>Open Manual</cite></dt> +<dd>Opens this manual in a browser.</dd> +</dl> +</div> +</div> +<div class="section" id="preferences-dialog"> +<h2><a class="toc-backref" href="#id24">Preferences dialog</a></h2> +<p>The preferences dialog, than can either be opened through <cite>Edit → +Plugin Preferences</cite> or with the <cite>Preferences</cite> button in the plugin manager, +allows to modify the following preferences:</p> +<dl class="docutils"> +<dt><cite>General</cite></dt> +<dd><dl class="first last docutils"> +<dt><cite>Save file before generating documentation</cite></dt> +<dd>Choose whether the current document should be saved to disc before +generating the documentation. This is a technical detail, but it is +currently needed to have an up-to-date tag list. If you disable this option +and ask for documentation generation on a modified document, the behavior +may be surprising since the comment will be generated for the last saved +state of the document and not the current one.</dd> +<dt><cite>Indent inserted documentation</cite></dt> +<dd>Chooses whether the inserted documentation should be indented to fit the +indentation at the insertion position.</dd> +</dl> +</dd> +<dt><cite>Documentation type</cite></dt> +<dd>This list allows you to choose the documentation type to use with each file +type. The special language <cite>All</cite> on top of the list is used to choose the +default documentation type, used for all languages that haven't one set.</dd> +<dt><cite>Global environment</cite></dt> +<dd>Global environment overrides and additions. This is an environment that will +be merged with the <a class="reference internal" href="#file-types">file type</a>-specific ones, possibly overriding some parts. +It can be used to define some values for all the file types, such as whether +to write the common <cite>Since</cite> tag, define the <a class="reference external" href="http://www.doxygen.org">Doxygen</a> prefix an so on. +Its most use case is not to need to change a file type's environment to change +the value of one of its elements.</dd> +</dl> +</div> +</div> +<div class="section" id="miscellaneous"> +<h1><a class="toc-backref" href="#id25">Miscellaneous</a></h1> +<div class="section" id="configuration-directories"> +<h2><a class="toc-backref" href="#id26">Configuration directories</a></h2> +<p>Configuration directories hold GeanyGenDoc's configuration. They are the +following:</p> +<ul class="simple"> +<li>The user-specific configuration directory, containing the user-defined +settings is <tt class="docutils literal">$GEANY_USER_CONFIG/plugins/geanygendoc/</tt>. +<tt class="docutils literal">$GEANY_USER_CONFIG</tt> is generally <tt class="docutils literal"><span class="pre">~/.config/geany/</span></tt> on UNIX systems.</li> +<li>The system-wide configuration directory containing the default and +pre-installed configuration is <tt class="docutils literal">$GEANY_SYS_CONFIG/plugins/geanygendoc/</tt>. +<tt class="docutils literal">$GEANY_SYS_CONFIG</tt> is generally <tt class="docutils literal">/usr/share/geany/</tt> or +<tt class="docutils literal">/usr/local/share/geany</tt> on UNIX systems.</li> +</ul> +<p>When searching for configuration, GeanyGenDoc will first look in the +user's configuration directory, and if it wasn't successful, in the system +configuration directory. If both failed, it assumes that there is no +configuration at all.</p> +</div> +</div> +<div class="section" id="appendix"> +<h1><a class="toc-backref" href="#id27">Appendix</a></h1> +<div class="section" id="configuration-syntax-summary"> +<h2><a class="toc-backref" href="#id28">Configuration syntax summary</a></h2> +<pre class="literal-block"> +string ::= ( """ .* """ | "'" .* "'" ) +constant ::= [_A-Z][_A-Z0-9]+ +integer ::= [0-9]+ +boolean ::= ( "True" | "False" ) +setting_value ::= ( string | constant | integer ) +setting ::= "setting-name" "=" setting_value ";" +setting_list ::= ( "{" setting* "}" | setting ) +setting_section ::= "settings" "=" setting_list + +position ::= ( "BEFORE" | "AFTER" | "CURSOR" ) +policy ::= ( "KEEP" | "FORWARD" ) +children ::= ( "SPLIT" | "MERGE" ) +type ::= ( "class" | "enum" | "enumval" | "field" | + "function" | "interface" | "member" | "method" | + "namespace" | "package" | "prototype" | "struct" | + "typedef" | "union" | "variable" | "extern" | + "define" | "macro" | "file" ) +matches ::= type ( "|" type )* +doctype_subsetting ::= ( "template" "=" string | + "position" "=" position | + "policy" "=" policy | + "children" "=" children | + "matches" "=" matches | + "auto_doc_children" "=" boolean ) ";" +match ::= type ( "." type )* +doctype_setting ::= ( match "=" "{" doctype_subsetting* "}" | + match "." doctype_subsetting ) +doctype_setting_list ::= ( "{" doctype_setting* "}" | doctype_setting ) +doctype ::= "doctype-name" "=" doctype_setting_list +doctype_list ::= ( "{" doctype* "}" | doctype ) +doctype_section ::= "doctypes" "=" doctype_list + +document ::= ( setting_section? doctype_section? | + doctype_section? setting_section? ) +</pre> +<!-- Content end, begin references --> +<!-- External links --> +<!-- --> +<!-- Internal links --> +<!-- --> +<hr class="docutils" /> +<table class="docutils citation" frame="void" id="default" rules="none"> +<colgroup><col class="label" /><col /></colgroup> +<tbody valign="top"> +<tr><td class="label">[default]</td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id2">2</a>, <a class="fn-backref" href="#id3">3</a>)</em> This is the default value of the setting</td></tr> +</tbody> +</table> +</div> +</div> +</div> +<div class="footer"> +<hr class="footer" /> +Generated on: 2010-05-22. + +</div> +</body> +</html>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
plugins-commits@lists.geany.org