Permalink
Browse files

[project @ 2004-08-16 19:59:48 by panne]

XMLification
  • Loading branch information...
panne
panne committed Aug 16, 2004
1 parent 944f88d commit 55766b3a68ef5564321cf84305565b1cd73c3513
Showing with 192 additions and 204 deletions.
  1. +0 −199 doc/HSWin32.sgml
  2. +190 −0 doc/HSWin32.xml
  3. +2 −5 doc/Makefile
View
@@ -1,199 +0,0 @@
-<!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
-<!entity the-index SYSTEM "genindex.sgml">
-]>
-
-<book id="HSX11">
- <bookinfo>
- <date>2003-5-22</date>
- <title>HSX11 Guide</title>
- <author>
- <firstname>Alastair</firstname>
- <surname>Reid</surname>
- </author>
- <address><email>alastair@reid-consulting-uk.ltd.uk</email></address>
- <copyright>
- <year>1999-2003</year>
- <holder>Alastair Reid</holder>
- </copyright>
- <abstract>
- <para>This document describes HSWin32, the Haskell binding to Win32,
- version 2.00.</para>
- </abstract>
- </bookinfo>
-
- <!-- Table of contents -->
- <toc></toc>
-
-<!-- Introduction --------------------------------------------------------- -->
-
- <chapter id="introduction">
- <title>Introduction</title>
-
- <para> <literal/HSWin32/ is a Haskell binding to the popular
- <literal/Win32/ library provided on Microsoft operating systems.
-
- <para>The library aims to provide a direct translation of the Win32
- binding into Haskell so the most important pieces of documentation
- you should read are the <literal/Win32/ documents which can be
- obtained from the <ULink
- url="http://msdn.microsoft.com/library/default.asp">Microsoft MSDN website</ULink> and Charles Petzold's excellent book
- <ULink url="http://www.charlespetzold.com/pw5/index.html">Programming Windows</ULink>.
- Let me say that again because it is very important. Get hold of this
- documentation and read it: it tells you almost everything you need
- to know to use this library.
-
- </chapter>
-
- <chapter id="changes">
- <title>Changes from Win32 documentation</title>
-
- <para>In making a Haskell binding to a C library, there are certain
- necessary and/or desirable changes in the interface.
-
- These can be divided into systematic changes which are applied
- uniformly throughout the library and ad-hoc changes which are
- applied to particular parts of the interface.
-
- <Sect1 id="systematic-changes"><Title>Systematic Changes</Title>
-
- <VariableList>
-
- <VarListEntry><term/Naming Conventions/
- <ListItem>
- <Para>
- In translating the library, we had to change names to conform with
- Haskell's lexical syntax: function names and names of constants must
- start with a lowercase letter; type names must start with an
- uppercase letter.
- </para>
- <para>
- For example, we translate some C
- functions, constants and types as follows:
-
- <InformalTable>
- <TGroup cols="2">
- <ColSpec Colname="one" Align="Left" Colsep="0">
- <ColSpec Colname="two" Align="Left" Colsep="0">
- <TBody>
-
- <Row>
- <Entry>C Name</Entry>
- <Entry>Haskell Name</Entry>
- </Row>
-
- <Row>
- <Entry><function/HBRUSH/</Entry>
- <Entry><function/HBRUSH/</Entry>
- </Row>
-
- <Row>
- <Entry><function/CreateSolidBrush/</Entry>
- <Entry><function/createSolidBrush/</Entry>
- </Row>
-
- <Row>
- <Entry><function/wHITEBRUSH/</Entry>
- <Entry><function/WHITEBRUSH/</Entry>
- </Row>
-
- </TBody>
-
- </TGroup>
- </InformalTable>
-
-
- </Para>
- </ListItem>
- </VarListEntry>
-
- <VarListEntry><term/Types/
- <ListItem>
- <Para>
- We translate type names as follows...
-
- <InformalTable>
- <TGroup cols="3">
- <ColSpec Colname="one" Align="Left" Colsep="0">
- <ColSpec Colname="two" Align="Left" Colsep="0">
- <ColSpec Colname="three" Align="Left" Colsep="0">
- <TBody>
-
- <Row>
- <Entry><function/POINT/</Entry>
- <Entry><function/POINT/</Entry>
- <Entry><function/(LONG,LONG)/</Entry>
- </Row>
-
- <Row>
- <Entry><function/RECT/</Entry>
- <Entry><function/RECT/</Entry>
- <Entry><function/(LONG,LONG,LONG,LONG)/</Entry>
- </Row>
-
- <Row>
- <Entry><function/SIZE/</Entry>
- <Entry><function/SIZE/</Entry>
- <Entry><function/(LONG,LONG)/</Entry>
- </Row>
-
- </TBody>
-
- </TGroup>
- </InformalTable>
-
- </Para>
- <Para>
- We systematically use a type of the form <literal/ListFoo/ as a
- synonym for <literal/[Foo]/ and <literal/MbFoo/ as a synonym for
- <literal/Maybe Foo/. This is an unfortunate side-effect of the tool
- we used to generate the bindings.
- </Para>
- <Para>
- We named enumeration types so that function types would be easier to
- understand. For example, we added ... Note that the types are
- synonyms for <literal/Int/ so no extra typesafety was obtained.
- </Para>
- </ListItem>
- </VarListEntry>
-
- <VarListEntry><term/Exception Handling/
- <ListItem>
- <Para>
- We consistently raise exceptions when a function returns an error
- code. This affects most of the functions in the library.
- </Para>
- </ListItem>
- </VarListEntry>
-
- </VariableList>
-
- <Para>
- As an example of how these rules are applied in generating a
- function type, the C function with type:
-<ProgramListing>
-COLORREF GetBkColor(
- HDC hdc // handle to device context
-);
-</ProgramListing>
- is given the Haskell type:
-<ProgramListing>
-getBkColor :: HDC -> IO COLORREF
-</ProgramListing>
- </Para>
-
- </sect1>
-
- <Sect1 id="adhoc-changes"><Title>Ad hoc Changes</Title>
-
- <para>
- Finally, we chose to make some changes in the interface to better
- conform with idiomatic Haskell style or to allow a typesafe interface.
- These have not yet been documented.
-
- </sect1>
-
- </chapter>
-
- &the-index
-
-</book>
View
@@ -0,0 +1,190 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<book id="HSX11">
+ <bookinfo>
+ <date>2003-05-22</date>
+ <title>HSX11 Guide</title>
+ <author>
+ <firstname>Alastair</firstname>
+ <surname>Reid</surname>
+ </author>
+ <address><email>alastair@reid-consulting-uk.ltd.uk</email></address>
+ <copyright>
+ <year>1999-2003</year>
+ <holder>Alastair Reid</holder>
+ </copyright>
+ <abstract>
+ <para>This document describes HSWin32, the Haskell binding to
+ Win32, version 2.00.</para>
+ </abstract>
+ </bookinfo>
+
+ <!-- Table of contents -->
+ <toc></toc>
+
+ <chapter id="introduction">
+ <title>Introduction</title>
+
+ <para><literal>HSWin32</literal> is a Haskell binding to the
+ popular <literal>Win32</literal> library provided on Microsoft
+ operating systems.</para>
+
+ <para>The library aims to provide a direct translation of the
+ Win32 binding into Haskell so the most important pieces of
+ documentation you should read are the <literal>Win32</literal>
+ documents which can be obtained from the <ulink
+ url="http://msdn.microsoft.com/library/default.asp">Microsoft MSDN
+ website</ulink> and Charles Petzold's excellent book <ulink
+ url="http://www.charlespetzold.com/pw5/index.html">Programming
+ Windows</ulink>. Let me say that again because it is very
+ important. Get hold of this documentation and read it: it tells
+ you almost everything you need to know to use this library.</para>
+
+ </chapter>
+
+ <chapter id="changes">
+ <title>Changes from Win32 documentation</title>
+
+ <para>In making a Haskell binding to a C library, there are
+ certain necessary and/or desirable changes in the
+ interface.</para>
+
+ <para>These can be divided into systematic changes which are
+ applied uniformly throughout the library and ad-hoc changes which
+ are applied to particular parts of the interface.</para>
+
+ <sect1 id="systematic-changes">
+ <title>Systematic Changes</title>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>Naming Conventions</term>
+ <listitem>
+ <para>In translating the library, we had to change names
+ to conform with Haskell's lexical syntax: function names
+ and names of constants must start with a lowercase letter;
+ type names must start with an uppercase letter.</para>
+
+ <para>For example, we translate some C functions,
+ constants and types as follows:</para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colname="one" align="left" colsep="0"/>
+ <colspec colname="two" align="left" colsep="0"/>
+ <tbody>
+
+ <row>
+ <entry>C Name</entry>
+ <entry>Haskell Name</entry>
+ </row>
+
+ <row>
+ <entry><function>HBRUSH</function></entry>
+ <entry><function>HBRUSH</function></entry>
+ </row>
+
+ <row>
+ <entry><function>CreateSolidBrush</function></entry>
+ <entry><function>createSolidBrush</function></entry>
+ </row>
+
+ <row>
+ <entry><function>wHITEBRUSH</function></entry>
+ <entry><function>WHITEBRUSH</function></entry>
+ </row>
+
+ </tbody>
+
+ </tgroup>
+ </informaltable>
+
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Types</term>
+ <listitem>
+ <para>We translate type names as follows...</para>
+
+ <informaltable>
+ <tgroup cols="3">
+ <colspec colname="one" align="left" colsep="0"/>
+ <colspec colname="two" align="left" colsep="0"/>
+ <colspec colname="three" align="left" colsep="0"/>
+ <tbody>
+
+ <row>
+ <entry><function>POINT</function></entry>
+ <entry><function>POINT</function></entry>
+ <entry><function>(LONG,LONG)</function></entry>
+ </row>
+
+ <row>
+ <entry><function>RECT</function></entry>
+ <entry><function>RECT</function></entry>
+ <entry><function>(LONG,LONG,LONG,LONG)</function></entry>
+ </row>
+
+ <row>
+ <entry><function>SIZE</function></entry>
+ <entry><function>SIZE</function></entry>
+ <entry><function>(LONG,LONG)</function></entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>We systematically use a type of the form
+ <literal>ListFoo</literal> as a synonym for
+ <literal>[Foo]</literal> and <literal>MbFoo</literal> as a
+ synonym for <literal>Maybe Foo</literal>. This is an
+ unfortunate side-effect of the tool we used to generate
+ the bindings.</para>
+
+ <para>We named enumeration types so that function types
+ would be easier to understand. For example, we added ...
+ Note that the types are synonyms for
+ <literal>Int</literal> so no extra typesafety was
+ obtained.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Exception Handling</term>
+ <listitem>
+ <para>We consistently raise exceptions when a function
+ returns an error code. This affects most of the functions
+ in the library.</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ <para>As an example of how these rules are applied in generating
+ a function type, the C function with type:</para>
+<programlisting>
+COLORREF GetBkColor(
+ HDC hdc // handle to device context
+);
+</programlisting>
+ <para>is given the Haskell type:</para>
+<programlisting>
+getBkColor :: HDC -> IO COLORREF
+</programlisting>
+
+ </sect1>
+
+ <sect1 id="adhoc-changes">
+ <title>Ad hoc Changes</title>
+
+ <para>Finally, we chose to make some changes in the interface to
+ better conform with idiomatic Haskell style or to allow a
+ typesafe interface. These have not yet been documented.</para>
+ </sect1>
+ </chapter>
+</book>
Oops, something went wrong.

0 comments on commit 55766b3

Please sign in to comment.