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 IR-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 semantic graph (ASG). 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 ASG 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 ASG, 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 ASG 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 the most important 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.

--cfilter

Specify a comment filter (See the section called “Comment Filters”).

--translate

Translate comments to doc-strings, using the given markup specifier (See the section called “Comment Translators”).

--sxr-prefix

Specify the directory under which to store SXR info for the parsed source files. This causes parsers to generate SXR info, the linker to generate an sxr Symbol Table, and for the HTML formatter this causes Source and XRef views to be generated.

--probe

This is useful in conjunction with the -p Cpp option to probe for system header search paths and system macro definitions. (See the section called “Emulating A Compiler”).