CHANGES

                       CHANGES of the GAPDoc package

1.6 -> 1.6.1
- Slightly nicer display of header lines of ManSection's with long
  names and/or long argument lists.

- Added an element <Constr> to be used in ManSection's on constructors.

- Minimal changes to make GAPDoc (translation of manual, and handler
  functions for the help system) work in any single thread in HPCGAP.

1.5.1 -> 1.6
- Changed and documented the handling of <Alt Only="LaTeX"> elements;
  its content is not reformatted.

- Can now handle help books with empty bibliography.

- Some technical adjustments which make it easier to use GAPDoc with
  HPC-GAP.

- Some cosmetic improvements, mainly for text output and markup of nested
  elements.

- Introduce finer distinction of <Alt>-elements for HTML with/without
  MathJax.

- 'StringBibXMLEntry' supports now a 'rec(MathJax := true)' option.

- Added a new utility function 'InitialSubstringUTF8String'.

- 'NormalizedNameAndKey' can now find initials from UTF-8 encoded name
  strings.

- The HTML manuals in Browsers with Javascript now always have the 
  [Style] link, even if no MathJax version is generated.

- 'RunExamples' now returns 'true' or 'false'.

- Removed support for the "MathML" variant of 'GAPDoc2HTML' which 
  was probably not used anyway.

- MakeGAPDocDoc (more precisely AddPageNumbersToSix) will no longer enter
  a break loop in case of an empty index (noticed by Thomas Breuer).

- New function 'LabelsFromBibTeX'. If BibTeX is available this is used to 
  unify the labels used for citations and the ordering of the reference list
  in the LaTeX, text and HTML version of a GAPDoc document. 

- 'ComposedDocument' now accepts also file names with absolute paths and 
  relative to GAP roots. (Uses a new function 'FilenameGAP'.)

- Documented 'DOCCOMPOSEERROR' for 'ComposedDocument' to ignore missing
  chunks.

- Mention that .bib files for <Bibliography> must be in latin1-encoding,
  and corrected 3k+1.bib accordingly (error noticed by Bill Allombert).

- Corrected HorLine in tables without trailing | column (report and fix by
  Max Horn).

- Recognize document encoding in <?xml tag and in some other places case
  insensitively (proposed by Max Horn).

1.5 -> 1.5.1

- Adjustments to GAP's new DeclareUserPreference setup.

1.4 -> 1.5

- Substituted the TestManual functions by new ones based on the new
  'Test' functionality in the GAP library: ExtractExamples, RunExamples.
  (Used this to adjust all manual examples.)

- Added a copy of GPL text.

- Corrected/improved handling of certain external references, and some other
  small errors (reported by James Mitchell).

- Improved detection of UTF-8 input.

- Improved/adjusted manual examples.

1.3 -> 1.4

- Made license statement more direct.

- Slight change of the dtd: The <C> elements now permit <A> elements in 
  their content. The converters were adjusted accordingly.

- Several layout changes in text version: More unicode characters are used,
  e.g., for fill strings and table borders (see BOXCHARS). Also mathematical
  symbols from unicode are used more often.
  Less colors are used in default text theme.

- Several text themes are available in the distribution (more by others
  are welcome). The preferred theme can be configured by the user via
  SetGAPDocTextTheme and  at startup via a user preference
  SetUserPreference("GAPDoc", "TextTheme", ...).

- Improved markup of <Arg> elements in function definitions in Text and
  HTML conversion.

- The text version of the manuals now contains more hooks (by pseudo
  escape sequences) for preprocessing before display. Paragraphs are now
  reformatted to current screen width. Unicode to latinX translation is
  now done with multi-character substitution. And markup with visible
  characters becomes possible, e.g. the "old" text theme (tables are not
  reformatted which can lead to some problems). 

- Slightly changed layout of the title page in LaTeX/PDF manuals.

- The LaTeX/PDF manuals use less colors by default.

- The tables of content contain now references and index (not convinced
  that this is ok, but was often requested). 

