                       CHANGES of the GAPDoc package

0.99999 -> 1.0

- Changed the status of the package from "deposited" to "accepted".

- GAPDoc language (only few changes, all are fully backward compatible):
  - Made entities for LaTeX special characters ($tamp;, &percent; and so on)
    unnecessary (but kept them--with simplified definitions--for backward 
    compatibility). Now just write characters in content and attribute
    values directly, except for math elements which contain LaTeX code.
  - A <ManSection> does now allow an optional <Heading> (I would not like
    if this would be used extensively, but can be sensible for ManSections
    which explain several commands.) 
  - <Index> does now allow an optional <Subkey> element to specify subkeys with
    further markup (not possible in 'Subkey' attribute).
  - <URL>, <Email>, <Homepage> now allow optional elements <Link> and
    <LinkText> to specify text with further markup (not possible in 'Text'
    attribute).
  - New element <Ignore Remark="...">. Can be used everywhere (e.g., for
    additional data like source code, or to comment non finished parts of
    the document).

- MakeGAPDocDoc: 
    - Now the text converter is called first to produce labels for
      (sub-)sections which are independent of their number (see 
      'Text converter:' below). 
    - Now only the PDF manual is compiled from the LaTeX version. 
    - The .log file written by pdflatex is checked for errors, warnings
      and overfull boxes; these are displayed. 
      
- Bibliography data (see '?GAPDoc: Utilities for Bibliographies'):
    - Defined a 'BibXMLext' format for bibliographies with DTD bibxmlext.dtd
      (better data format if not used for LaTeX).
    - Utilities for parsing BibXMLext data and translating them to various
      formats (BibTeX, Text, HTML). Includes a utility to approximate
      BibXMLext data from given BibTeX data.
    - BibXMLext databases can be specified in <Bibliography .../>  
      (and I suggest to use this possibility).
    - Labels for references in Text and HTML converter are now similar to
      those produced by BibTeX.
    
- New functions for extracting and checking the code in all <Example>
  elements, see 'ManualExamples', 'TestManualExamples'.

- Unicode strings: 
  - Introduced unicode strings and characters as GAP objects,
    see '?Unicode'.
  - Translations between unicode strings and GAP strings in various 
    character encodings, see '?Encode'. (Mainly UTF-8, ISO-8859-X, "XML"
    and "URL" encodings.)
  - Some non-injective (partial) maps from unicode: a "LaTeX" encoding,
    simplifications to ASCII or latin1, conversions to lowercase and 
    uppercase characters.

- The internal encoding for the XML parsed data is now UTF-8, this is also 
  recommended for input (all GAPDoc files are now in UTF-8 encoding), but
  all latin? encodings work as well.

- LaTeX converter: 
    - Convert long URLs such that LaTeX can hyphenate them after slashes
      (but without a maybe confusing hyphenation dash).
    - Documented SetGapDocLaTeXOptions, see ?GAPDoc2LaTeX. (E.g., settings for
      hyperref, using colors or not.)
    - The default LaTeX markup for <A>, <Arg> is now by slanted typewriter
      font.
    - Very long identifier names are now hyphenated in the (two-column) index. 
    - The pdf-manuals now know their paper size.
    - The pdf-manuals contain the robust labels generated by the text
      converter (see below). E.g., with xpdf one can display a labeled
      text directly: xpdf manual.pdf +L.<label>. Links of this type remain
      stable as long as the header of a sectioning unit is not changed.

- HTML converter: 
    - Introduced some more markup, such that the layout for the
      HTML files can be widely configured by  the manual.css file. 
    - Adjusted the sample gapdoc.css/manual.css style sheet file.
    - Added local links to (sub-)sections at top of each chapter.
    - The XHTML files are now in UTF-8 encoding. 
    - Here also links are to anchors which don't depend on section numbers.
      Links to a sectioning unit will remain working across several versions
      of the manual as long as this unit remains in the same chapter and
      keeps the same header.
  
- Text converter: 
    - The display markup (ANSI escape sequences) is now substituted by some 
      place holder markup, which is substituted on the fly while browsing via 
      the help system (using a user configurable "style sheet", see
      ?SetGAPDocTextTheme).
    - The text version of a manual is now in UTF-8 encoding, this is
      translated by the GAP help system to other terminal encodings on the fly.
    - As a side effect the converter produces labels for all chapters
      and (sub-)sections which are independent of their current number.
      These are used in the HTML and PDF versions of the manual. 
      This should make links between different manuals much more robust
      across different versions. 

- Print statements in some functions are now substituted by Info statements,
  such that they can be switched off, or can be set to debug level
  (new Info classes: InfoGAPDoc, InfoXMLParser, InfoBibTools).

- ComposedXMLString can now return information about the original file and 
  line number of any text in the composed  document. Also, that function is 
  substituted by 'ComposedDocument' because the preprocessing step can be used
  for completely different types of documents as well.

- ParseTreeXMLString:
    - can use the improved information from ComposedDocument
      to give better error messages in case of parsing errors. This uses the 
      new function OriginalPositionDocument.
    - can take a record with entity definitions as argument (and a bug was
      fixed that the entity dictionary for the parser was not reset before
      parsing).
    - these is a new command ParseTreeXMLFile which reads the document from
      a file.

- Improved the documentation which markup is allowed in attribute values
  (recursively substituted entities). Improved the code to handle all
  special XML or LaTeX characters in attribute values.
  
- Changed further details for handling special characters; e.g. in LaTeX we
  now try to use always the nicer characters for \{}~^ from the \texttt
  font.

- There is a utility to find out if the terminal running GAP uses a UTF-8
  encoding. If yes, then GAPInfo.TermEncoding is set to "UTF-8", otherwise
  to "ISO-8859-1" (latin1). You can set GAPInfo.TermEncoding in your .gaprc
  file (e.g. to some other "ISO-8859-?"). GAPDoc tries to translate the text
  version of GAPDoc manuals on the fly to this encoding.

- Removed some pre-GAP 4.4 syntax.

0.9999 -> 0.99999

- Now MathSciNet often gives two numbers as MRNUMBER in BibTeX references.
  For links in HTML text we use now only the first 9 characters (MRxxxxxxx).
  (Thanks to Alan Cain.)

- HTML conversion: 
  - changed XHTML DOCTYPE to official URI of definition.
  - added 'lang="en"' and 'xml:lang="en"' attributes to the <html ... > tag.
  - fixed a problem with forward references. (Thanks to Marco Costantini.)

- PDF conversion:
  - using author and title in document for PDF meta-information.
  - attribute values with underscores were not correctly escaped, this is
    fixed and an example is added to the documentation, see
    ?GAPDoc Example: MyOperation (for bla)
  - now handling XML meta-characters '<>&' in attribute values.
  
- The XML Parser now prints the position of the start tag when it finds 
  a non-fitting end tag.

- Some minor documentation improvements.

