Appendix A. Description of program options for the synopsis executable

Appendix A. Description of program options for the synopsis executable

The synopsis executable is a little convenience frontend to the larger Synopsis framework consisting of AST related types as well as processor classes.

While the full power of synopsis is available through scripting (see Chapter 3, Scripting and extending synopsis), 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.

This tool has three processor types it can call:

Parser

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.

Linker

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.

Formatter

A processor that generates some form of formatted output from an existing AST, typically html, docbook xml, or class graphs. Other formatters exist to assist debugging, such as a List formatter that prints specific aspects of the IR to stdout, or a Dump formatter that writes the IR to an xml file, useful for unit testing.

You can run synopsis with a single processor, for example to parse a C++ file source.hh and store the AST into a file source.syn, or you can combine it directly with linker and or formatter to generate the output you want in a single call.

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.

For example, a typical Makefile fragment that contains the rules to generate documentation out of multiple source files may look like this:

      hdr := $(wildcard *.h)
      syn := $(patsubst %.h, %.syn, $(hdr))

      html: $(syn)
          synopsis -f HTML -o $@ $<

      %.syn: %.h
          synopsis -p Cxx -I../include -o $@ $<
    

Here is a listing of all available options:

-h, --help

print out help message

-V, --version

print out version info and exit

-v, --verbose

operate verbosely

-d, --debug

operate in debug mode

-o, --output

output file / directory

-p, --parser

select a parser

-l, --link

link

-f, --formatter

select a formatter

-I

set an include search path

-D

specify a macro for the parser

-W

pass down additional arguments to a processor. For example '-Wp,-I.' sends the '-I.' option to the parser.