Synopsis Formatters

The ASCII formatter attempts to output the AST in a format that is suitable for recompilation, or close to. You can use this to check that your code and comments are getting parsed correctly, or out of interest to see the structure of the AST after Linking. Like the DUMP formatter, this is mostly of use for debugging.

The Dia formatter generates a Dia file with the filename specified in the -o option. This file contains all classes in the AST, with inheritance relationships linked as generalizations. At your option, the classes may include operations and/or attributes. Unfortunately, it is hard to predict the size of the graph objects and automatically lay them out, so the process of organising the diagram is left to the user. When you load the Dia file all the classes will be overlaid on one another and you may have to spend some time rearranging them. In future we may utilise constraint-solvers to arrange the objects - if you would like to help in this effort please get in touch.

Dia Options

The DUMP formatter is useful only for debugging. It takes the AST and dumps it to screen in a nested attribute-oriented format. Several optimisations are made eg. for lists of strings which are displayed in Scoped::Name format. It also dumps the type-dictionary, and is useful for seeing what is included and excluded in the main-stripping process in the parser, and the Linking process. You may also use it to see the structure of types formed by constructs such as "const vector<int,char*>" which is quite complex.

This formatter has no options, but I recommend that you pipe its output into "less -r". Names are displayed in bold, and the output is *very* verbose.

This is the most highly developed formatter, for obvious reasons. It is designed in a modular fashion, although for now there are no options to manipulate that apart from the comment formatters. In future it is planned that the user can add custom file layouts, templates, comment formatters, Table Of Contents, linking schemes, and other such niceties.

The -o option specifies for this formatter an output directory, into which it places the generated files. Support is provided to link to a stylesheet via the -s option, and copying an existing stylesheet into the new directory via the -S option. The file layout is as follows: There is an index page that contains the familiar (to Javadoc users anyway) three-frame layout. The top-left frame lists modules or files. The left frame contains an index of the selected module (aka namespace for C++) or file. The main frame contains summaries and details of the currently selected module/namespace or interface/class.

The contents of the selected scope (module/namespace, or interface/class) is divided into declarations of common type, such as Operations, Variables, etc. Each declaration is displayed as a summary, and those with detailed comments are displayed at the bottom of the page with their detailed comment. The process of separating summaries and details is performed by the "summary" comment formatter. Summarized declarations that have a detailed section are displayed with their name as a link. Any other name is displayed as a label such that it may be referred to via a html #link.

Since there are several different commenting styles, and several different tagging styles, Synopsis' HTML formatter provides a set of comment formatters that the user may select to format thier comments. These are specified by multiple -C options to the formatter:

• ssd - Slash-Slash-Dot. This formatter will filter and strip so that only comments begginning with "//." are parsed as documentation comments. This formatter should be the first in the list.
• java - Java-style comments. This formatter will filter and strip so that only comments of the style:

    /**
     * This is a Java-style comment.
     */
  	      

  are parsed as documentation comments. This formatter should be first in the list. Only one of "ssd" and "java" should be used. You may also use neither if, for example in the case of the Python Parser, your comments come with no comment-markers.
• summary - Summarizer. This formatter will look for comments with a "first sentence". This first sentence is copied into the "summary" section of a comment and displayed with the declaration in the "summary" section of the page. The rest of the comment, including the first sentence, is displayed in the "details" section. If it is unable to find a "first sentence", for example if your comment is one line without a final period, the whole comment is made the "summary" and the detail is omitted. The "first sentence" is defined as the first set of characters terminated by a period followed either by the end of the string or whitespace (space, newline, tab). This is to allow you to use periods in the first sentence such as "Set the name using AST.Name".
• javadoc - Javadoc @tag formatter. This formatter looks for Javadoc-style @tags and attempts to format them in a similar manner. Currently it only supports @see tags, but support for the others is intended for future versions. For an example see demo/C++/employee.cc and the "make employee_html" target in that directory.
• section - Experimental section formatter. This formatter was originally a test for the multiple comment formatter feature, but is quite useful anyway. It translates empty lines into paragraph breaks, and in the future may expand to allow other formatting constructs similar to "zwiki"'s "structured text" concept.

HTML Options

synopsis -f HTML -Wf,-s,style.css,-S,../../style.css,-c,ssd,-c,summary,-c,javadoc -o Manual all.syn

This is the original HTML formatter included with version 0.1. It outputs the whole AST to one file, specified via the -o option. It also allows stylesheet support.