- Preferred style for viewing the HTML manuals can be configured by the user
  via user preferences: SetUserPreference("GAPDoc", "HTMLStyle", ...) and
  SetUserPreference("GAPDoc", "UseMathJax", true/false)

- The HTML manuals support style switching (via URL and cookie) with
  javascript and cookie enabled browsers. Several styles (and combinations)
  are offered in the distribution (more by others are welcome).

- The HTML manuals contain now a hook to use javascript and a few more hooks 
  for CSS style sheets.

- All output versions contain now markup for coloring GAP examples as with
  ColorPrompt(true). (Easy to switch off for text and HTML in user config.)

- Link from MathJax HTML manuals to central server http://cdn.mathjax.org
  to get scripts and fonts.

- Added a link to the "Contents" on top and bottom of each HTML manual page.

- For LaTeX/PDF conversion of manuals we use now the "psnfss" for postscript
  fonts.

- Added more hooks and simplified customization of LaTeX/PDF manuals
  (see "SetGapDocLaTeXOptions"). 
  
- PDF-verison is now by default generated with bookmarks (for acroread and 
  other viewers), but such that they are not opened by default.

- Fixed a bug when displaying multiple hits while ANSI_COLORS=false.

1.2 -> 1.3

- Improved the example ./gapdoc.css file (also used for the GAPDoc manuals):
  when hovering over a link to a section its subsections are now shown in 
  a separate block.

- The Arg attribute in <Func > and other elements now allows for GAP 
  options.

- Added support for HTML output using MathJax (http://www.mathjax.org/).
  MakeGAPDocDoc and GAPDoc2HTML now allow an optional argument
  "MathJax".

- Better bound for long index entries to be hyphenated (can now also
  be changed by setting GAPDoc2LaTeXProcs.MaxIndexEntryWidth).

- Improved the \description environment in LaTeX output using the
  enumitem LaTeX packages. Now works with very long labels.

- Now a warning is given if ComposedDocument finds several pieces of
  documentation with the same label.

- Fixed a problem which caused ParseError in rare cases to display the
  wrong line (reported by Laurent Bartholdi).

- Tables without | or HorLine are now distinguished in HTML version, such
  that they can be configured to be displayed without borders.

- There is a new attribute Mode="M" for <Display> elements, if this is given
  the formula is processed as in <M> elements.
                       
1.1 -> 1.2

- New utility to access the MathSciNet data base from within GAP (only if
  your computer has access, of course),  see documentation of 'SearchMR'.

- Now letters counting appendices are also printed without trailing dot in
  references.

- Slightly changed HorLine's in text-version of output.

- Various changes in tools for bibliography data (many suggested by 
  Thomas Breuer):
  - Avoid some syntax errors caused by 'NormalizedNameAndKey' in case
    of first names starting with non-ASCII character (but still cannot
    correctly handle these cases, use BibXMLext instead).
  - Improved sorting of bib-entries in HTML/Text output.
  - Better heuristic functions for translating characters in LaTeX code in 
    BibTeX entries to unicode, see 'HeuristicTranslationsLaTeX2XML'.
  - Handle (rare) short MathReview numbers. 
  - Better formatted output for HTML version of bib-entries.
  - Fixed the case of an empty 'strings' list in 'RecBibXMLEntry'.
  - Apply recoding to <value ...> strings from BibXMLext data.

- Use default markup in StringBibAsText (undocumented, internally used by 
  StringBibXMLEntry) when called with one argument.

- Added more simplifications and LaTeX translations of unicode characters.

- Improved "RepeatedString".

- XML parser: 
  - Could show wrong line number for original position of code with error.
  - Now the ":" is allowed in element and attribute names, this allows
    to implement utilities for dealing with XML name spaces
    (http://www.w3.org/TR/2006/REC-xml-names-20060816/).

- Corrected bug in normalization of argument lists (if "," was used as
  separator). Also the layout was changed in case of leading optional
  arguments (reported by Laurent Bartholdi).

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). 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
  elements with markup which  are contained in each other correctly.

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.