[Synopsis-cvs] Synopsis/Synopsis/docs/Manual synopsis.xml,1.13,1.14
Stephen Davies chalky at users.sourceforge.netTue Apr 8 04:45:02 UTC 2003
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Update of /cvsroot/synopsis/Synopsis/docs/Manual
In directory sc8-pr-cvs1:/tmp/cvs-serv22961
Modified Files:
synopsis.xml
Log Message:
Lots more info about the Project file format.
Index: synopsis.xml
===================================================================
RCS file: /cvsroot/synopsis/Synopsis/docs/Manual/synopsis.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -p -d -r1.13 -r1.14
--- synopsis.xml 16 Mar 2003 00:26:27 -0000 1.13
+++ synopsis.xml 8 Apr 2003 11:43:59 -0000 1.14
@@ -220,7 +220,7 @@ void func()
<para>The comment processors are all written in Python, and you can
specify your own in a config file to perform custom processing, or to
- deal with unusual comment styles. </para>
+ deal with unusual comment styles.</para>
<para>See the chapter on the Linker for more information on this.</para>
</section>
@@ -743,15 +743,19 @@ class struct:
setattr(self, key, value)
class Project:
+ # Instantiate an object:
+ my_object = struct(name = "foo", magic_number = 42)
+
+ # And another one, this time formatted nicely:
some_object = struct(
name = "hi",
some_list = [1, 2, 3],
+ # Here an attribute is a nested object:
nested_object = struct(
type = "foo",
fred = "baz"
)
- )
- </programlisting>
+ )</programlisting>
</example>
<para>The new Project structure defines not only configuration for the
@@ -795,9 +799,9 @@ class Project:
<para>Can take as input any number of ASTs (from eg: ParserAction,
LinkerAction). Outputs the same ASTs, but stores the ASTs on disk
so that they don't need to be regenerated each time if the
- timestamps have not changed. There is a limitation in that the
- timestamps are only checked on the input source files themselves,
- not on their dependencies. This will be fixed in a later version.</para>
+ timestamps have not changed. For C++ files all dependencies
+ (#included files) will have their timestamps checked. For other
+ languages only the actual source files will be checked.</para>
</listitem>
</varlistentry>
@@ -833,12 +837,69 @@ class Project:
Linker and Formatter objects are described later in this manual, and are
the same as the old config format just with a different syntax.</para>
- <para>As mentioned, the main element of the config file is the
- "class Project". It has a number of attributes, including a
- string name, verbose flag, a list of actions, a list of channels, and a
- default formatter to use if none is specified. The channels are the
- connections between actions, and are simply tuple pairs of names of
- actions.</para>
+ <section>
+ <title>Project class</title>
+
+ <para><programlisting>class Project:
+ # attributes go here. Must be indented!
+ name = 'project name' # string - name of project
+ verbose = 0 # boolean
+ data_dir = './' # string - path (currently unused)
+ default_formatter = 'name' # string - the name of the default formatter to
+ # use if none is specified on the command line.
+ channels = [ <list of channels> ]
+ actions = [ <list of actions> ]</programlisting>The main element
+ of the config file is the "class Project". It has a number of
+ attributes, including a string name, verbose flag, a list of actions,
+ a list of channels, and a default formatter to use if none is
+ specified. The channels are the connections between actions, and are
+ simply tuple pairs of names of actions, e.g.:<programlisting> channels = [
+ ('C++ Parser', 'File Cacher'),
+ ('File Cacher', 'Linker')
+ ]</programlisting></para>
+
+ <para>Be careful that the action names in the channels list match the
+ names of the actual Actions in the actions list.</para>
+ </section>
+
+ <section>
+ <title>Action object</title>
+
+ <para>An action object, part of the list of actions in Project, is a
+ list of attributes (not a struct!). The first 4 attributes are always
+ the same, but different Actions have different uses for the remaining
+ attributes (remember, a list has variable length). The following
+ example shows all action types:<programlisting> actions = [
+ # string type, X/Y coords, string name, extra attributes...
+ ['SourceAction', 100, 100, 'Boost Sources', [ <list of SourceAction Rules> ] ],
+ ['ParserAction', 200, 100, 'C++ Parser', struct(key=val, key=val, ...) ],
+ ['CacherAction', 300, 100, 'File Cacher', 'directory' or None, 'file' or None ],
+ ['LinkerAction', 400, 100, 'Linker', struct(key=val, key=val, ...) ],
+ ['FormatAction', 500, 100, 'HTML Formatter', struct(key=val, key=val, ...) ]
+ ]</programlisting></para>
+
+ <para>As you can see, all types use the same format for the first four
+ attributes. The first is the type of action. The 2nd and 3rd are the X
+ and Y coordinates to use to display the action in the GUI. The 4th is
+ the name of the Action.</para>
+
+ <para>For SourceActions the 5th attribute is a list of SourceAction
+ Rules (see the next section).</para>
+
+ <para>For CacherActions the 5th and 6th attributes are directory name
+ and file name respectively. One and only one of these must be set (the
+ other must be None). If directory is set, then the inputs to the
+ action will be cached in the given directory and the outputs will be
+ the same as the inputs. If the file is set, then the action will have
+ no inputs, and one output which is loaded from the given file. Note
+ that this second mode of operation is not really caching but more like
+ loading, and can be used to load an AST from a file which you
+ don't have or want to use source code for.</para>
+
+ <para>For all other Action types the 5th attribute is a Config object.
+ For information on these see the documentation for the relevant
+ chapters of this manual (Parsers, Linker and Formatters).</para>
+ </section>
<section id="sourceaction-rules">
<title>SourceAction Rules</title>
@@ -933,6 +994,39 @@ class Project:
</listitem>
</varlistentry>
</variablelist>
+
+ <para>All rules are processed in the order that they appear in the
+ list. The effect of a rule is to add remove files to/from a list.
+ Therefore to explicitly exclude a file, the exclude rule should be at
+ the end.</para>
+
+ <para>Note that this is the opposite to permission type rules you
+ might be used to, since in this case we don't know what files
+ there are until a rule is processed. With permissions you know what
+ user/file you are checking permissions for so it's usually the
+ first matching rule which is used - hence exclusions are usually
+ placed first for permissions.</para>
+
+ <para>Another special case is when you are using the
+ 'multiple_files' feature of the C++ parser - in this case the
+ first rule must be a Simple rule with the main filename (e.g.:
+ Python.h). This is documented at the end of the C++ Parser section.</para>
+ </section>
+
+ <section>
+ <title>Command Line Usage</title>
+
+ <para>To use the project file and generate output for the default
+ formatter (specified in the config), use a command line like so:<programlisting>$ synopsis -P project.synopsis</programlisting></para>
+
+ <para>You can specify a formatter to use other than the default
+ formatter like so:<programlisting>$ synopsis -P project.synopsis -Wc,formatter=MyFormatter</programlisting></para>
+
+ <para>Synopsis will ensure that all Actions connected to the formatter
+ are also executed.</para>
+
+ <para>See the Boost demo for an example of how to use the project file
+ format.</para>
</section>
</section>
@@ -954,8 +1048,6 @@ class Project:
<section>
<title>C++ Parser</title>
- <para>most advanced. SXR. XREF. UCPP, OCC</para>
-
<para>The C++ parser reads C++ source code and generates an AST. It is
the most advanced Synopsis parser, using the following components:<itemizedlist><listitem><para>A
modified version of UCPP by Thomas Pornin. The modifications are to
@@ -1832,10 +1924,6 @@ class HTML (Base.Formatter.HTML):
can change this text using the "short_title" option of the
ModuleListing subobject.</para>
- <para>XXX There are two types of tree you can use: a simple HTML tree,
- or one that uses DHTML to open/close individual nodes, with little
- graphics for the buttons.</para>
-
<section>
<title>Options</title>
@@ -2883,4 +2971,4 @@ htmlPageClass = XRefPages</programlistin
<para>The best way to figure this out is to study the existing Pages.</para>
</section>
</chapter>
-</book>
+</book>
\ No newline at end of file
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the Synopsis-changes mailing list