jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update documentation and add margin-left.patch file for htmldoc

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@7117 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
John Lenz 2005-03-30 05:55:46 +00:00
commit df8516b782
5 changed files with 348 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

36
Doc/Manual/CSharp.html
View file

@ -8,12 +8,24 @@
<H1><a name="CSharp"></a>16 SWIG and C#</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#csharp_introduction">Introduction</a>
<li><a href="#csharp_differences_java">Differences to the Java module</a>
<li><a href="#csharp_exceptions">C# Exceptions</a>
<ul>
<li><a href="#csharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="#csharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="#csharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="#csharp_custom_application_exception">Custom C# ApplicationException example</a>
</ul>
</ul>
</div>
<!-- INDEX -->
<H2><a name="csharp_introduction"></a>Introduction</H2>
<H2><a name="csharp_introduction"></a>16.1 Introduction</H2>
<p>
The purpose of the C# module is to offer an automated way of accessing existing C/C++ code from .NET languages.
@ -26,7 +38,9 @@ Swig C# works equally well on non-Microsoft operating systems such as Linux, Sol
<a href="http://www.mono-project.com/">Mono</a> and <a href="http://www.dotgnu.org/pnet.html">Portable.NET</a>.
</p>
<H2><a name="csharp_differences_java"></a>Differences to the Java module</H2>
<H2><a name="csharp_differences_java"></a>16.2 Differences to the Java module</H2>
<p>
The C# module is very similar to the Java module, so until some more complete documentation has been written,
please use the <a href="Java.html#Java">Java documentation</a> as a guide to using SWIG with C#.
@ -170,7 +184,9 @@ Windows users can also get the examples working using a
<a href="http://www.cygwin.com">Cygwin</a> or <a href="http://www.mingw.org">MinGW</a> environment for automatic configuration of the example makefiles.
Any one of the three C# compilers (Portable.NET, Mono or Microsoft) can be detected from within a Cygwin or Mingw environment if installed in your path.
<H2><a name="csharp_exceptions"></a>C# Exceptions</H2>
<H2><a name="csharp_exceptions"></a>16.3 C# Exceptions</H2>
<p>
It is possible to throw a C# Exception from C/C++ code.
SWIG already provides the framework for throwing C# exceptions if it is able to detect that a C++ exception could be thrown.
@ -264,7 +280,9 @@ set so should only be used when a C# exception is not created.
</p>
<H3><a name="csharp_exception_example_check_typemap"></a>C# exception example using "check" typemap</H3>
<H3><a name="csharp_exception_example_check_typemap"></a>16.3.1 C# exception example using "check" typemap</H3>
<p>
Lets say we have the following simple C++ method:
</p>
@ -437,7 +455,9 @@ method and C# code does not handle pending exceptions via the canthrow attribute
Actually it will issue this warning for any function beginning with <tt>SWIG_CSharpSetPendingException</tt>.
</P>
<H3><a name="csharp_exception_example_percent_exception"></a>C# exception example using %exception</H3>
<H3><a name="csharp_exception_example_percent_exception"></a>16.3.2 C# exception example using %exception</H3>
<p>
Let's consider a similar, but more common example that throws a C++ exception from within a wrapped function.
We can use <tt>%exception</tt> as mentioned in <a href="Customization.html#exception">Exception handling with %exception</a>.
@ -499,7 +519,8 @@ The managed code generated does check for the pending exception as mentioned ear
</pre>
</div>
<H3><a name="csharp_exception_example_exception_specifications"></a>C# exception example using exception specifications</H3>
<H3><a name="csharp_exception_example_exception_specifications"></a>16.3.3 C# exception example using exception specifications</H3>
<p>
When C++ exception specifications are used, SWIG is able to detect that the method might throw an exception.
@ -555,7 +576,8 @@ DllExport void SWIGSTDCALL CSharp_evensonly(int jarg1) {
Multiple catch handlers are generated should there be more than one exception specifications declared.
</p>
<H3><a name="csharp_custom_application_exception"></a>Custom C# ApplicationException example</H3>
<H3><a name="csharp_custom_application_exception"></a>16.3.4 Custom C# ApplicationException example</H3>
<p>
This example involves a user defined exception.

50
Doc/Manual/Chicken.html
View file

@ -35,9 +35,9 @@
<li><a href="#Chicken_nn16">Typemaps</a>
<li><a href="#Chicken_nn17">Pointers</a>
<ul>
<li><a href="#Chicken_nn18">Garbage collection</a>
<li><a href="#collection">Garbage collection</a>
</ul>
<li><a href="#Chicken_nn19">Unsupported features and known problems</a>
<li><a href="#Chicken_nn18">Unsupported features and known problems</a>
</ul>
</div>
<!-- INDEX -->
@ -77,17 +77,15 @@
relies on some recent additions to CHICKEN, which are only
present in releases of CHICKEN with version number
<strong>greater than or equal to 1.89</strong>.
CHICKEN can be downloaded from
<a href="http://www.call-with-current-continuation.org/">http://www.call-with-current-continuation.org/</a>
To use a chicken version between 1.40 and 1.89, see the <a href="#collection">Garbage collection</a>
section below.
</p>
<p>
You may want to look at any of the examples in Examples/chicken/
or Examples/GIFPlot/Chicken for the basic steps to run SWIG
CHICKEN.
We will generically refer to the <em>wrapper</em> as the
generated files.
</p>
</p>
<H3><a name="Chicken_nn3"></a>17.1.1 Running SWIG in C mode</H3>
@ -268,7 +266,11 @@
<p>could be run with</p>
<div class="targetlang"><pre>
(handle-exceptions exvar (if (= exvar 15) (print "Correct!") (print "Threw something else " exvar)) (test-throw 1))
(handle-exceptions exvar
(if (= exvar 15)
(print "Correct!")
(print "Threw something else " exvar))
(test-throw 1))
</pre></div>
@ -426,39 +428,43 @@ $ ./example
type. flags is either zero or SWIG_POINTER_DISOWN (see below).
</p>
<H3><a name="Chicken_nn18"></a>17.7.1 Garbage collection</H3>
<H3><a name="collection"></a>17.7.1 Garbage collection</H3>
<p>If the owner flag in the SWIG_NewPointerObj is 1, NewPointerObj will add a
<p>If the owner flag passed to <code>SWIG_NewPointerObj</code> is 1, <code>NewPointerObj</code> will add a
finalizer to the type which will call the destructor or delete method of
that type. The destructor and delete functions are no longer exported for
use in scheme code, instead SWIG and chicken completly manage pointers.
</p>
<p>In situations where SWIG knows that a function is returning a type that should
use in scheme code, instead SWIG and chicken manage pointers.
In situations where SWIG knows that a function is returning a type that should
be garbage collected, SWIG will automaticly set the owner flag to 1. For other functions,
The <code>%newobject</code> directive must be specified for functions whose return values
the <code>%newobject</code> directive must be specified for functions whose return values
should be garbage collected. See
<a href="Customization.html#ownership">Object ownership and %newobject</a> for more information.
</p>
<p>In situations where a C or C++ function will assume ownership of a pointer, and thus
chicken should no longer garbage collect this type, SWIG provides the DISOWN input typemap.
After applying this typemap (see the Typemaps chapter for more information on how to apply typemaps),
chicken should no longer garbage collect it, SWIG provides the <code>DISOWN</code> input typemap.
After applying this typemap (see the <a href="Typemaps.html">Typemaps chapter</a> for more information on how to apply typemaps),
any pointer that gets passed in will no longer be garbage collected.
An object is disowned by passing the SWIG_POINTER_DISOWN flag to SWIG_ConvertPtr.
An object is disowned by passing the <code>SWIG_POINTER_DISOWN</code> flag to <code>SWIG_ConvertPtr</code>.
<b>Warning:</b> Since the lifetime of the object is now controlled by the underlying code, the object might
get deleted while the scheme code still holds a pointer to it. Further use of this pointer
can lead to a crash.
</p>
<H2><a name="Chicken_nn19"></a>17.8 Unsupported features and known problems</H2>
<p>Adding a finalizer function from C code was added to chicken in the 1.89 release, so garbage collection
does not work for chicken versions below 1.89. If you would like the SWIG generated code to work with
chicken 1.40 to 1.89, pass the <code>-nocollection</code> argument to SWIG. This will not export code
inside the _wrap.c file to register finalizers, and will then export destructor functions which
must be called manually.
</p>
<H2><a name="Chicken_nn18"></a>17.8 Unsupported features and known problems</H2>
<ul>
<li>No director support.</li>
<li>No support for c++ standard types like std::vector.</li>
<li>Importing multiple SWIG modules not working with TinyCLOS. (Planned on fixing for 1.3.25) </li>
</ul>
</body>

15
Doc/Manual/Contents.html
View file

@ -486,6 +486,17 @@
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="CSharp.html#csharp_introduction">Introduction</a>
<li><a href="CSharp.html#csharp_differences_java">Differences to the Java module</a>
<li><a href="CSharp.html#csharp_exceptions">C# Exceptions</a>
<ul>
<li><a href="CSharp.html#csharp_exception_example_check_typemap">C# exception example using "check" typemap</a>
<li><a href="CSharp.html#csharp_exception_example_percent_exception">C# exception example using %exception</a>
<li><a href="CSharp.html#csharp_exception_example_exception_specifications">C# exception example using exception specifications</a>
<li><a href="CSharp.html#csharp_custom_application_exception">Custom C# ApplicationException example</a>
</ul>
</ul>
</div>
<!-- INDEX -->
@ -517,9 +528,9 @@
<li><a href="Chicken.html#Chicken_nn16">Typemaps</a>
<li><a href="Chicken.html#Chicken_nn17">Pointers</a>
<ul>
<li><a href="Chicken.html#Chicken_nn18">Garbage collection</a>
<li><a href="Chicken.html#collection">Garbage collection</a>
</ul>
<li><a href="Chicken.html#Chicken_nn19">Unsupported features and known problems</a>
<li><a href="Chicken.html#Chicken_nn18">Unsupported features and known problems</a>
</ul>
</div>
<!-- INDEX -->

18
Doc/Manual/Makefile
View file

@ -27,21 +27,21 @@ check:
generate: swightml.book swigpdf.book
htmldoc --batch swightml.book || true
htmldoc --batch swigpdf.book
htmldoc --batch swigpdf.book || true
python fixstyle.py SWIGDocumentation.html
swightml.book:
echo "#HTMLDOC 1.8.23" > swightml.book
echo -t pdf13 -f SWIGDocumentation.pdf $(HTMLDOC_OPTIONS) >> swightml.book
echo "Sections.html" >> swightml.book
cat chapters >> swightml.book
swigpdf.book:
echo "#HTMLDOC 1.8.23" > swigpdf.book
echo -t html -f SWIGDocumentation.html $(HTMLDOC_OPTIONS) >> swigpdf.book
echo "#HTMLDOC 1.8.24" > swigpdf.book
echo -t pdf13 -f SWIGDocumentation.pdf $(HTMLDOC_OPTIONS) --stylesheet style.css >> swigpdf.book
echo "Sections.html" >> swigpdf.book
cat chapters >> swigpdf.book
swightml.book:
echo "#HTMLDOC 1.8.24" > swightml.book
echo -t html -f SWIGDocumentation.html $(HTMLDOC_OPTIONS) >> swightml.book
echo "Sections.html" >> swightml.book
cat chapters >> swightml.book
clean:
rm -f swightml.book
rm -f swigpdf.book

269
Doc/Manual/margin-left.patch Normal file
View file

@ -0,0 +1,269 @@
#
# Patch managed by http://www.holgerschurig.de/patcher.html
#
# This patch is against htmldoc 1.8.24, and it hacks in support for
# correctly indenting the <div class=""> sections in the SWIG manual.
# This patch should only be used until the 1.9 branch of htmldoc
# stabalizes, since the 1.9 branch includes true CSS1 support.
#
# This patch only affects the PDF generation, an unpatched htmldoc
# creates the one-page html documentation just fine.
#
--- htmldoc-1.8.24/htmldoc/ps-pdf.cxx~margin-left
+++ htmldoc-1.8.24/htmldoc/ps-pdf.cxx
@@ -158,6 +158,7 @@
# undef page_t
#endif // __hpux
+extern int lookup_div_class(uchar *);
/*
* Constants...
@@ -4188,9 +4189,24 @@
para->child = para->last_child = NULL;
}
- parse_doc(t->child, left, right, bottom, top, x, y, page, NULL,
+ {
+ int num_indent = 0;
+ uchar *cname;
+
+ if (cname = htmlGetVariable(t, (uchar *)"class")) {
+ num_indent = lookup_div_class(cname);
+ *left += 5.0f * num_indent;
+ *x = *left;
+ }
+
+ parse_doc(t->child, left, right, bottom, top, x, y, page, NULL,
needspace);
+ if (num_indent > 0) {
+ *left -= 5.0f * num_indent;
+ }
+ }
+
if (para->child != NULL)
{
parse_paragraph(para, *left, *right, *bottom, *top, x, y, page, *needspace);
--- htmldoc-1.8.24/htmldoc/htmldoc.cxx~margin-left
+++ htmldoc-1.8.24/htmldoc/htmldoc.cxx
@@ -62,6 +62,8 @@
const char *__XOS2RedirRoot(const char *);
}
#endif
+
+extern void parse_style(char *);
/*
@@ -2140,6 +2142,10 @@
}
else if (strcmp(temp, "--cookies") == 0)
file_cookies(temp2);
+ else if (strcmp(temp, "--stylesheet") == 0)
+ {
+ parse_style(temp2);
+ }
}
}
--- /dev/null
+++ htmldoc-1.8.24/htmldoc/style.cxx
@@ -0,0 +1,185 @@
+/* Extreamly simple parsing routines for CSS style sheets.
+ * We only parse div.class { } sections, and only look
+ * for margin-left: <num>em;
+ *
+ * Copyright (C) 2005 John Lenz <lenz@cs.wisc.edu>
+ *
+ * Released under GNU GPL v2 or above.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <fcntl.h>
+#include <string.h>
+#include <ctype.h>
+
+#include "types.h"
+
+#define BUFF_SIZE 512
+
+struct div_entry {
+ uchar class_name[BUFF_SIZE];
+ int indent;
+ struct div_entry *next;
+};
+
+static struct div_entry *head = 0;
+
+/* These are the parsing states */
+#define IGNORE_TILL_SEMI 0
+#define IGNORE_TILL_CLOSE_BRACE 1
+#define READING_DIV 2
+#define READING_CLASS 3
+#define READING_ATTRIBUTE 4
+#define READING_NUM 5
+#define CHECKING_ONLY_DIV 6
+
+static int at_eof = 0;
+
+static int strucmp(uchar *a, uchar *b) {
+ int i;
+ for (i = 0; a[i] && b[i]; i++) {
+ if (a[i] < b[i]) return -1;
+ if (a[i] > b[i]) return 1;
+ }
+ /* This isn't right, but who cares...*/
+ if (a[i] || b[i]) return 1;
+ return 0;
+}
+
+static int read_word(FILE *f, const char *word) {
+ char c;
+ for (int idx = 0; word[idx]; idx++) {
+ c = getc(f);
+ if (c == EOF) {
+ at_eof = 1;
+ return 0;
+ }
+ if (c != word[idx])
+ return 0;
+ }
+ return 1;
+}
+
+int lookup_div_class(uchar *name) {
+ struct div_entry *node = head;
+
+ while (node) {
+ if (strucmp(node->class_name, name) == 0)
+ return node->indent;
+ node = node->next;
+ }
+
+ return 0;
+}
+
+void parse_style(char *fname) {
+ FILE *f;
+ char c;
+ int state;
+ struct div_entry *cur = 0;
+ int class_idx = 0;
+ char num[BUFF_SIZE];
+ int num_idx = 0;
+
+ if (!fname) return;
+
+ f = fopen(fname, "r");
+ if (!f) {
+ fprintf(stderr, "Unable to parse style\n");
+ return;
+ }
+
+ state = READING_DIV;
+ while (!at_eof && (c = getc(f)) != EOF) {
+ switch (state) {
+
+ case IGNORE_TILL_SEMI:
+ if (c == ';')
+ state = READING_ATTRIBUTE;
+ break;
+
+ case IGNORE_TILL_CLOSE_BRACE:
+ if (c == '}')
+ state = READING_DIV;
+ break;
+
+ case READING_DIV:
+ if (c != ' ' && c != '\t' && c != '\n') {
+ if (c == 'd' && read_word(f, "iv.")) {
+ state = READING_CLASS;
+ cur = (struct div_entry *) malloc(sizeof(struct div_entry));
+ memset(cur, 0, sizeof(struct div_entry));
+ class_idx = 0;
+ } else
+ state = IGNORE_TILL_CLOSE_BRACE;
+ }
+ break;
+
+ case READING_CLASS:
+ if (isalpha(c)) {
+ if (class_idx >= BUFF_SIZE-1) {
+ fprintf(stderr, "class size %s too long\n", cur->class_name);
+ free(cur);
+ state = IGNORE_TILL_CLOSE_BRACE;
+ } else {
+ cur->class_name[class_idx++] = c;
+ }
+ } else {
+ if (c == '{') {
+ cur->next = head;
+ head = cur;
+ state = READING_ATTRIBUTE;
+ } else
+ state = CHECKING_ONLY_DIV;
+ }
+ break;
+
+ case READING_ATTRIBUTE:
+ if (c != ' ' && c != '\t' && c != '\n') {
+ if (c == '}')
+ state = READING_DIV;
+ else {
+ if (c == 'm' && read_word(f, "argin-left:")) {
+ num_idx = 0;
+ memset(num, 0, sizeof(num));
+ state = READING_NUM;
+ } else {
+ state = IGNORE_TILL_SEMI;
+ }
+ }
+ }
+ break;
+
+ case READING_NUM:
+ if (isdigit(c)) {
+ if (num_idx >= BUFF_SIZE - 1) {
+ fprintf(stderr, "Number too long\n");
+ state = IGNORE_TILL_SEMI;
+ } else {
+ num[num_idx++] = c;
+ }
+ } else if (c != ' ' && c != '\t') {
+ if (num_idx > 0 && c == 'e' && read_word(f, "m"))
+ cur->indent = atoi(num);
+ state = IGNORE_TILL_SEMI;
+ }
+ break;
+
+ case CHECKING_ONLY_DIV:
+ if (c != ' ' && c != '\t' && c != '\n') {
+ if (c == '{') {
+ cur->next = head;
+ head = cur;
+ state = READING_ATTRIBUTE;
+ } else {
+ free(cur);
+ state = IGNORE_TILL_CLOSE_BRACE;
+ }
+ }
+ break;
+ }
+ }
+
+ fclose(f);
+}
--- htmldoc-1.8.24/htmldoc/Makefile~margin-left
+++ htmldoc-1.8.24/htmldoc/Makefile
@@ -35,7 +35,7 @@
OBJS = gui.o file.o html.o htmldoc.o htmllib.o htmlsep.o http.o \
http-addr.o http-support.o image.o iso8859.o license.o md5.o \
- progress.o ps-pdf.o rc4.o snprintf.o string.o toc.o util.o
+ progress.o ps-pdf.o rc4.o snprintf.o string.o toc.o util.o style.o
#