Now allowing unicode characters for certain mathematical symbols

GAP · gap · commit 436e1858a06e · 2007-10-04T22:02:12.000Z
in mathematical formulae (and outside of them).
Adjusted code, documentation, examples.
Introduced entities &amp;NN;, &amp;ZZ;, and some more for \mathbb characters as
a start.



git-svn-id: path/gapdoc/trunk@185
diff --git a/3k+1/3k+1.xml b/3k+1/3k+1.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 
 <!--   A complete "fake package" documentation   
-   $Id: 3k+1.xml,v 1.3 2007-09-25 09:30:35 gap Exp $
+   $Id: 3k+1.xml,v 1.4 2007-10-04 22:02:12 gap Exp $
 -->
 
 <!DOCTYPE Book SYSTEM "gapdoc.dtd">
@@ -25,14 +25,12 @@
 <Body>
   <Chapter> <Heading>The <M>3k+1</M> Problem</Heading>
     <Section Label="sec:theory"> <Heading>Theory</Heading>
-      Let <M>k  \in {\mathbb N}</M>  be a natural number.  We consider
-      the sequence <M>n(i, k), i  \in {\mathbb N},</M> with <M>n(1, k)
-      =  k</M> and  else <M>n(i+1,  k) =  n(i, k)  / 2</M>  if <M>n(i,
-      k)</M> is even and  <M>n(i+1, k) = 3 n(i, k)  + 1</M> if <M>n(i,
-      k)</M> is  odd. <P/>  
-      It is not known whether for any natural number <M>k \in {\mathbb
-      N}</M> there  is an <M>m \in  {\mathbb N}</M> with <M>n(m,  k) =
-      1</M>.
+      Let  <M>k \in  &NN;</M> be  a  natural number.  We consider  the
+      sequence <M>n(i, k), i \in &NN;,</M> with <M>n(1, k) = k</M> and
+      else <M>n(i+1,  k) = n(i, k)  / 2</M> if <M>n(i,  k)</M> is even
+      and <M>n(i+1, k) =  3 n(i, k) + 1</M> if  <M>n(i, k)</M> is odd.
+      <P/> It  is not known  whether for  any natural number  <M>k \in
+      &NN;</M> there is an <M>m \in &NN;</M> with <M>n(m, k) = 1</M>.
       <P/>
       <Package>ThreeKPlusOne</Package>  provides   the  function  <Ref
       Func="ThreeKPlusOneSequence"/>   to  explore   this  for   given
diff --git a/CHANGES b/CHANGES
@@ -2,17 +2,29 @@
 
 1.0 -> 1.1
 
+- We allow unicode characters which have useful translations to 
+  LaTeX and as simplified string (with one character, for the moment)
+  in mathematical formulae. Introduced entities &CC;, &ZZ;, &NN;, &PP;,
+  &QQ;, &HH;, &RR; for \mathbb  characters.
+
+- Now chapter numbers in references to chapters are without trailing 
+  dot in text and HTML converters.
+
+- Fixed bug with vertical spacing for <Verb> in text converter.
+
 - GAPDoc can now be used with other languages than English, see
   'SetGapDocLanguage' for details.
 
+- Various documentation improvements.
+
 - New options "utf8" and "nopslatex" for LaTeX converter, see
   'SetGapDocLaTeXOptions'.
 
 - Introduced "LaTeXUTF8" encoding (uses known translations but leaves
   other characters as they are).
 
 - Removed support of '\N, \Z, ...' for '{\mathbb N}, {\mathbb Z}, ...
-  (was not documented before).
+  (was not documented before). But see &NN; above.
 
 - Introduced 'WrapTextAttribute' which takes care of existing escape
   sequences in the text to wrap. Use it for the text converter to handle
diff --git a/doc/app3k1.xml b/doc/app3k1.xml
diff --git a/doc/enter.xml b/doc/enter.xml
@@ -1,4 +1,4 @@
-<!-- $Id: enter.xml,v 1.13 2007-09-27 16:40:03 gap Exp $ -->
+<!-- $Id: enter.xml,v 1.14 2007-10-04 22:02:12 gap Exp $ -->
 <Chapter Label="HowEnter">
 <Heading>How To Type a &GAPDoc; Document</Heading>
 
@@ -360,7 +360,10 @@ In &GAPDoc; there are some more predefined  entities:
 Here <C>&amp;nbsp;</C> is a non-breakable space character.
 <P/>
 
