[Synopsis-changes] Synopsis/Synopsis/doc/Tutorial Tutorial.xml,1.5,1.6 html.xsl,1.5,1.6 synopsis.css,1.3,1.4
Stefan Seefeld stefan at synopsis.fresco.orgSat Dec 6 05:36:25 UTC 2003
- Previous message: [Synopsis-changes] Synopsis/Synopsis/Synopsis/dist/command build_doc.py,1.8,1.9
- Next message: [Synopsis-changes] Synopsis/Synopsis/demo html.css,1.16,1.17
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Update of /cvs/synopsis/Synopsis/doc/Tutorial
In directory frida:/tmp/cvs-serv6962/doc/Tutorial
Modified Files:
Tutorial.xml html.xsl synopsis.css
Log Message:
more work on tutorial
Index: Tutorial.xml
===================================================================
RCS file: /cvs/synopsis/Synopsis/doc/Tutorial/Tutorial.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -p -d -r1.5 -r1.6
--- Tutorial.xml 6 Dec 2003 04:06:16 -0000 1.5
+++ Tutorial.xml 6 Dec 2003 05:36:23 -0000 1.6
@@ -47,14 +47,155 @@
<chapter>
<title>Using the synopsis tool</title>
-
+ <para>In this section we are going to explore the possibilities
+ to generate documentation from source code. We will demonstrate
+ how to use synopsis standalone as well as in conjunction with
+ existing build systems. Further, we will see how to adapt
+ synopsis to your coding and commenting style, as well as how
+ to generate the output in a format and style that fulfills
+ your needs.</para>
<section>
<title>The synopsis executable</title>
+ <para>The synopsis executable is a little convenience frontend
+ to the larger Synopsis framework consisting of AST related
+ types as well as processor classes.</para>
+ <para>While the full power of synopsis is available through
+ scripting (see <xref linkend="scripting" />), 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.</para>
+ <para>This tool has three processor types it can call:</para>
+ <variablelist>
+ <varlistentry>
+ <term>Parser</term>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Linker</term>
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Formatter</term>
+ <listitem>
+ <para>A processor that generates some form of formatted
+ output from an existing AST, typically html, docbook xml,
+ or class graphs.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <!-- Talk about the simplest frontend, the
- synopsis executable: basic usage, options, etc. -->
+ <para>You can run synopsis with a single processor, for example
+ to parse a C++ file <filename>source.hh</filename> and store
+ the AST into a file <filename>source.syn</filename>, or you can
+ combine it directly with linker and or formatter to generate
+ the output you want in a single call.</para>
+ <para>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.</para>
+ <para>For example, a typical Makefile fragment that contains the rules
+ to generate documentation out of multiple source files may look like
+ this:</para>
+ <programlisting>
+ hdr := $(wildcard *.h)
+ syn := $(patsubst %.h, %.syn, $(hdr))
- <para></para>
+ html: $(syn)
+ synopsis -f HTML -o $@ $<
+
+ %.syn: %.h
+ synopsis -p Cxx -I../include -o $@ $<
+ </programlisting>
+ <para>Here is a listing of all available options:</para>
+ <variablelist>
+ <varlistentry>
+ <term>-h</term>
+ <term>--help</term>
+ <listitem>
+ <para>print out help message</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-V</term>
+ <term>--version</term>
+ <listitem>
+ <para>print out version info and exit</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-v</term>
+ <term>--verbose</term>
+ <listitem>
+ <para>operate verbosely</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-d</term>
+ <term>--debug</term>
+ <listitem>
+ <para>operate in debug mode</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-o</term>
+ <term>--output</term>
+ <listitem>
+ <para>output file / directory</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-p</term>
+ <term>--parser</term>
+ <listitem>
+ <para>select a parser</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-l</term>
+ <term>--link</term>
+ <listitem>
+ <para>link</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-f</term>
+ <term>--formatter</term>
+ <listitem>
+ <para>select a formatter</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-I</term>
+ <listitem>
+ <para>set an include search path</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-D</term>
+ <listitem>
+ <para>specify a macro for the parser</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>-W</term>
+ <listitem>
+ <para>pass down additional arguments to a processor.
+ For example '-Wp,-I.' sends the '-I.' option to the
+ parser.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
<section>
@@ -67,14 +208,13 @@
<title>Using comments for documentation</title>
<para>
- <programlisting>
- <xi:include href="examples/example1/Shape.h" parse="text"/>
+ <programlisting><xi:include href="examples/example1/Shape.h" parse="text"/>
</programlisting>
</para>
</section>
</chapter>
- <chapter>
+ <chapter id="scripting">
<title>Scripting and extending synopsis</title>
<!-- When the synopsis executable isn't
Index: html.xsl
===================================================================
RCS file: /cvs/synopsis/Synopsis/doc/Tutorial/html.xsl,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -p -d -r1.5 -r1.6
--- html.xsl 2 Dec 2003 05:51:03 -0000 1.5
+++ html.xsl 6 Dec 2003 05:36:23 -0000 1.6
@@ -11,5 +11,6 @@
<xsl:param name="use.id.as.filename" select="1"/>
<xsl:param name="chunk.first.sections" select="1"/>
<xsl:param name="use.svg" select="0"/>
-
+<xsl:param name="header.rule" select="0"/>
+<xsl:param name="footer.rule" select="0"/>
</xsl:stylesheet>
Index: synopsis.css
===================================================================
RCS file: /cvs/synopsis/Synopsis/doc/Tutorial/synopsis.css,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -p -d -r1.3 -r1.4
--- synopsis.css 27 Nov 2003 06:00:36 -0000 1.3
+++ synopsis.css 6 Dec 2003 05:36:23 -0000 1.4
@@ -8,6 +8,22 @@ body
:visited { color: #770000; text-decoration: none;}
:active { color: #ff0000; text-decoration: none;}
+div.navheader
+{
+ border-bottom: solid;
+ border-color: #aaaaaa;
+ border-width: 1px;
+ padding: 10px;
+}
+
+div.navfooter
+{
+ border-top: solid;
+ border-color: #aaaaaa;
+ border-width: 1px;
+ padding: 10px;
+}
+
div.page-heading
{
position:float;
- Previous message: [Synopsis-changes] Synopsis/Synopsis/Synopsis/dist/command build_doc.py,1.8,1.9
- Next message: [Synopsis-changes] Synopsis/Synopsis/demo html.css,1.16,1.17
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the Synopsis-changes mailing list