Revision: 1411 http://geany-plugins.svn.sourceforge.net/geany-plugins/?rev=1411&view=re... Author: colombanw Date: 2010-05-27 15:16:40 +0000 (Thu, 27 May 2010)
Log Message: ----------- GeanyGenDoc: Move manual to docs/ and install HTML in DOCDIR/html
Move the manual sources from docs/help to docs since the sub-directory is useless and led to some confusion. Install the HTML version of the manual in DOCDIR/html rather than DOCDIR.
Modified Paths: -------------- trunk/geany-plugins/geanygendoc/docs/Makefile.am trunk/geany-plugins/geanygendoc/src/ggd-plugin.c trunk/geany-plugins/wscript
Added Paths: ----------- trunk/geany-plugins/geanygendoc/docs/html4css1.css trunk/geany-plugins/geanygendoc/docs/manual.css trunk/geany-plugins/geanygendoc/docs/manual.html trunk/geany-plugins/geanygendoc/docs/manual.rst
Removed Paths: ------------- trunk/geany-plugins/geanygendoc/docs/help/Makefile.am trunk/geany-plugins/geanygendoc/docs/help/html4css1.css trunk/geany-plugins/geanygendoc/docs/help/manual.css trunk/geany-plugins/geanygendoc/docs/help/manual.html trunk/geany-plugins/geanygendoc/docs/help/manual.rst
Modified: trunk/geany-plugins/geanygendoc/docs/Makefile.am =================================================================== --- trunk/geany-plugins/geanygendoc/docs/Makefile.am 2010-05-26 17:43:39 UTC (rev 1410) +++ trunk/geany-plugins/geanygendoc/docs/Makefile.am 2010-05-27 15:16:40 UTC (rev 1411) @@ -1 +1,20 @@ -SUBDIRS = help +if ENABLE_GEANYGENDOC +include $(top_srcdir)/build/vars.docs.mk +plugin = geanygendoc +pluginhtmldocdir = $(plugindocdir)/html +endif ENABLE_GEANYGENDOC + +EXTRA_DIST = manual.rst \ + manual.css \ + html4css1.css \ + manual.html + +if ENABLE_GEANYGENDOC +plugindoc_DATA = manual.rst +pluginhtmldoc_DATA = manual.html + +if BUILD_RST +manual.html: manual.rst manual.css + $(AM_V_GEN) $(RST2HTML) -d --strict --stylesheet-path manual.css $< $@ +endif BUILD_RST +endif ENABLE_GEANYGENDOC
Deleted: trunk/geany-plugins/geanygendoc/docs/help/Makefile.am =================================================================== --- trunk/geany-plugins/geanygendoc/docs/help/Makefile.am 2010-05-26 17:43:39 UTC (rev 1410) +++ trunk/geany-plugins/geanygendoc/docs/help/Makefile.am 2010-05-27 15:16:40 UTC (rev 1411) @@ -1,19 +0,0 @@ -if ENABLE_GEANYGENDOC -include $(top_srcdir)/build/vars.docs.mk -plugin = geanygendoc -endif ENABLE_GEANYGENDOC - -EXTRA_DIST = manual.rst \ - manual.css \ - html4css1.css \ - manual.html - -if ENABLE_GEANYGENDOC -plugindoc_DATA = manual.rst \ - manual.html - -if BUILD_RST -manual.html: manual.rst manual.css - $(AM_V_GEN) $(RST2HTML) -d --strict --stylesheet-path manual.css $< $@ -endif BUILD_RST -endif ENABLE_GEANYGENDOC
Deleted: trunk/geany-plugins/geanygendoc/docs/help/html4css1.css =================================================================== --- trunk/geany-plugins/geanygendoc/docs/help/html4css1.css 2010-05-26 17:43:39 UTC (rev 1410) +++ trunk/geany-plugins/geanygendoc/docs/help/html4css1.css 2010-05-27 15:16:40 UTC (rev 1411) @@ -1,293 +0,0 @@ -/* -:Author: David Goodger (goodger@python.org) -:Id: $Id: html4css1.css 5951 2009-05-18 18:03:10Z milde $ -:Copyright: This stylesheet has been placed in the public domain. - -Default cascading style sheet for the HTML output of Docutils. - -See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to -customize this style sheet. -*/ - -/* used to remove borders from tables and images */ -.borderless, table.borderless td, table.borderless th { - border: 0 } - -table.borderless td, table.borderless th { - /* Override padding for "table.docutils td" with "! important". - The right padding separates the table cells. */ - padding: 0 0.5em 0 0 ! important } - -.first { - /* Override more specific margin styles with "! important". */ - margin-top: 0 ! important } - -.last, .with-subtitle { - margin-bottom: 0 ! important } - -.hidden { - display: none } - -a.toc-backref { - text-decoration: none ; - color: black } - -blockquote.epigraph { - margin: 2em 5em ; } - -dl.docutils dd { - margin-bottom: 0.5em } - -/* Uncomment (and remove this text!) to get bold-faced definition list terms -dl.docutils dt { - font-weight: bold } -*/ - -div.abstract { - margin: 2em 5em } - -div.abstract p.topic-title { - font-weight: bold ; - text-align: center } - -div.admonition, div.attention, div.caution, div.danger, div.error, -div.hint, div.important, div.note, div.tip, div.warning { - margin: 2em ; - border: medium outset ; - padding: 1em } - -div.admonition p.admonition-title, div.hint p.admonition-title, -div.important p.admonition-title, div.note p.admonition-title, -div.tip p.admonition-title { - font-weight: bold ; - font-family: sans-serif } - -div.attention p.admonition-title, div.caution p.admonition-title, -div.danger p.admonition-title, div.error p.admonition-title, -div.warning p.admonition-title { - color: red ; - font-weight: bold ; - font-family: sans-serif } - -/* Uncomment (and remove this text!) to get reduced vertical space in - compound paragraphs. -div.compound .compound-first, div.compound .compound-middle { - margin-bottom: 0.5em } - -div.compound .compound-last, div.compound .compound-middle { - margin-top: 0.5em } -*/ - -div.dedication { - margin: 2em 5em ; - text-align: center ; - font-style: italic } - -div.dedication p.topic-title { - font-weight: bold ; - font-style: normal } - -div.figure { - margin-left: 2em ; - margin-right: 2em } - -div.footer, div.header { - clear: both; - font-size: smaller } - -div.line-block { - display: block ; - margin-top: 1em ; - margin-bottom: 1em } - -div.line-block div.line-block { - margin-top: 0 ; - margin-bottom: 0 ; - margin-left: 1.5em } - -div.sidebar { - margin: 0 0 0.5em 1em ; - border: medium outset ; - padding: 1em ; - background-color: #ffffee ; - width: 40% ; - float: right ; - clear: right } - -div.sidebar p.rubric { - font-family: sans-serif ; - font-size: medium } - -div.system-messages { - margin: 5em } - -div.system-messages h1 { - color: red } - -div.system-message { - border: medium outset ; - padding: 1em } - -div.system-message p.system-message-title { - color: red ; - font-weight: bold } - -div.topic { - margin: 2em } - -h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, -h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { - margin-top: 0.4em } - -h1.title { - text-align: center } - -h2.subtitle { - text-align: center } - -hr.docutils { - width: 75% } - -img.align-left, .figure.align-left{ - clear: left ; - float: left ; - margin-right: 1em } - -img.align-right, .figure.align-right { - clear: right ; - float: right ; - margin-left: 1em } - -.align-left { - text-align: left } - -.align-center { - clear: both ; - text-align: center } - -.align-right { - text-align: right } - -/* reset inner alignment in figures */ -div.align-right { - text-align: left } - -/* div.align-center * { */ -/* text-align: left } */ - -ol.simple, ul.simple { - margin-bottom: 1em } - -ol.arabic { - list-style: decimal } - -ol.loweralpha { - list-style: lower-alpha } - -ol.upperalpha { - list-style: upper-alpha } - -ol.lowerroman { - list-style: lower-roman } - -ol.upperroman { - list-style: upper-roman } - -p.attribution { - text-align: right ; - margin-left: 50% } - -p.caption { - font-style: italic } - -p.credits { - font-style: italic ; - font-size: smaller } - -p.label { - white-space: nowrap } - -p.rubric { - font-weight: bold ; - font-size: larger ; - color: maroon ; - text-align: center } - -p.sidebar-title { - font-family: sans-serif ; - font-weight: bold ; - font-size: larger } - -p.sidebar-subtitle { - font-family: sans-serif ; - font-weight: bold } - -p.topic-title { - font-weight: bold } - -pre.address { - margin-bottom: 0 ; - margin-top: 0 ; - font: inherit } - -pre.literal-block, pre.doctest-block { - margin-left: 2em ; - margin-right: 2em } - -span.classifier { - font-family: sans-serif ; - font-style: oblique } - -span.classifier-delimiter { - font-family: sans-serif ; - font-weight: bold } - -span.interpreted { - font-family: sans-serif } - -span.option { - white-space: nowrap } - -span.pre { - white-space: pre } - -span.problematic { - color: red } - -span.section-subtitle { - /* font-size relative to parent (h1..h6 element) */ - font-size: 80% } - -table.citation { - border-left: solid 1px gray; - margin-left: 1px } - -table.docinfo { - margin: 2em 4em } - -table.docutils { - margin-top: 0.5em ; - margin-bottom: 0.5em } - -table.footnote { - border-left: solid 1px black; - margin-left: 1px } - -table.docutils td, table.docutils th, -table.docinfo td, table.docinfo th { - padding-left: 0.5em ; - padding-right: 0.5em ; - vertical-align: top } - -table.docutils th.field-name, table.docinfo th.docinfo-name { - font-weight: bold ; - text-align: left ; - white-space: nowrap ; - padding-left: 0 } - -h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, -h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { - font-size: 100% } - -ul.auto-toc { - list-style-type: none }
Deleted: trunk/geany-plugins/geanygendoc/docs/help/manual.css =================================================================== --- trunk/geany-plugins/geanygendoc/docs/help/manual.css 2010-05-26 17:43:39 UTC (rev 1410) +++ trunk/geany-plugins/geanygendoc/docs/help/manual.css 2010-05-27 15:16:40 UTC (rev 1411) @@ -1,68 +0,0 @@ -/* -: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; -}
Deleted: trunk/geany-plugins/geanygendoc/docs/help/manual.html =================================================================== --- trunk/geany-plugins/geanygendoc/docs/help/manual.html 2010-05-26 17:43:39 UTC (rev 1410) +++ trunk/geany-plugins/geanygendoc/docs/help/manual.html 2010-05-27 15:16:40 UTC (rev 1411) @@ -1,602 +0,0 @@ -<?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>
Deleted: trunk/geany-plugins/geanygendoc/docs/help/manual.rst =================================================================== --- trunk/geany-plugins/geanygendoc/docs/help/manual.rst 2010-05-26 17:43:39 UTC (rev 1410) +++ trunk/geany-plugins/geanygendoc/docs/help/manual.rst 2010-05-27 15:16:40 UTC (rev 1411) @@ -1,535 +0,0 @@ -======================= -GeanyGenDoc User Manual -======================= -------------------------------------------------- -A handy hand guide for the lazy documenter in you -------------------------------------------------- - - -Introduction -============ - -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. - - -.. contents:: - - -Design -====== - -GeanyGenDoc has an extensible design based on three points: file type, -documentation type and rules. - -`File type`_ - The file type determines which configuration applies to which document. For - example, the "c" file type corresponds to C source, and so on. - -`Documentation type`_ - 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 `Doxygen`_ - and `Gtk-Doc`_ documentation from C sources. She should then create two - documentation types in the C `file type configuration file`_, such as - "doxygen" and "gtkdoc". - -`Rule`_ - 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. - - -Syntax -====== - -Key-Value pairs ---------------- - -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.). - -The key-value syntax is as follows:: - - key = value - -where value is either a semicolon-ended single value:: - - value; - -or a brace-surrounded list of key-value pairs that use the same syntax again:: - - { - key1 = value1 - key2 = value2 - } - -Here a little example of the *syntax* (not any actual configuration example):: - - key1 = value1; - key2 = { - sub-key1 = sub-value1; - sub-key2 = { - sub-sub-key1 = sub-sub-value1; - } - } - - -Naming ------- - -Key-value pairs are often referred as *group* when they are meant to have -multiple values and as *setting* when they have a single value. - - -Comments --------- - -Is considered as comment (and therefore ignored) everything between a number -sign (``#``) and the following end of line, unless the ``#`` occurs as part of -another syntactic element (such as a string literal). - -A short example:: - - # This is a comment - key = value; # This is also a comment - string = "A string. # This isn't a comment but a string"; - - -Value types ------------ - -string - A string literal. String literals are surrounded by either single (``'``) or - double (``"``) quotes. - - Some special characters can be inserted in a string with an escape sequence: - - ``\t`` - A tabulation. - ``\n`` - A new line. - ``\r`` - A carriage return. - ``\`` - A backslash. - ``'`` - A single quote (escaping only needed in single-quotes surrounded strings). - ``"`` - A double quote (escaping only needed in double-quotes surrounded strings). - - Note that backslashes are used as the escaping character, which means that it - must be escaped to be treated as a simple backslash character. - - A simple example:: - - "This is a string with "special" characters.\nThis is another line!" - -boolean - A boolean. It can take one of the two symbolic values ``True`` and ``False``. - -enumeration - An enumeration. It consists of a named constant, generally in capital letters. - The possible values depend on the setting that use this type. - -flags - A logical OR of named constants. This is like enumerations but can combine - different values. - - The syntax is common for such types and uses the pipe (``|``) as - combination character. Considering the ``A``, ``B`` and ``C`` constants, a - valid value could be ``A | C``, which represents both ``A`` and ``C`` but - not ``B``. - -list - A list of values (often referred as array). - - -File types -========== - -The file type determines which configuration applies to which document. -*File type identifiers* are the lowercased name of the Geany's file type, for -example "c" or "python". - -Configuration for a particular file type goes in a file named -``file-type-identifier.conf`` in the ``filetypes`` sub-directory of a -`configuration directory`_. - -A file type configuration can contain two type of things: file-type-wide -settings and any number of `documentation types`_. - - -The ``settings`` group ----------------------- - -This group contains the file-type-wide settings. - -``match_function_arguments`` (string) - 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. - -``global_environment`` (string) - A description of a CTPL_ environment to add when parsing rule_'s templates. - - -The ``doctypes`` group ----------------------- - -This group contains a list of `documentation types`_. - - -Documentation types -=================== - -A documentation type is a named set of rules_ for a `file type`_, describing how -to generate a particular type of documentation (i.e. Doxygen_, `Gtk-Doc`_, -Valadoc_ or whatever). - -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). - - -Short example -------------- - -:: - - doxygen = { - struct.member = { - template = " /**< {cursor} */"; - position = AFTER; - } - struct.template = "/**\n * @brief: {cursor}\n * \n * \n */\n"; - } - - -Rules: the cool thing -===================== - -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. - -A rule is represented as a group of `settings`_ in a `documentation type`_. -The name of this group is the `type hierarchy`_ to which the settings applies. - - -Type hierarchy --------------- - -A type hierarchy is a hierarchy of the types that a symbol must have to match -this rule. - -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 ``class -> method``; and if the class is itself in a -namespace, the hierarchy would the look like ``namespace -> class -> method``, -and so on. - -For a rule to apply, its type hierarchy must match *the end* of the symbol -type hierarchy. For example a rule with the type hierarchy ``class`` will match -a symbol with the type hierarchy ``namespace -> class`` but not one with -``class -> method``. - -A type hierarchy uses dots (``.``) to separate types and build the hierarchy. -For example, the type hierarchy representing ``namespace -> class`` would be -written ``namespace.class``. - - -Known types -~~~~~~~~~~~ - -``class`` - A class. -``enum`` - An enumeration. -``enumval`` - An enumeration value. -``field`` - A field (of a class for example). -``function`` - A function. -``interface`` - An interface. -``member`` - A member (of a structure for example). -``method`` - A method. -``namespace`` - A namespace. -``package`` - A package. -``prototype`` - A prototype. -``struct`` - A structure. -``typedef`` - A type alias definition (*typedef* in C). -``union`` - An union. -``variable`` - A variable. -``extern`` - `???` -``define`` - A definition (like the *define* C preprocessor macro). -``macro`` - A macro. -``file`` - A file (will never match). - - -Rule settings -------------- - -``template`` (string) - A CTPL_ template that can include references to the following predefined - variables in addition to the file-type-wide and the global environment: - - ``argument_list`` (string list) - A list of the arguments of the currently documented symbol. - - ``returns`` (boolean) - Indicates whether the currently documented symbol returns a value - (makes sense only for symbols that may return a value). - - ``children`` (string list) - A list of the current symbol's first-level children. This is only set if - the rule's setting ``children`` is set to ``MERGE``. - - **[...]** - - ``cursor`` (special, described below) - 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. - -``position`` (enumeration) - The position where the documentation should be inserted. Possible values are: - - ``BEFORE`` [default]_ - Inserts the documentation just before the symbol. - - ``AFTER`` - Inserts the documentation just after the symbol (currently quite limited, it - inserts the documentation at the end of the symbol's first line). - - ``CURSOR`` - Inserts the documentation at the current cursor position. - -``policy`` (enumeration) - How the symbol is documented. Possible values are: - - ``KEEP`` [default]_ - The symbol documents itself. - - ``FORWARD`` - Forward the documentation request to the parent. This is useful for symbols - that are documented by their parent, such as `Gtk-Doc`_'s enumerations. - -``children`` (enumeration) - How the symbol's children can be used in the template. Possible values are: - - ``SPLIT`` [default]_ - The symbol's children are provided as per-type lists. - - ``MERGE`` - The symbol's children are provided as a single list named ``children``. - -``matches`` (flags) - List of the children types that should be provided. Only useful if the - ``children`` setting is set to ``MERGE``. - Defaults to all. - **FIXME: check the exactitude of this description** - -``auto_doc_children`` (boolean) - Whether to also document symbol's children (according to their own rules). - - -User interface in Geany -======================= - -Menus ------ - -GeanyGenDoc adds an item named `Insert Documentation Comment` in the editor's -pop-up under the `Insert Comments` sub-menu; and a menu named -`Documentation Generator` into the `Tools` menu. - -Editor's pop-up menu -~~~~~~~~~~~~~~~~~~~~ - -The item `Editor's pop-up → Insert Comments → Insert Documentation Comment` -generates documentation for the current symbol. It has a keyboard shortcut -that can be configured through Geany's keybinding configuration system, under -`GeanyGenDoc → Insert Documentation Comment`. - -Tools menu -~~~~~~~~~~ - -The `Documentation Generator` menu under `Tools` contains the following items: - -`Document Current Symbol` - This generates documentation for the current symbol. It is equivalent to the - item `Insert Documentation Comment` that can be found in the editor's pop-up - menu. - -`Document All Symbols` - This generates documentation for all symbols in the document. This is - equivalent to manually requesting documentation generation for each symbol in - the document. - -`Reload Configuration Files` - This force reloading of all the `file type`_ 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. - -`Edit Current Language Configuration` - 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 `configuration - directory`_ transparently. - -`Open Manual` - Opens this manual in a browser. - - -Preferences dialog ------------------- - -The preferences dialog, than can either be opened through `Edit → -Plugin Preferences` or with the `Preferences` button in the plugin manager, -allows to modify the following preferences: - -`General` - `Save file before generating documentation` - 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. - - `Indent inserted documentation` - Chooses whether the inserted documentation should be indented to fit the - indentation at the insertion position. - -`Documentation type` - This list allows you to choose the documentation type to use with each file - type. The special language `All` on top of the list is used to choose the - default documentation type, used for all languages that haven't one set. - -`Global environment` - Global environment overrides and additions. This is an environment that will - be merged with the `file type`_-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 `Since` tag, define the `Doxygen`_ 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. - - -Miscellaneous -============= - -Configuration directories -------------------------- - -Configuration directories hold GeanyGenDoc's configuration. They are the -following: - -* - The user-specific configuration directory, containing the user-defined - settings is ``$GEANY_USER_CONFIG/plugins/geanygendoc/``. - ``$GEANY_USER_CONFIG`` is generally ``~/.config/geany/`` on UNIX systems. -* - The system-wide configuration directory containing the default and - pre-installed configuration is ``$GEANY_SYS_CONFIG/plugins/geanygendoc/``. - ``$GEANY_SYS_CONFIG`` is generally ``/usr/share/geany/`` or - ``/usr/local/share/geany`` on UNIX systems. - -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. - - -Appendix -======== - -Configuration syntax summary ----------------------------- - -:: - - 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? ) - - -.. Content end, begin references - -.. External links -.. -.. _Doxygen: http://www.doxygen.org -.. _Gtk-Doc: http://www.gtk.org/gtk-doc/ -.. _Valadoc: http://www.valadoc.org/ -.. _CTPL: http://ctpl.tuxfamily.org/ - -.. Internal links -.. -.. _file type: `File types`_ -.. _file type configuration file: `File types`_ -.. _documentation type: `Documentation types`_ -.. _rule: `Rules: the cool thing`_ -.. _rules: `Rules: the cool thing`_ -.. _settings: `Rule settings`_ -.. _configuration directory: `Configuration directories`_ - -------------------- - -.. [default] This is the default value of the setting
Copied: trunk/geany-plugins/geanygendoc/docs/html4css1.css (from rev 1409, trunk/geany-plugins/geanygendoc/docs/help/html4css1.css) =================================================================== --- trunk/geany-plugins/geanygendoc/docs/html4css1.css (rev 0) +++ trunk/geany-plugins/geanygendoc/docs/html4css1.css 2010-05-27 15:16:40 UTC (rev 1411) @@ -0,0 +1,293 @@ +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 5951 2009-05-18 18:03:10Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left{ + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: left } + +/* div.align-center * { */ +/* text-align: left } */ + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none }
Copied: trunk/geany-plugins/geanygendoc/docs/manual.css (from rev 1409, trunk/geany-plugins/geanygendoc/docs/help/manual.css) =================================================================== --- trunk/geany-plugins/geanygendoc/docs/manual.css (rev 0) +++ trunk/geany-plugins/geanygendoc/docs/manual.css 2010-05-27 15:16:40 UTC (rev 1411) @@ -0,0 +1,68 @@ +/* +: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; +}
Copied: trunk/geany-plugins/geanygendoc/docs/manual.html (from rev 1409, trunk/geany-plugins/geanygendoc/docs/help/manual.html) =================================================================== --- trunk/geany-plugins/geanygendoc/docs/manual.html (rev 0) +++ trunk/geany-plugins/geanygendoc/docs/manual.html 2010-05-27 15:16:40 UTC (rev 1411) @@ -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>
Copied: trunk/geany-plugins/geanygendoc/docs/manual.rst (from rev 1409, trunk/geany-plugins/geanygendoc/docs/help/manual.rst) =================================================================== --- trunk/geany-plugins/geanygendoc/docs/manual.rst (rev 0) +++ trunk/geany-plugins/geanygendoc/docs/manual.rst 2010-05-27 15:16:40 UTC (rev 1411) @@ -0,0 +1,535 @@ +======================= +GeanyGenDoc User Manual +======================= +------------------------------------------------- +A handy hand guide for the lazy documenter in you +------------------------------------------------- + + +Introduction +============ + +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. + + +.. contents:: + + +Design +====== + +GeanyGenDoc has an extensible design based on three points: file type, +documentation type and rules. + +`File type`_ + The file type determines which configuration applies to which document. For + example, the "c" file type corresponds to C source, and so on. + +`Documentation type`_ + 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 `Doxygen`_ + and `Gtk-Doc`_ documentation from C sources. She should then create two + documentation types in the C `file type configuration file`_, such as + "doxygen" and "gtkdoc". + +`Rule`_ + 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. + + +Syntax +====== + +Key-Value pairs +--------------- + +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.). + +The key-value syntax is as follows:: + + key = value + +where value is either a semicolon-ended single value:: + + value; + +or a brace-surrounded list of key-value pairs that use the same syntax again:: + + { + key1 = value1 + key2 = value2 + } + +Here a little example of the *syntax* (not any actual configuration example):: + + key1 = value1; + key2 = { + sub-key1 = sub-value1; + sub-key2 = { + sub-sub-key1 = sub-sub-value1; + } + } + + +Naming +------ + +Key-value pairs are often referred as *group* when they are meant to have +multiple values and as *setting* when they have a single value. + + +Comments +-------- + +Is considered as comment (and therefore ignored) everything between a number +sign (``#``) and the following end of line, unless the ``#`` occurs as part of +another syntactic element (such as a string literal). + +A short example:: + + # This is a comment + key = value; # This is also a comment + string = "A string. # This isn't a comment but a string"; + + +Value types +----------- + +string + A string literal. String literals are surrounded by either single (``'``) or + double (``"``) quotes. + + Some special characters can be inserted in a string with an escape sequence: + + ``\t`` + A tabulation. + ``\n`` + A new line. + ``\r`` + A carriage return. + ``\`` + A backslash. + ``'`` + A single quote (escaping only needed in single-quotes surrounded strings). + ``"`` + A double quote (escaping only needed in double-quotes surrounded strings). +
@@ Diff output truncated at 100000 characters. @@
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.