From df8516b78200789ccf3f69153e4f87817dcbf9d3 Mon Sep 17 00:00:00 2001 From: John Lenz Date: Wed, 30 Mar 2005 05:55:46 +0000 Subject: [PATCH] Update documentation and add margin-left.patch file for htmldoc git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@7117 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- Doc/Manual/CSharp.html | 36 ++++- Doc/Manual/Chicken.html | 50 ++++--- Doc/Manual/Contents.html | 15 +- Doc/Manual/Makefile | 18 +-- Doc/Manual/margin-left.patch | 269 +++++++++++++++++++++++++++++++++++ 5 files changed, 348 insertions(+), 40 deletions(-) create mode 100644 Doc/Manual/margin-left.patch diff --git a/Doc/Manual/CSharp.html b/Doc/Manual/CSharp.html index 6a5c75595..aa3d1f5a4 100644 --- a/Doc/Manual/CSharp.html +++ b/Doc/Manual/CSharp.html @@ -8,12 +8,24 @@

16 SWIG and C#

+
-

Introduction

+

16.1 Introduction

+

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 Mono and Portable.NET.

-

Differences to the Java module

+

16.2 Differences to the Java module

+ +

The C# module is very similar to the Java module, so until some more complete documentation has been written, please use the Java documentation as a guide to using SWIG with C#. @@ -170,7 +184,9 @@ Windows users can also get the examples working using a Cygwin or MinGW 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. -

C# Exceptions

+

16.3 C# Exceptions

+ +

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.

-

C# exception example using "check" typemap

+

16.3.1 C# exception example using "check" typemap

+ +

Lets say we have the following simple C++ method:

@@ -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 SWIG_CSharpSetPendingException.

-

C# exception example using %exception

+

16.3.2 C# exception example using %exception

+ +

Let's consider a similar, but more common example that throws a C++ exception from within a wrapped function. We can use %exception as mentioned in Exception handling with %exception. @@ -499,7 +519,8 @@ The managed code generated does check for the pending exception as mentioned ear -

C# exception example using exception specifications

+

16.3.3 C# exception example using exception specifications

+

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.

-

Custom C# ApplicationException example

+

16.3.4 Custom C# ApplicationException example

+

This example involves a user defined exception. diff --git a/Doc/Manual/Chicken.html b/Doc/Manual/Chicken.html index 8d1fbffb4..bf132b987 100644 --- a/Doc/Manual/Chicken.html +++ b/Doc/Manual/Chicken.html @@ -35,9 +35,9 @@

  • Typemaps
  • Pointers -
  • Unsupported features and known problems +
  • Unsupported features and known problems @@ -77,17 +77,15 @@ relies on some recent additions to CHICKEN, which are only present in releases of CHICKEN with version number greater than or equal to 1.89. - CHICKEN can be downloaded from - http://www.call-with-current-continuation.org/ + To use a chicken version between 1.40 and 1.89, see the Garbage collection + section below. +

    +

    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 wrapper as the - generated files. - -

    +

    17.1.1 Running SWIG in C mode

    @@ -268,7 +266,11 @@

    could be run with

    -(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))
    @@ -426,39 +428,43 @@ $ ./example type. flags is either zero or SWIG_POINTER_DISOWN (see below).

    -

    17.7.1 Garbage collection

    +

    17.7.1 Garbage collection

    -

    If the owner flag in the SWIG_NewPointerObj is 1, NewPointerObj will add a +

    If the owner flag passed to SWIG_NewPointerObj is 1, NewPointerObj 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. -

    - -

    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 %newobject directive must be specified for functions whose return values + the %newobject directive must be specified for functions whose return values should be garbage collected. See Object ownership and %newobject for more information.

    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 DISOWN input typemap. + After applying this typemap (see the Typemaps chapter 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 SWIG_POINTER_DISOWN flag to SWIG_ConvertPtr. Warning: 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.

    -

    17.8 Unsupported features and known problems

    +

    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 -nocollection 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. +

    + +

    17.8 Unsupported features and known problems

    diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index 3a384104b..eb357f0e1 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -486,6 +486,17 @@
    +
    @@ -517,9 +528,9 @@
  • Typemaps
  • Pointers -
  • Unsupported features and known problems +
  • Unsupported features and known problems diff --git a/Doc/Manual/Makefile b/Doc/Manual/Makefile index 831c31f74..5502567a7 100644 --- a/Doc/Manual/Makefile +++ b/Doc/Manual/Makefile @@ -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 diff --git a/Doc/Manual/margin-left.patch b/Doc/Manual/margin-left.patch new file mode 100644 index 000000000..70f087b92 --- /dev/null +++ b/Doc/Manual/margin-left.patch @@ -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
    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: em; ++ * ++ * Copyright (C) 2005 John Lenz ++ * ++ * Released under GNU GPL v2 or above. ++ */ ++ ++#include ++#include ++#include ++#include ++#include ++ ++#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 + + + # +