-One can define  further local entities right inside  the head (see&nbsp;<Ref
+Additional entities are defined for some mathematical symbols, see <Ref
+Sect="MathForm"/> for more details.
+<P/>
+One can define  further  local entities right inside  the head (see&nbsp;<Ref
 Subsect="XMLhead"/>) of a &GAPDoc; XML document as in the following example.
 
 <Listing Type="Example">
diff --git a/doc/gapdoc.xml b/doc/gapdoc.xml
@@ -2,7 +2,7 @@
 
 <!DOCTYPE Book SYSTEM "gapdoc.dtd">
 
-<!-- $Id: gapdoc.xml,v 1.11 2007-05-31 12:27:30 gap Exp $ -->
+<!-- $Id: gapdoc.xml,v 1.12 2007-10-04 22:02:12 gap Exp $ -->
 
 <!-- The documentation to the GAPDoc system. 
      Copyright 2000-2007 by Frank Lübeck and Max Neunhöffer
@@ -57,7 +57,14 @@ gap> SizeScreen([72,40]);;
 
 </Body>
 
-<#Include SYSTEM "app3k1.xml">
+<Appendix Label="app:3k+1"><Heading>The File <F>3k+1.xml</F></Heading>
+
+Here is the complete source of the example &GAPDoc; document <F>3k+1.xml</F>
+discussed in Section&nbsp;<Ref Sect="sec:3k+1expl" />.
+
+<Listing Type="3k+1.xml">
+<![CDATA[<#Include SYSTEM "../3k+1/3k+1.xml">]]></Listing>
+</Appendix>
 
 <Appendix Label="GAPDocdtd">
 <Heading>The File <F>gapdoc.dtd</F></Heading>
diff --git a/doc/intro.xml b/doc/intro.xml
@@ -1,4 +1,4 @@
-<!-- $Id: intro.xml,v 1.12 2007-09-27 16:40:03 gap Exp $ -->
+<!-- $Id: intro.xml,v 1.13 2007-10-04 22:02:12 gap Exp $ -->
 <Chapter Label="ch:intro"><Heading>Introduction and Example</Heading>
 
 The main  purpose of  the &GAPDoc; package  is to define  a file  format for
@@ -67,7 +67,7 @@ character set (other common encodings are ASCII or ISO-8895-X encodings).
 
 <Listing Type="from 3k+1.xml">
 <![CDATA[<!--   A complete "fake package" documentation   
-   $Id: intro.xml,v 1.12 2007-09-27 16:40:03 gap Exp $
+   $Id: intro.xml,v 1.13 2007-10-04 22:02:12 gap Exp $
 -->
 ]]></Listing>
 
@@ -203,31 +203,34 @@ The text of the first section starts  as follows. The whitespace in the text
 is unimportant and the indenting is not necessary.
 
 <Listing Type="from 3k+1.xml">
-<![CDATA[      Let <M>k  \in {\mathbb N}</M>  be a natural number.  We consider
-      the sequence <M>n(i, k), i  \in {\mathbb N},</M> with <M>n(1, k)
-      =  k</M> and  else 
+
+<![CDATA[      Let  <M>k \in  &NN;</M> be  a  natural number.  We consider  the
+      sequence <M>n(i, k), i \in &NN;,</M> with <M>n(1, k) = k</M> and
+      else 
 ]]></Listing>
 
 Here we come  to the interesting question how to  type mathematical formulae
 in a &GAPDoc; document. We did not find any alternative for writing formulae
-in &TeX; syntax. (There is MATHML, but even simple formulae contain a lot of
-markup,  become quite  unreadable and they are cumbersome  to type.  Furthermore
-there seem to be no tools available  which translate such formulae in a nice
-way into &TeX;  and text.) So, formulae  are typed as in  &LaTeX;. There are
-three  types  of elements  containing  formulae:  <Q>M</Q>, <Q>Math</Q>  and
-<Q>Display</Q>. The  first two  are for  in-text formulae  and the  third is
-for  displayed  formulae.  Here  <Q>M</Q> and  <Q>Math</Q>  are  equivalent,
-when  translating a  &GAPDoc; document  into &LaTeX;.  But they  are handled
-differently  for terminal  text (and  HTML) output.  For the  content of  an
-<Q>M</Q>-element  there  are  defined  rules for  a  translation  into  well
-readable  terminal text.  More complicated  formulae are  in <Q>Math</Q>  or
-<Q>Display</Q> elements and they are just  printed as they are typed in text
-output. So,  to make a  section well readable  inside a terminal  window you
-should  try to  put as  many  formulae as  possible into  <Q>M</Q>-elements.
-In  our  example  text  we  used the  notation  <C>n(i,  k)</C>  instead  of
-<C>n_i(k)</C>  because  it  is  easier  to read  in  text  mode.  See
+in &TeX;  syntax. (There is MATHML,  but even simple formulae  contain a lot
+of  markup,  become  quite  unreadable  and they  are  cumbersome  to  type.
+Furthermore  there  seem to  be  no  tools  available which  translate  such
+formulae in  a nice way into  &TeX; and text.) So,  formulae are essentially
+typed  as  in &LaTeX;.  (Actually,  it  is  also  possible to  type  unicode
+characters of some mathematical symbols directly,  or via an entity like the
+<C>&amp;NN;</C>  above.)  There  are  three  types  of  elements  containing
+formulae: <Q>M</Q>,  <Q>Math</Q> and <Q>Display</Q>.  The first two  are for
+in-text formulae and the third is  for displayed formulae. Here <Q>M</Q> and
+<Q>Math</Q>  are  equivalent,  when  translating a  &GAPDoc;  document  into
+&LaTeX;.  But they  are handled  differently  for terminal  text (and  HTML)
+output. For the content of an <Q>M</Q>-element there are defined rules for a
+translation into well readable terminal  text. More complicated formulae are
+in <Q>Math</Q> or <Q>Display</Q> elements and  they are just printed as they
+are typed  in text  output. So,  to make  a section  well readable  inside a
+terminal window  you should  try to  put as many  formulae as  possible into
+<Q>M</Q>-elements. In our  example text we used the  notation <C>n(i, k)</C>
+instead of  <C>n_i(k)</C> because  it is  easier to read  in text  mode. See
 Sections&nbsp;<Ref Sect="GDformulae"/> and&nbsp;<Ref  Sect="sec:misc" /> for
-more  details.  <P/>  
+more details. <P/>
 
 A few lines further on we find two non-internal references.
 
diff --git a/doc/refdtd.xml b/doc/refdtd.xml
@@ -1,4 +1,4 @@
-<!-- $Id: refdtd.xml,v 1.24 2007-09-27 16:40:03 gap Exp $ -->
+<!-- $Id: refdtd.xml,v 1.25 2007-10-04 22:02:12 gap Exp $ -->
 <Chapter Label="DTD">
 <Heading>The Document Type Definition</Heading>
 
@@ -1376,6 +1376,14 @@ using  the  corresponding  entities  or by  enclosing  the  formula  between
 <Q><C>&lt;![CDATA[</C></Q> and  <Q><C>]]&gt;</C></Q>. (The  main reference
 for &LaTeX; is <Cite Key="La85" />.)<P/>
 
+It is also possible to use some unicode characters for mathematical
+symbols directly, provided that it can be translated by <Ref Func="Encode" /> into <C>"LaTeX"</C> encoding and that <Ref Func="SimplifiedUnicodeString"/> with arguments <C>"latin1"</C> and <C>"single"</C> returns something sensible.
+Currently, we support entities <C>&amp;CC;</C>, <C>&amp;ZZ;</C>,
+<C>&amp;NN;</C>, <C>&amp;PP;</C>, <C>&amp;QQ;</C>, <C>&amp;HH;</C>,
+<C>&amp;RR;</C> for the corresponding black board bold letters 
+&CC;, &ZZ;, &NN;,&PP;, &QQ;, &HH; and  &RR;, respectively.
+<P/>
+
 The only  element type that  is allowed within  the formula elements  is the
 <C>Arg</C> or <C>A</C> element (see  <Ref Subsect="Arg"/>), which is used to
 typeset identifiers that are arguments to &GAP; functions or operations.<P/>
diff --git a/example/example.xml b/example/example.xml
@@ -1,9 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 
-<!-- $Id: example.xml,v 1.16 2007-05-31 12:27:30 gap Exp $ -->
+<!-- $Id: example.xml,v 1.17 2007-10-04 22:02:12 gap Exp $ -->
 
 <!DOCTYPE Book SYSTEM "gapdoc.dtd"
- [ <!ENTITY see '<Alt Only="LaTeX">$\to$</Alt><Alt Not="LaTeX">--&gt;</Alt>'>]>
+ [ <!ENTITY see '<Alt Only="LaTeX">$\to$</Alt><Alt Not="LaTeX">--&gt;</Alt>'>
+ ]>
 
 <Book Name="GAPDoc Example">
 
@@ -46,7 +47,6 @@
 <Body>
   Text before chapter <Ref Chap="First"/>. (&see; <Ref Sect="Two"/>)
 
-
 <Chapter Label="First"><Heading>Sectioning Elements</Heading>
 
   Text before the section <Ref Sect="FirstSect"/>. (&see; <Ref Sect="Two"/>)
@@ -431,7 +431,10 @@ Here is a <E>table</E>:
 
 [&see; <Ref Sect="Ten"/>]<P/>
 
-Here is the table of special characters:
+Here is a table of special characters, the first two are special for
+XML and must be typed in by entities in &GAPDoc; documents. The other 
+characters are special for &LaTeX; but in &GAPDoc; they can be typed
+directly. 
 
 <Table Align="|c|c|c|c|c|c|c|c|c|c|c|c|c|" Label="charsInCDATA"> 
  <Caption>Special characters in character data</Caption>
@@ -475,6 +478,8 @@ And here are the predefined entities in &GAPDoc;:
 <HorLine/>
 </Table>
 
+And some more for mathematical symbols: 
+&CC;, &ZZ;, &NN;, &PP;, &QQ;, &HH;, &RR;.
 
 </Section>
 
@@ -949,10 +954,16 @@ Here is a <E>table</E>:
 
 <Listing>
 <![CDATA[<Section><Heading>Entities and Special Characters</Heading>
+<Label Name="TenBack"/>
 
-Here is the table of special characters:
+[&see; <Ref Sect="Ten"/>]<P/>
 
-<Table Align="|c|c|c|c|c|c|c|c|c|c|c|c|c|c|" Label="charsInCDATA"> 
+Here is a table of special characters, the first two are special for
+XML and must be typed in by entities in &GAPDoc; documents. The other 
+characters are special for &LaTeX; but in &GAPDoc; they can be typed
+directly. 
+
+<Table Align="|c|c|c|c|c|c|c|c|c|c|c|c|c|" Label="charsInCDATA"> 
  <Caption>Special characters in character data</Caption>
  <HorLine/> <Row> 
   <Item><C>&amp;</C></Item>
@@ -994,6 +1005,8 @@ And here are the predefined entities in &GAPDoc;:
 <HorLine/>
 </Table>
 
+And some more for mathematical symbols: 
+&CC;, &ZZ;, &NN;, &PP;, &QQ;, &HH;, &RR;.
 
 </Section>
 
diff --git a/gapdoc.dtd b/gapdoc.dtd
@@ -4,7 +4,7 @@
      By Frank Lübeck and Max Neunhöffer
      ================================================================== -->
 
-<!-- $Id: gapdoc.dtd,v 1.15 2007-05-21 22:07:18 gap Exp $ -->
+<!-- $Id: gapdoc.dtd,v 1.16 2007-10-04 22:02:12 gap Exp $ -->
 
 <!-- Note that this definition goes "bottom-up" because entities can only
      be used after their definition in the file. -->
@@ -58,6 +58,15 @@
 <!ENTITY XGAP   "<Package>XGAP</Package>">
 <!ENTITY copyright "&#169;">
 
+<!-- and unicode math symbols -->
+<!ENTITY CC "&#x2102;" > <!-- double struck -->
+<!ENTITY ZZ "&#x2124;" >
+<!ENTITY NN "&#x2115;" >
+<!ENTITY PP "&#x2119;" >
+<!ENTITY QQ "&#x211a;" >
+<!ENTITY HH "&#x210d;" >
+<!ENTITY RR "&#x211d;" >
+
 
 <!-- ==================================================================
      The following describes the "innermost" documentation text which 
diff --git a/init.g b/init.g
@@ -2,7 +2,7 @@
 ##
 #A  init.g                  GAPDoc              Frank Lübeck / Max Neunhöffer
 ##
-#H  @(#)$Id: init.g,v 1.16 2007-06-13 16:02:50 gap Exp $
+#H  @(#)$Id: init.g,v 1.17 2007-10-04 22:02:12 gap Exp $
 ##
 #Y  Copyright (C)  2000,  Frank Lübeck and Max Neunhöffer,  
 #Y  Lehrstuhl D für Mathematik,  RWTH Aachen
@@ -28,7 +28,10 @@ ReadPackage("GAPDoc", "lib/HelpBookHandler.g");
 # try to find terminal encoding
 GAPInfo.tmpfunc := function()
   local env, pos, enc, a;
-  if not IsBound(GAPInfo.TermEncoding) then
+  # we leave the GAPInfo.TermEncodingOverwrite for .gaprc
+  # for a moment, but don't document it - doesn't work with 
+  # loaded workspaces
+  if not IsBound(GAPInfo.TermEncodingOverwrite) then
     if IsList(GAPInfo.SystemEnvironment) then
       # for compatibility with GAP 4.4.
       env := rec();
@@ -58,6 +61,8 @@ GAPInfo.tmpfunc := function()
       # default is latin1
       GAPInfo.TermEncoding := "ISO-8859-1";
     fi;
+  else
+    GAPInfo.TermEncoding := GAPInfo.TermEncodingOverwrite;
   fi;
 end;
 GAPInfo.tmpfunc();
diff --git a/lib/GAPDoc2LaTeX.gi b/lib/GAPDoc2LaTeX.gi
diff --git a/lib/UnicodeTabs.g b/lib/UnicodeTabs.g
diff --git a/lib/XMLParser.gi b/lib/XMLParser.gi
