1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The synopsis executable</title><link rel="stylesheet" href="synopsis.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="Synopsis Tutorial"><link rel="up" href="using.html" title="Chapter2.Using the synopsis tool"><link rel="previous" href="using.html" title="Chapter2.Using the synopsis tool"><link rel="next" href="parsing.html" title="Parsing source code"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">The synopsis executable</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using.html">Prev</a></td><th width="60%" align="center">Chapter2.Using the synopsis tool</th><td width="20%" align="right"><a accesskey="n" href="parsing.html">Next</a></td></tr></table></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="executable"></a>The synopsis executable</h2></div></div><div></div></div><p>The synopsis executable is a little convenience frontend
to the larger Synopsis framework consisting of AST related
types as well as processor classes.</p><p>While the full power of synopsis is available through
scripting (see <a href="scripting.html" title="Chapter3.Scripting and extending synopsis">Chapter3, <i>Scripting and extending synopsis</i></a>), it is possible
to quickly generate simple documentation by means of an
easy-to-use executable, that is nothing more but a little
script with some extra command line argument parsing.</p><p>This tool has three processor types it can call:</p><div class="variablelist"><dl><dt><span class="term">Parser</span></dt><dd><p>A processor that will parse source code into an
internal abstract syntax tree (AST). Various Parsers
have a variety of parameters to control how exactly
they do that.</p></dd><dt><span class="term">Linker</span></dt><dd><p>A processor that will remove duplicate symbols,
forward declarations, and apply any number of AST
manipulations you want. The user typically specifies
what sub-processors to load to run from the linker.</p></dd><dt><span class="term">Formatter</span></dt><dd><p>A processor that generates some form of formatted
output from an existing AST, typically html, docbook xml,
or class graphs.</p></dd></dl></div><p>You can run synopsis with a single processor, for example
to parse a C++ file <tt class="filename">source.hh</tt> and store
the AST into a file <tt class="filename">source.syn</tt>, or you can
combine it directly with linker and or formatter to generate
the output you want in a single call.</p><p>While the document generation in a single call is convenient,
for larger projects it is much more sensible to integrate the
document generation into existing build systems and let the build
system itself manage the dependencies between the intermediate files
and the source files.</p><p>For example, a typical Makefile fragment that contains the rules
to generate documentation out of multiple source files may look like
this:</p><pre class="programlisting">
hdr := $(wildcard *.h)
syn := $(patsubst %.h, %.syn, $(hdr))
html: $(syn)
synopsis -f HTML -o $@ $<
%.syn: %.h
synopsis -p Cxx -I../include -o $@ $<
</pre><p>Here is a listing of all available options:</p><div class="variablelist"><dl><dt><span class="term">-h, </span><span class="term">--help, </span></dt><dd><p>print out help message</p></dd><dt><span class="term">-V, </span><span class="term">--version, </span></dt><dd><p>print out version info and exit</p></dd><dt><span class="term">-v, </span><span class="term">--verbose, </span></dt><dd><p>operate verbosely</p></dd><dt><span class="term">-d, </span><span class="term">--debug, </span></dt><dd><p>operate in debug mode</p></dd><dt><span class="term">-o, </span><span class="term">--output, </span></dt><dd><p>output file / directory</p></dd><dt><span class="term">-p, </span><span class="term">--parser, </span></dt><dd><p>select a parser</p></dd><dt><span class="term">-l, </span><span class="term">--link, </span></dt><dd><p>link</p></dd><dt><span class="term">-f, </span><span class="term">--formatter, </span></dt><dd><p>select a formatter</p></dd><dt><span class="term">-I</span></dt><dd><p>set an include search path</p></dd><dt><span class="term">-D</span></dt><dd><p>specify a macro for the parser</p></dd><dt><span class="term">-W</span></dt><dd><p>pass down additional arguments to a processor.
For example '-Wp,-I.' sends the '-I.' option to the
parser.</p></dd></dl></div></div><div class="navfooter"><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using.html">Prev</a></td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"><a accesskey="n" href="parsing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter2.Using the synopsis tool</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">Parsing source code</td></tr></table></div></body></html>
|
