manualchapters

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% 
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

classification of items:
-1 release critical, under no circumstances to be published in this form
-2 still embarrassing to publish this
-3 requires decision/discussion:
   please think about such an item, add a comment how to work on it,
   and assign the item to another class
-4 something missing (so feature does not exist because of lack of doc.)
-5 should be improved in the long run
-6 nice to have, usually cosmetic

% items with a star (*) behind the number involve global changes
% throughout the manual

% items are assigned to a person by putting the initials behind the number

% for items that have been done, replace "-" by "+" and put your initials

% to produce some statistics, use the following command:
% grep "^-" manualchapters | cut -f 1 -d " " | sort | uniq -c

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  When you intend to work on improving a manual chapter then
%%  put your name under the ``Who'' line for this chapter
%%  (initials should suffice),
%%  and enter the date when you started under the ``Started'' line;
%%  when you have finished the work on this chapter then enter the date
%%  under the ``Finished'' line,
%%  and enter comments concerning improvements that are still possible or
%%  necessary under the ``Comments'' line.
%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  Reference Manual
%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 1: Preface
% File: ./preface.xml (line 13)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 06, 2008
% Comments:
+1AK Move the relevant parts to the Reference Manual,
  put only a very short paragraph into the Tutorial.
  Left only the introduction and then two sections ("The GAP system" and
  "Further Information about GAP") reused from the preface to
  the reference manual. Chapters in the "manualchapters" file renumbered.
+3cAK Copyright notice: adjust the year?
  Made it automatically adjusted using the &RELEASEYEAR; entity
+3cAK Is it really a good idea to include release specific information such as
  a detailed list of changes in the beginning of the Tutorial?
  (This information is available on the GAP web pages,
  and I could imagine a collection of changes w.r.t. older versions being
  part of the Reference Manual --really as a reference-- for example as an
  appendix chapter.)
  I have not tried to beautify the changes list, since the next release
  will anyhow have a new list.
  TODO: indeed it should be an appendix, 
  references to this list should be updated
+2AK In the same paragraphs, the importance of packages should be emphasized
  more than it is now.
  (Perhaps simply add ``see below''?) and recommmend their usage 
-6 Should the references to the Reference Manuals and to the web site
  (for example section ``Release history and Prefaces'') be turned
  into hyperlinks in the HTML version?
+2AK put a note about the temporary preface for beta release which will be
   revised later
+1SL revise prefaces: check for consistency - all outdated information 
   must be updated. This mostly relates to ``Authors and Maintainers''
   and ``Acknowledgements'' sections.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 2: About the GAP Reference Manual - REMOVED
% File: ./about.xml (line 10)
% Who: Thomas Breuer
% Started: July 27, 2009
% Finished: July 27, 2009
% Comments:
+1AK ``This is one of four parts of the GAP documentation ..''
  This is no longer correct.
+1AK Add a link to the Tutorial in the HTML version.
+1AK ``This manual is divided into chapters. Each chapter is divided into
  sections and, within each section, important definitions are numbered.
  References are therefore triples.''
  Better state that the manual is divided into chapters, sections, and
  subsections; this is mentioned also in the chapter about the help system.
+1AK ``in each of the four manuals''
+1FL+MN  Resolved by deleting this section! I don't think that any 
  explanation of this kind is necessary, all of this is self-explanatory
  when one reads the manual. (FL)
  Manual Conventions:
  The statements about boldface, italics, monospace font are not correct.
  (And in the old version, the examples were not shown as intended.
  Also the description of `Oper', with certain single letters at the end of
  the line, is no longer correct.  (And again, the old example was wrong.)
  adjust to the current situation!
+5FL+MN Became irrelevant because of solution of previous point. (FL)

  Several instances of ``in the printed manual'' must be changed.
  Note that the old manual was essentially a TeX document --this defines the
  term ``printed manual''-- which was used to produce also the online help
  and an HTML version; so the PDF (or DVI) version was regarded as the most
  important format of the manual.

  I don't think that this belongs here. In the beginning there is the
  sensible hint to start reading about the help system. (FL)
  The new manual should express that there is one source text which is
  processed to obtain three variants, and that each format has its strengths
  and its limitations.
  One such aspect is the way how formulas are shown.
  The formulation in the old manual is not very useful:
  I would regard the appearance of symbols as equally important as the
  appearance of subscripts and superscripts.
+1AK Shouldn't the general information parts from the Preface of the Tutorial
  better be moved to the Reference Manual? (yes)
  TODO: all preface should go to the beginning of the reference manual 
  (except list of changes which should go to the appendix). Sections 1.1 
  and 1.5 of it should be also reused in the tutorial (using INCLUDE
  directives in GAPDoc).
+3c ``Pages are numbered consecutively'' --omit this in the HTML version?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 2: The Help System
% File: ./help.xml (line 12)
% Who: Thomas Breuer
% Started: July 23, 2009
% Finished: July 24, 2009
% Comments:
+2FL Invoking the Help:
  ``dvi files (produced by &TeX;)'' --replaced by LaTeX
  Removed, we no longer (need to) support dvi, use pdf (which often has
  hyperlinks).
+2FL Browsing through the Sections:
  - ``?< displays the section preceding the previously shown section,
    and ?> takes you to the section following the previously shown one.''
    --This is not true for GAPDoc format manuals, here the help is subsection
    oriented, i. e., if one asks for a particular topic then the corresponding
    subsection is opened (not the beginning of the section that contains this
    subsection), and if one goes further with ?> then the help is opened at the
    following subsection.
       changed to "section or subsection"
    (This holds also if one has used the pager facilities for moving forwards
    to the end of the whole chapter, say.)
       GAP cannot know what a user did in his/her (external) pager
  - ``?<< takes you back to the first section of the current chapter,
    which gives an overview of the sections described in this chapter.''
    --Is this really true for all chapters?  (Would it be useful to state this
    as a rule for writing documentation?)
       removed the "overview" statement
+2FL The description of the commands ``?[book:]sections'' and
  ``?[book:][chapters]'' is not sufficient.
  If no book is prescribed then the table of contents of the first book is
  shown, quitting the help leads to the table of contents of the second book
  and so on.
  What is the difference between ``?sections'' and ``?chapters''?
  What is the difference between ``?IO:'', ``?IO:sections'', ``?IO:chapters''?
  For GAPDoc books there seems to be no difference,
     mentioned that for some books ?sections and ?chapters may show the 
     same full table of contents
     that ?IO: and ?IO:chapters are the same was already in the description
  for other book such as the book for the `Hopf' package,
  there are a ``Table of Chapters'' and a ``Table of Sections''.
     yes both were generated with the old style manuals
  (BTW, shouldn't it be ``Contents'' rather than ``Content'', in the text of
  this section as well as in the displayed help pages?)
     it seems that "Content" only occurs in manuals generated by old
     versions of GAPDoc, so this is already fixed
+2FL Changing the Help Viewer:
  +FL ``dvi: The standard output format of &TeX;. Only useful if &TeX; is
    installed on your system.'' --Is &TeX really needed for using xdvi?
        removed the 'dvi' and 'ps' parts from the description, we now only
        provide pdf
  - ``HTML: ... Some books  use special  symbol fonts for  formulae and
    need an appropriate web browser for correct display.'' --Which book
    formats use symbol fonts? And in this case, is the choice of the browser
    the problem or the browser configuration (see below)?
        made a bit clearer and put the remark in parentheses (in my eyes
        one has to "misconfigure" the browser to display these symbol fonts,
        so will not provide more details
+2FL SetHelpViewer:
  - ``Furthermore the  terminal (window) should use a fixed  width font and
    we suggest to take one with <C>ISO-8859-1</C> (also called <C>latin1</C>)
    encoding.'' --Is this still true?
        now suggest terminal with UTF-8 encoding (which is the default on
        all modern systems anyway)
  - ``Note, that for  some books the browser must be configured to use symbol
    fonts.'' --Does this hold only for non-GAPDoc books? (Be specific!)
        put in parentheses with the formulation "some old manuals"
  - Related with the item above: 
    ``Formulae which use symbol fonts may be unreadable.'' --Tell in which
    formats symbol fonts may appear.
        also put in parentheses
  +AK Why must TeX (LaTeX?) be installed in order to use xdvi?
        FL: you need the fonts, they are not contained in a dvi-file
        (contrary to pdf-files)
     removed mentioning the help viewers 'xdvi' 
     removed remark on font configuration for 'xpdf'
+5*AK Pager:
  Heading ``Example'' above an <Example> element?
  (check in the whole manual whether ``Example:'' occurs immediately
  above an example!)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 3: Running GAP
% File: ./run.xml (line 18)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 04, 2008
% Comments:
-6* unified kilobytes vs. KBytes vs. Kilobytes (same for mega and giga),
  should be consistent throughout the manual (semi-automatic)
  What's the preferred form??? kB, Kb, Kbytes? Not KB=Knuth-Bendix, of course.
+6*AK unified `ctr-C', `ctrl-C' etc. (with various <C> and <A> markup)
  to <B>Ctrl-C</B>, should be consistent throughout the manual
+2*AK Are the following statements about the command line options `-m' and `-o'
  correct:
  ``Under UNIX the default amount of memory allocated by &GAP; is 24 MBytes.''
  ``Under UNIX the default amount is 256 MBytes.''
  (Is it reasonable at all to mention the values in the text,
  i.e., wouldn't it be better to point to those components in `GAPInfo'
  where the current values --not only the default values-- can be looked up?
  Note for example that the script for starting GAP may involve a different
  default.)
  best: write a sentence that one should start GAP and look at GAPInfo.<something>!
  AK: removed defaults for -m and -o. The manual already refers to GAPInfo as
  to the source of such information.
+2*MN The section `Command Line Options' mentions GASMAN, malloc, sbrk,
  and the GAP compiler; is this still correct?
  --> I have looked at this, all is still correct.
      Or do we want to withdraw the compiler for 4.5? I think not!
+6AK Should the command line options be sorted alphabetically?
+6AK The section about the Mac mentions menus; should the menu entries be
  marked using <C> elements (as currently) or better using <B> elements?
  AK: this is ignored since the whole section about MacOS was removed.
+2AK The section about the Mac states
  ``Presently, &GAP; for MacOS also supports Mac path names, but this may
  change in the future.'' --what is the status here?
  AK: this is ignored since the whole section about MacOS was removed.
+1*TB Is the file `.gaprc' really read *after* `lib/init.g'?
  We have to change and document the setup.
  [This has been done as a part of the recent startup rearrangement.]
+1TB If it is really still meaningful to support both GAP 3 and GAP 4 in one's
  `.gaprc' file, why is such a complicated example needed?
  Reading one of the two files depending on some distinguishing value
  would be natural, so why should one use `Exec' and `echo', and then read
  a file `/tmp/jJj'?
  (And why is the alternative restricted to UNIX systems? Very strange!)
  [This has been done as a part of the recent startup rearrangement.]
+3c*TB I would say that using a workspace should be the recommended way
  to speed up the startup of GAP.
  This chapter, however, advertises completion fles (``reduce the startup
  time of &GAP; drastically''), and the section on workspaces does not
  mention the speedup at all.

 Proposal: Move the section on completion files to the end of chapter 3 and 
 bring the section on saving a workspace earlier. Add text recommending saving 
 a workspace and saying that completion files may be withdrawn in the future.
 
  [Chapter 3 has been rearranged according to the proposal.]
+1AK Why ``The most tempting code to compile is probably the library''?
  change descr. of GAC: used only for compiling kernel modules from C code in
  packages; put this into a chapter on developing packages
  AK: - Sections on suitability for compilation and compiling the library code
        moved to the GAP.dev manual.
      - The rest of the GAC description moved to the chapter on developing 
        packages, revised and restricted to cover only kernel modules.
-5 In the future, the Example package may also contain an example of the 
   kernel module and the documentation of the parts of the kernel interface 
   (some of which is already documented in the GAP.dev manual)
+1SL: check how gac works with GMP when GAP code being compiled 
  contains large integers (the solution would be to generate four #ifdefs
  for various modes (32/64-bit, with/without gmp). Done: fixed by Steve.
-5 cross-ref. to undocumented `READ_GAP_ROOT'.
+1TB Admit loading packages that have been installed newly after the GAP
  session started; in particular, admit loading packages that are not
  known in a given workspace!
  [This has been done as a part of the recent startup rearrangement.]
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 4: The Programming Language
% File: ./language.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: November 09, 2008
% Comments:
-6 Turn the various lists of special words into tables?
  Or better make them accessible as lists of GAP strings?
-5 What exactly is a keyword?  The statement that this is ``a reserved word''
  in section ``Symbols'' does not say anything.
  And after an explicit list of ``the'' keywords,
  another list of ``keywords because of technical reasons'' is shown,
  which is confusing.
  Also confusing is the statement:  ``The only consequence of this is that
  those identifiers cannot be re-assigned, and ...''
  However, we have also the feature that ordinary identifiers can be
  protected from overwriting, so this is not a meaningful criterion.
-5 In section ``Identifiers'', it is emphasized that `\*' is an identifier
  and not a keyword.
  This suggests that `*' in fact is a keyword. Is it?
+2AK Another confusing topic:  On the one hand, it is stated that keywords
  cannot be used as identifiers, but on the other hand, the function
  `IsValidIdentifier' returns `true' for the input `"if"'.
  (If there is a finite list of keywords then having this as a list stored in
  a component of `GAPInfo' would make it possible to use it in
  `IsValidIdentifier'.  And also code for improving GAPDoc documents could
  benefit from that.)
  This information is now provided by a kernel function ALL_KEYWORDS,
  so IsValidIdentifier can be updated. SL (AK: IsValidIdentifier updated,
  now returns `false' for `"if"'; manual has been updated, now the list 
  of keywords is produced from newly added GAPInfo.Keywords component. 
-5 Once again identifiers:
  ``An identifier usually consists ...'' is not a sensible formulation for a
  definition, which one expects in the section ``Identifiers''.
  (There are several such vague formulations where precise statements would
  be desirable.)
-6 Several sections show syntax constructs which cannot be expressed using
  <ManSection> (and <A>) elements, for example `<A>function-var</A>()',
  `<A>left-expr</A> = <A>right-expr</A>', `<A>procedure-var</A>();'.
  How to deal with this?
  (Moreover, there are some cases where the ``declaration line'' does not
  fit onto one line.)
-6 Section ``For'' contained a piece of pseudo code, distinguishing
  keywords and constants from variable names.
  How to write this in GAPDoc?
-5 What is the `continue' statement good for?
  (At least the example shown is not striking.)
+5*MN Is the comparison with PASCAL up-to-date?
  (several occurrences; replace by self-contained descriptions,
  without referring to PASCAL or so!)
  --> Done.
-5 The section ``The Syntax in BNF'' was commented out.
  (``A few recent additions to the syntax may be missing from this definition.''
  What is a definition good for that is by definition not correct?
  And the table in this section is too long; the lower part is not visible,
  and one gets a lot of LaTeX error messages when processing the manual.)
  It would still be desirable to have a correct definition of the GAP syntax.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 5: Functions
% File: ./function.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 24, 2008
% Comments:
+2AK some examples missing. AK: added more examples.
-4 missing: STARTLINE_FUNC etc. 
  AK: StartlineFunc is already documented. What else is missing?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 6: Main Loop and Break Loop
% File: ./mloop.xml (line 10)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 21, 2008
% Comments:
-6* read-eval-print or read-eval-view?
-5MN We provide `ViewObj', `PrintObj', `Display', `String';
  where do we state which of these operations may delegate to others?
  (There is also the undocumented function `DisplayString'.)

 TODO: write the proposal and discuss in gap-dev: 
   Display > ViewObj > PrintObj > DisplayString > ViewString > String
   may delegate only to things after you in this order. For very large objects
   makes sense have a PrintObj method as well as String to save memory.
 --> This is done and documented. Discussion on gap-dev needed.
 --> Proposal sent.
 --> Additional question: Do we really want that a name of an object
     overwrites the PrintObj methods??? Perhaps it should overwrite ViewObj
     and not PrintObj

+2AK The variables `last', `last2', `last3' are documented in the Tutorial,
  there is an index entry for `last' in the section ``Main Loop''
  but nothing else in the Reference Manual about `last', `last2', `last3'.
  These variables should get a proper documentation in the Reference Manual.
  AK: there is already an example in this section involving all `last', 
  `last2' and `last3'. I've added index entries for `last2', `last3' to
  the reference manual.
-5AK Section ``View and Print'' ends with a paragraph on `SetName'.
  But this function is documented in Chapter ``Objects and Elements''.
+3cAK Can someone explain why ``DownEnv moves *up* nr steps''?
  (The statements about this are confusing, so they do not fit into a Reference
  Manual.) 
  This is clarified now, using output of Where as mnemonic.
  Also heading is used for better ManSection title.
+3cMN Section ``Editor Support'':  Why is the following statement commented out?
  ``Send comments  and suggestions to Frank.Luebeck@Math.RWTH-Aachen.De''
  (Better suggest to contact support@gap-system.org also for these issues?)
 Agreed.
+5FL Infos on command line history is now available with
     '?The command line history'
     including new commands to save and read the history.
  Is section ``Line Editing'' still correct?
  E. g., is the command line history really limited to about 8000 characters?
  An easy tests shows that 8000 characters is not a limit, but it's not clear
  if a bigger limit exists (AK removed 8000 limit already, asked Frank for 
  further updates)
+3cMN  Shouldn't the global variable `EDITOR' be turned into a component of
  `GAPInfo'? YES
   (Document the default for `EDITOR'?
  Does it make sense to suggest `/usr/ucb/vi'?)
  GAPInfo.EDITOR should default to the environment variable $EDITOR and
  probably to fail (or something that gives a sane error message) otherwise. 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 7: Debugging and Profiling Facilities
% File: ./debug.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 21, 2008
% Comments:
+3aAK Should `START_TEST' and `STOP_TEST' become documented?
    Added a section after the ReadTest section. Made it clear they are optional.
+3cMN Turn `PROFILETHRESHOLD' into a component of `GAPInfo'?
      Yes
      Done, in obsolete: PROFILETHRESHOLD still available for
      (partial) backward compatibility.
+2AK: Fill the section "Information about the version used" with content
  Done, referring to GAPInfo.Version
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 8: Options Stack
% File: ./options.xml (line 11)
% Who: Thomas Breuer
% Started: July 23, 2009
% Finished: July 23, 2009
% Comments:
+3c ``At some time, an options predicate or something of the kind may be added
  to method selection.''
  Is this still intended?  NO -- remove
  Explain that (currently) options are ignored by the method selection;
  only arguments of the function call are evaluated by the method selection.
   NO NEED

+3cMN Clarified.
 ``An alternative to this system is the use of additional optional arguments
  in procedure calls. This is not felt to be adequate because many procedure
  calls might cause, for example, a coset enumeration and each would need to
  make provision for the possibility of extra arguments. In this system the
  options are pushed when the user-level procedure is called, and remain in
  effect (unless altered) for all procedures called by it.''

  This is misleading: Additional optional arguments ARE used in most places,
  and in fact they are a clean way to transfer parameters to subroutines,
  whereas global options are in danger to be overwritten by someone else
  who tries to use the same mechanism.
  (I think optional arguments should be preferred to global options whenever
  one designs new code.)
  In my eyes, global options are a convenience not for the user but only for
  the programmer, in the situation that (s)he wants to carry a new parameter
  from a top level function to a low level function (a new method, say)
  without changing the intermediate function calls.
  The best reason for using global options in such a situation is that one
  simply cannot change the existing GAP library code that does not know about
  the new parameter.

(I admit that I do not like global options at all, in particular the
extended function call syntax.
In my eyes, this mechanism works only because it is used rarely.
If it will become more popular then eventually it will break its own
functionality.)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 9: Files and Filenames
% File: ./files.xml (line 17)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 24, 2008
% Comments:
-6* unify ``read-eval-print loop'' vs. ``read eval view loop''
-6* unify ``an error is signalled'' etc.
+2AK* Section `PrintTo':
  Is the ``operating system dependent maximum on the number of output files
  that may be open simultaneously'' still usually 14?
  (Section `Read' claims that it is usually 15.)
  The truth is that in scanner.c the limit is set to 16, and 15 of them 
  are available, and this is not an operating system dependent.
-3*TB Document GAPInfo. -- Suggest in Chapter 3 (but not necessarily all
  the fields) 
  Here, `Directory' mentions `GAPInfo.UserHome'
  -- turn this into a <Ref> as soon as the component gets documented.
  Which components shall be documented?
+3c `DirectoryCurrent': comment
  ``THIS IS A HACK (will not work if SetDirectoryCurrent is implemented)''
  Not a problem -- SetDirectoryCurrent must update GAPInfo.DirectoryCurrent 
+3c `DirectoriesLibrary' lists "lib", "grp", "prim" and so on as admissible
  arguments; after reorganizing the data libraries, for example "prim"
  will not be admissible; list the admissible values in a GAPInfo component?
  For documentation -- change examples to ones that are stable: lib, src & doc
-6  Maybe do GAPInfo thing as well.
  AK: not clear what does this comment mean.
+3c cross-reference to `GAPInfo.RootPaths' -- turn this into a <Ref> as soon
  as the component gets documented.
  (definition of the function: change this to return an empty list instead
  of raising an error if no such directory is found) -- NO
+2AK cross-reference to undocumented function `IsDirectory'
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 10: Streams
% File: ./streams.xml (line 18)
% Who: AK
% Started: January 25, 2008
% Finished: January 27, 2008
% Comments:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 11: Processes
% File: ./process.xml (line 16)
% Who: AK
% Started: January 28, 2008
% Finished: January 28, 2008
% Comments:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 12: Objects and Elements
% File: ./objects.xml (line 15)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 24, 2008
% Comments:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 13: Types of Objects
% File: ./types.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 05, 2008
% Comments:
-5 cross-ref. to undocumented variable `FamilyOfFamilies'
-5 How to introduce a `ManSection' for the `and' of filters?
  (see also chapter `Booleans')
+3c strange statements such as ``All attributes in the library are created
  during initialization, in particular they are not created dynamically
  at runtime.'' --of course one can create any filter at any time,
  the term ``initialization'' does not make sense.
  (What is really meant with that?)
+3c Shall we give up type data (see `DataType')?
  Max: PLEASE NOT! I am using it in a package! (cvec)
  Why get rid of it? It is used.
  No: Leave it.
+2AK Many <C>...</C> elements may be converted to cross-references
  (AK: Done, except four basic representations of GAP objects which do
  not have separate mansections).
-5* Many <Ref> elements use "Func" instead of "Filt", "Oper", "Attr" etc. 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 14: Integers
% File: ./integers.xml (line 12)
% Who: AK
% Started: 8 January 2008
% Finished: 21 January 2008
% Comments:
-4AK There are undocumented variables mentioned in <C> elements: 
  FactorsRho, MAXSIZE_GF_INTERNAL, and well described but not documented
  in separate ManSections variables Primes2, ProbablePrimes2,
  IsZmodnZObjNonprimeFamily, IsFFEFamily, RandomSourcesFamily
+4JS The <Description> for the documented function `PrimalityProof' is empty.
  Jack Schmidt promised to look into this.
-5 The documentation of IsPrimeInt should be adjusted to the current
   implementation (the bounds should be updated to the actual state-of art)
+5*MN,FL This is now supported and documented as extension of the 
         Arg attribute in <Func > and so on. (FL)
  GAPDoc issue:  
  How to display options in Arg? (see e.g. in FactorsInt, where we obtain
  FactorsInt(n[, :RhoTrials:=trials]), so the comma may be confusing).
-4* There are ManSections combining several definitions. I added labels where
  applicable to avoid multiply defined labels, and it was enough for that 
  purpose; however, names of such ManSections might be revised (for example),
  14.6.3 "State" unites definitions of "State", "Reset" and "Init".
  GAPDoc offers optional "Heading" element for such ManSections.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 15: Number Theory
% File: ./numtheor.xml (line 12)
% Who: AK
% Started: 14 January 2008
% Finished: 21 January 2008
% Comments:
+3c (by TB) The section `Sigma' states ``the known 44 Mersenne primes''
  --meanwhile two more Mersenne primes have been announced.
  So is it wise to have such a statement at all?
  (Better refer to a web page with info about Mersenne primes?)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 16: Combinatorics
% File: ./combinat.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 05, 2008
% Comments:
-6 Perhaps the sections should be reorganized (join the `NrSomething' stuff
  with the `Something' stuff).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 17: Rational Numbers
% File: ./rational.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 05, 2008
% Comments:
-5 I still think that having numerator and denominator separately is
  conceptually not clean, one should have an operation that returns a pair.
  Yes, one should add an operation NumeratorDenominatorRat returning
  a pair.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 18: Cyclotomic Numbers
% File: ./cyclotom.xml (line 17)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 05, 2008
% Comments:
-6AK `Int' and `RoundCyc' should be nearer to each other,
  with a cross-ref. if necessary
+2AK cross-ref. to undocumented variable `CyclotomicsFamily'
  (AK: added CyclotomicsFamily to the index. Note that we often do not
  document families)
-4 section ``Internally Represented Cyclotomics'' mentions that
  the conductors of internal cyclotomics are restricted to small integers,
  and refers to `IsSmallIntRep', which is undocumented;
  also, an example demonstrates that 2^28 is not a small integer,
  which is not necessarily true
  Yes: IsSmallIntRep should be documented in the integers chapter.
       Maximal values for both 32bit and 64bit should be given.
       Here, there should the statement that the conductor is a
       IsSmallIntRep and a reference but no example.
  AK: IsSmallIntRep is no longer mentioned anywhere in GAP manuals. If we 
  want, we may document it later, but this is not urgent at the moment.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 19: Floats
% File: ./floats.xml (line 12)
% Who: 
% Started:
% Finished: 
% Comments:
+1LB This chapter is merely a placeholder for the beta version of GAP 4.5.
   It should be filled with a real content.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 20: Booleans
% File: ./boolean.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 05, 2008
% Comments:
+6AK GAPDoc issue:
  How to introduce a `ManSection' for `and', `or', `not', `<>'?
  (see also chapter `Types of Objects')
  For the operators `=' and `<', one can instead talk about the operations
  `\=' and `\<', but this is perhaps also not really what one wants.
  AK: I've decided to leave `Types of Objects' as it is. As for `Booleans',
  I introduced new Subsections making the text more structured. They meant
  to be analogs of `ManSection', though their display style is different 
  from a proper `ManSection'.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 21: Lists
% File: ./lists.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 19th, 2008
% Comments:
-4 `IsInternalRep' is mentioned but not documented.
-6   These and the next point could be done with Subsections  and some
     sensible Index entries. 
     Actually, 'list[ pos ]' is a shortcut for '\[\](list, pos)'  which
     can be documented with a standard ManSection. (Similar for the other
     cases below.) (FL)
     Looking at that Chapter, maybe this point can be marked +?
  GAPDoc issue: 
  In the section ``List Elements'', the notation `list[ pos ]' is
  introduced, which cannot be used in `ManSection';
  how to write this down?.
  Similar questions arise with `list{ poss }', `list[ pos ] := object',
  or `list1 = list2', `list1 <> list2', `list1 < list2', `list1 <= list2'.
-6 GAPDoc issue:
  The `ManSections' about `IsBound' and `Unbind' for lists show the argument
  `list[n]', which can be interpreted as a contradiction to the syntax for
  optional arguments.
  (GAPDoc turns this into list[, n] --viewed as optional argument!)
  (The optimal solution would be to introduce, recommend, and document
  a two-argument syntax for these operations.)
+2AK The documented function COPY_LIST_ENTRIES should not be written with
  capital letters only (and the declaration line is too long, and looks ugly).
  Declared a synonym and used shorter argument names in the manual.
+2*AH,AK very long lines in examples in ``Comparisons of Lists''
  What is the recommended line length for manual examples?
  Immediate in-place fix done.
  It turns out that 79 characters is the maximum possible in the PDF
  version and 75 for the online version. In HTML this depends on the
  size of the browser window.
  (This was done by Frank on a systematic basis)
-5 There is a section title ``Comparisons of Lists'' and an index entry
  ``comparisons!of lists'' (i.e., ``of lists'' is a subkey);
  the idea behind the index entry is that several subkeys will appear
  under the index entry ``comparisons''.
  A side-effect is that the online help finds two matches, one for the
  section and one for the index entry, which point to the same place.
  How to deal with this?
+3c*MN It is confusing to use `last' as the name of an argument, but this
  occurred in some functions for ranges;
  which better name could be used?
  Also, should we better generally *forbid* assigning to `last', `last2' etc.?
  (Also `rec' should not be used as the name of an argument in the
  documentation; GAP does not admit `rec' as an argument name!)
  And should `last', `rec', and other dangerous names be forbidden in
  <A> elements?
  Yes, replace it.
  Done for rec. We keep "last" since it does not show up in Arg="..."
  but only in constructions like [<A>first</A>..<A>last</A>] which
  is OKish.
  Leave the decision whether it is forbidden in GAPDoc to the GAPDoc
  authors.
-5 If ranges will be generalized in GAP 4.5,
  the restrictions on bounds and length of ranges have to be dropped.
  Yes, adjust the documentation once this is actually implemented.
+3c `PositionSorted':  The old documentation contained the statement
  ``we catch plain lists by a function to avoid method selection'',
  which I think was not intended for the manual and therefore was removed.
  Make it a comment to the code rather a comment to the documentation.
+2AK `PositionSortedOp' is mentioned but not documented, 
  but actually there is a comment in the PositionSorted section. 
  AK: added index entry for PositionSortedOp
+2*FL GAPDoc problem:  Entering `?List' now opens the entry for GAPDoc's <List>
  element (the only exact match since the function `List' now has two
  variants with labels)
  [This is also a problem for `IsDocumentedFunction'.]
  (MN to ask Frank)
-6 `ListX' documentation:
  how to write down formatted/indented pseudo code, with comments
  in ordinary text, with <M> and <A> elements etc.
-3 `lists.xml' contains a section ``More about Sets'' from the GAP 3.4 manual
  that was commented out already in the 4.4 manual.
  What to do with this text?
  --> Take out the relevant parts of this and put it into section
      "Sorted Lists and Sets"
      However: Do we want to document the TNUM business storing
      denseness and sortedness???
+3c (AH) The sentence ``Currently &GAP; uses shellsort.'' in section
  ``Sorting Lists'' looks strange.
  (In which *methods* is shellsort used?)
-5 Mentioned undocumented functions `UnionSet', `IntersectionSet' from 
   coll.gi, which are also methods for more general operations `Union' and
   `Intersection'. It may be worth to document them properly.
-3 why is IsRange a category not a property?
  (clean up IsRange vs. ConvertToRangeRep?)
  --> Fix together with the ranges.
      Note that IsRange on Plain lists works and can silently change
      the representation to range representation.
  --> Rethink when we have more general ranges.
-4 ``cross-references'' to undocumented variables `IsGF2VectorRep',
  `Is8BitVectorRep', `IsGF2MatrixRep', `Is8BitMatrixRep' in the docum. of
  `IsListDefault'
-4 ``cross-reference'' to undocumented variable `IsZeroCyc' in the docum. of
  `Position'
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 22: Boolean Lists
% File: ./blist.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 19th, 2008
% Comments:
-3 missing description of the internal representation of *plain* lists;
  only compared to this, the description of blists is meaningful.
  (There is a comment on this in `blist.xml'.)
+3cMN It is not reasonable that calling `IsBlist' silently changes a list to
  the compact blist representation; instead, there should be
  `ConvertToBlistRep'; `IsBlist' should just check, not convert.
  --> Yes, provide and document ConvertToBlistRep, visit all occurrences
  of IsBlist in the library to see whether they need to be changed
  to ConvertToBlistRep. ConvertToBlistRep should give an error if
  the list is not a Blist and do nothing if it is already IsBlistRep.
  Make IsBlist not silently change its argument rep.
  This is already done!
  Note however: l := [true,false,true];  does automatically create
    a compact IsBlistRep!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 23: Row Vectors
% File: ./vector.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 19th, 2008
% Comments:
-4 crossref. to undocumented `IsLockedRepresentationVector'
+3cAK `CoeffsMod': what is the meaning of the argument `len1'?
 AK: added that if the optional argument <A>len1</A> is used, 
 it reduces only first <A>len1</A> elements of the list. 
+3cAK `ProductPol' is marked as obsolete -- remove it (and also its comment 
  lines in `vector.xml'? 
  AK: `ProductPol' and its description moved into "obsolete.g{d,i}". 
  Checked that it is not used/documented.
+3AH,AK What is the difference between `ShrinkCoeffs' and `ShrinkRowVector'?
  (Wouldn't one of them be enough?)
  Get rid of ShrinkCoeffs and replace all occurrences by ShrinkRowVector
  which has the better name.
  AK: ShrinkCoeffs moved to obsolete.{gd,gi}. 
-6 (cf. chapter ``Lists'')
  several descriptions of infix operators that cannot be handled with
  <ManSection>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 24: Matrices
% File: ./matrix.xml (line 12)
% Who: AK
% Started: February 01, 2008
% Finished:
% Comments:
-5 In section ``Duplication of Lists'', introduce subsections about
  ``ShallowCopy for lists'' and ``StructuralCopy for lists'';
  then the respective section for matrices (and others) can refer to these
  subsections.
+3bMN Is the statement that all matrices are lists still correct?
  --> Added a comment in this Chapter referring to the new chapter
      about vector and matrix objects
-4 IsBlockMatrixRep is not documented, only included into index
-4 IsLockedRepresentationVector is neither documented nor indexed
+3bSL (by TB:
  The docum. of `ConvertToMatrixRep' states: ``In general, it is better to
  call <Ref Func="ImmutableMatrix"/> instead since this function can also
  deal with mutable rows or rows locked in a wrong representation.''
  So why is `ConvertToMatrixRep' useful at all?
  (Because it is working in place?)

  Reordered documentation to make clear that ConvertToMatrixRep is
  a more technical internal alternative to ImmutableMatrix.  	   

+3bSL/MN (by TB:
  What is the status of the following statement:
  ``We plan to include greased blocked matrix multiplication for other
  finite fields, and greased blocked algorithms for inversion and other
  matrix operations in a future release.'')

  Still reasonable statement I think. SL
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 25: Integral matrices and lattices
% File: ./matint.xml (line 13)
% Who: Thomas Breuer
% Started: November 09, 2008
% Finished: November 09, 2008
% Comments:
+3cSL commented out declaration lines for `DiagonalizeIntMatNormDriven',
  `SNFNormDriven', `SNFofREF', `HNFNormDriven'
  --are these functions obsolete?

  I think so. There may be obscure cases where they are faster, but I don't 
  know what. SL
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 26: Vector and matrix objects
% File: ./matobj.xml
% Who: Max Neunhoeffer
% Started: February 16, 2011
% Finished: ???
% Comments:
  This is a completely new chapter.
-4MN needs to be completed from stuff in lib/matobj1.gd and lib/matobj2.gd
-2MN has 5 empty subsections and contains:  `FIXME: Collect all rules here.'
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 27: Strings and Characters
% File: ./string.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 19th, 2008
% Comments:
-4 Section ``Printing Strings'': document the special characters \<, \>
+3c just for curiosity: what does ``many English countries'' in Section
  `DayDMY' mean?
  --> Changed to "English speaking countries"
-4 crossref to undocumented `IsPlistRep'
-6 (cf. chapter ``Lists'')
  descriptions of infix operators `=' and `<>' that cannot be handled with
  <ManSection>
+3cAK Why are `INT_CHAR', `CHAR_INT', `SINT_CHAR', `CHAR_SINT' written in
  uppercase?
  --> Call them additionally IntChar etc. and document them as such.
  Remove comment about internal behaviour.
  Proper error management is already in place.
+3cAK Shouldn't the section ``Obtaining LaTeX Representations of Objects'',
  together with the functions `LaTeX' and `LaTeXObj', be removed?
  (These functions are not documented in GAP 4.4.)
  These should be documented conservatively.
  Actually they are documented (but not in the library source file
  but only in doc/ref/string.xml).
  AK moved their documentation from doc/ref/string.xml to the library source.
  This functionality is used in RCWA, NQL, NilMat packages.
  Status update by AK (02/10/2010):
  - moved TeXObj, LaTeXObj to obsolete.{gd,gi}
  - removed their description from string.xml and replaced it by a new text
  - moved all LaTeXObj method installations (from matrix.gi, ratfun.gi, 
    rational.gi, wordlett.gi) to obsolete.gi
  - inserted index entries to the documentation of all LaTeX string producing 
    functions
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 28: Dictionaries and General Hash Tables
% File: ./hash2.xml (line 13)
% Who: Max Neunhöffer
% Started: January 29, 2008
% Finished: February 8, 2008
% Comments:
(This chapter was moved from the "new" manual to the "ref" manual since 
the last release.)
+2AK An attribute <C>IntKeyFun</C> is mentioned which does not seem to
  exist. AK: removed it.
+2AK An operation <C>KeyIntSparse</C> is mentioned which does not seem to 
  exist. AK: removed it.
+2AK And KeyIntDense, DefaultHashLength are mentioned without markup,
  as if they would be a valid words. AK: markup added.
+2AK The description of AddDictionary contains a sentence which is
  obviously unfinished (AK: was corrected in rev. 4.24 on 04/08/2011?)
-5 This chapter needs some polishing of the formulations.
-3 Turn the inline reference in ManSection for IntegerHashFunction to 
  a proper reference to the bibliography. AK: The book by Cormen, Leiserson 
  and Rivest was added to the bibliography, but IntegerHashFunction is 
  not documented at the moment - should it be?
-5 This chapter has no examples at all, would be useful to add them eventually.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 29: Records
% File: ./record.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 19th, 2008
% Comments:
-6 (cf. chapter ``Lists'')
  description of `rec.name', `rec.( name )', `rec.name:= obj',
  `rec.( name ):= obj', `rec1 = rec2', `rec1 <> rec2', `rec1 < rec2',
  `rec1 <= rec2',
  which cannot be handled with <ManSection>;
+3c* Again: `rec' should not be used as the name of an argument!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 30: Collections
% File: ./coll.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 25th, 2008
% Comments:
+3c Random: As soon as ranges with arbitrarily large bounds are available,
  the variant Random( from, to ) is no longer necessary.
  -> Keep it for legacy reasons. Revisit documentation when large ranges
     are implemented.
+3bFL StateRandom, RestoreStateRandom: There is a disclaimer that these 
  functions are kept for compatibility reasons.
  Shouldn't they be moved to the obsolescent stuff?
  --> Done
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 31: Domains and their Elements
% File: ./domain.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 25th, 2008
% Comments:
+3c cross-reference to the Tutorial -- is this acceptable? Yes, it works.
-4 cross-reference to undocumented function `NormalizerInParent'
  (There is already a comment whether the section ``In Parent Attributes''
  should be moved from the `ext' manual to the Reference Manual.
  This would make it easy to document the `SomethingInParent' functions
  that actually exist.)
-4 cross-ref. to undocumented function `ParentAttr'
+2AK The functions described in Section ``Constructing Domains'' do not exist
  for all operational structures; at least add a remark about this.
+2AK docum. of `MultiplicativeZeroOp':
  relation to `IsMultiplicativeElementWithZero'? (AK: explained that
  the argument lies in the category `IsMultiplicativeElementWithZero')
-4 ``Comparison Operations for Elements'':
  Make explicit how <>, <=, >, >= are implemented, i.e., how they are
  related to \= and \<.
+2AK ``Arithmetic Operations for Elements'':
  why ``look up details about special methods in the index'' only for \mod?
  (AK: reformulated, there are also index entries for \*, \/, \^)
+3c* ``Useful Categories of Elements'':
  Several filters are explained as the *join* of other filters
  (file `lib/arith.gd');
  but it is just the other way round, they are the *meet*!
  (I suspect this pops up also in other parts of the manual.)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 32: Mappings
% File: ./mapping.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 25th, 2008
% Comments:
+3c `Projection': There is a unary version defined as the projection onto
  ``some natural *sub*domain''.  Does this make sense??
  --> Leave it, it is used e.g. in WreathProducts
  --> Changed subdomain to quotient domain
+2AK empty description of `Range', `Source', `IsAdditiveGroupGeneralMapping',
  `IsLeftModuleGeneralMapping', `IsRingGeneralMapping',
  `IsRingHomomorphism', `IsRingWithOneGeneralMapping',
  `IsRingWithOneHomomorphism', `IsAlgebraGeneralMapping',
  `IsAlgebraHomomorphism', `IsAlgebraWithOneGeneralMapping',
  `IsAlgebraWithOneHomomorphism', `IsSPGeneralMapping',
  `IsNonSPGeneralMapping', `IsGeneralMappingFamily'.
-3 Section ``Magma Homomorphisms'' defines magma homomorphisms as mappings
  that respect multiplication,
  and the next section is called ``Mappings that Respect Multiplication''.
  Does that make sense?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 33: Relations
% File: ./relation.xml (line 11)
% Who: Thomas Breuer
% Started: November 16, 2008
% Finished: November 16, 2008
% Comments:
-5 The whole chapter contains not a single example!
-3 What is the difference between `BinaryRelationByElements' and
  `GeneralMappingByElements'?
-3 Why are unary operations such as `ReflexiveClosureBinaryRelation' not
  attributes?
-3 `IsHasseDiagram': Is it a sensible definition of a property 
   that the return value is `true' if the argument was constructed 
   with `HasseDiagramBinaryRelation'?
-5AK `AsBinaryRelationOnPoints' is not in line with the convention about
  As<Something> functions.
  AK: should we have BinaryRelationByObject operation??? 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 34: Orderings
% File: ./orders.xml (line 11)
% Who: Thomas Breuer
% Started: November 16, 2008
% Finished: November 16, 2008
% Comments:
-3 IsShortLexLessThanOrEqual: Is ``short less ordering'' meaningful?
-4 IsBasicWreathProductOrdering: no definition, just an example
-4 IsWreathProductOrdering: neither definition nor example
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 35: Magmas
% File: ./magma.xml (line 11)
% Who: Thomas Breuer
% Started: November 16, 2008
% Finished: November 16, 2008
% Comments:
-4 MagmaByGenerators, MagmaWithOneByGenerators, MagmaWithInversesByGenerators:
  no definitions, no examples
-3 ``If a magma M has also an additive structure, e.g., if M is a ring,
  then the addition is always assumed to be associative and commutative.''
  Really?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 36: Words
% File: ./word.xml (line 11)
% Who: Thomas Breuer
% Started: November 09, 2008
% Finished: November 09, 2008
% Comments:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 37: Associative Words
% File: ./wordass.xml (line 11)
% Who: Thomas Breuer
% Started: November 09, 2008
% Finished: November 09, 2008
% Comments:
-6 The chapter structure is still not logical.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 38: Rewriting Systems
% File: ./rws.xml (line 11)
% Who: Thomas Breuer
% Started: November 16, 2008
% Finished: November 16, 2008
% Comments:
-4AK cross-ref to the undocumented functions `IsomorphismFpMonoid',
  `CreateKnuthBendixRewritingSystem'
+2AK: empty decsriptions for GeneratorsOfRws and AddGenerators
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 39: Groups
% File: ./groups.xml (line 11)
% Who: Thomas Breuer
% Started: December 01, 2008
% Finished: January 02, 2009
% Comments:
-5 `IsGroup': The sentence ``See 13.3 for details about categories.''
  is not very helpful.
-3 `Subgroup( G )': I think this is not a clean concept.
+4 AH `IndexInWholeGroup': Give an example where this applies.
+2AK `ConjugateSubgroup': What is this? (no definition, no example, ...)
-6AK `EpimorphismFromFreeGroup': Is the word found in the example ``as short as
  possible'' (i.e., of minimal length)?
-3 `Factorization': ``computes all elements of the group to ensure a short
  word is found'' --doesn't this approach in fact guarantee *minimal* length?
+4AK and cross-ref. to undocumented function `MappingGeneratorsImages')
-3 `Centralizer' for a conjugacy class states that this ``is a slight abuse 
   of notation''. So should the definition of `Centralizer' for this case 
   (as an attribute) be made explicit?
+2AK * Shouldn't `Complementclasses' be called `ComplementClasses'? 
   Yes, retaining the old name for compatibility
   AK: Done: Complementclasses -> ComplementClassesRepresentatives
   ComplementclassesEA -> ComplementClassesRepresentativesEA
   ComplementclassesSolvableWBG -> ComplementClassesRepresentativesSolvableWBG
   ComplementclassesSolvableNC -> ComplementClassesRepresentativesSolvableNC
   The first two names retained as synonyms for backwards compatibility.
   Since ComplementClasses is defined in Polycyclic package, its authors 
   are notified.
-4 `Omega: remark ``@At the moment methods exist only for abelian G and n=1.@''
-4 `PRump': remark ``@example missing@''
-4 `IsPSolvable': remark ``@Currently no method is installed!@''
-3 `ConjugacyClassSubgroups': Is this name needed at all--why not simply use 
   `ConjugacyClass'? (Do not forget to remove the `[]' method, as promised.)
-3 What is the recommended way to compute representatives of classes of
  maximal subgroups?
  (Note that `ConjugacyClassesMaximalSubgroups' refers to
  `MaximalSubgroupClassReps' for direct computation,
  and `MaximalSubgroups' refers to `ConjugacyClassesMaximalSubgroups'.)
-6* Are distinguishing labels "operation" and "attribute" (as for `Orbits')
  useful for the online help? Yes, they are useful, and should be added to
  other identifiers which are both operations and attributes.  
+2AK Section ``Numerical Group Attributes'':
  Is this reasonable, since attributes such as `NrConjugacyClasses' do not
  appear here?
  AK: added a note that it does not cover ALL attributes with numerical 
  values and put a couple of cross-references.
-4 Cross-references to undocumented functions `LeftActingGroup',
  `RightActingGroup'.
  TODO: there is a stub mansection at csetgrp.gd, extend it and link to the doc.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 40: Group Homomorphisms
% File: ./grphomom.xml (line 11)
% Who: Thomas Breuer
% Started: December 01, 2008
% Finished: January 03, 2009
% Comments:
-5* Formulations of the form ``The `NiceObject' of <obj> is the image of <obj>
  under its `NiceMonomorphism'.'' are confusing.
  Note that `NiceObject' and `NiceMonomorphism' are GAP functions, which
  are not the same as the words from which they are composed.
  (One could say something like ``The value of `NiceObject' for <obj> is the
  image of <obj> under the mapping returned by `NiceMonomorphism' when this
  is called with <obj>.'')
  How to proceed in such cases?
  They occur also in other chapters.
+3c Section ``Efficiency of Homomorphisms'' mentions a GAP function
  `GroupGeneralMappingByFunctions' which does not exist.
  (I have commented out the relevant part.
  Does anybody know what was intended here?)
  AH: Intended use was as analog for GroupHomomorphismByFunctions, but it
  seems not to be needed, so can stay out.

-4 Cross-reference to undocumented function `SetIsMapping'.
+AK `AutomorphismGroup':
  If the definition really intends to describe the general concept of an
  automorphism group of a GAP object, in the sense of the group of all
  bijections that preserve the algebraic structure of this object,
  then this must be described.
  However, since it is not obvious what is ``the structure'' of a domain,
  I think this is asking for trouble, and so we should better describe the
  operation only in the case that ist argument is a group.
  Yes - in the reference manual only for groups, and packages should document
  it for other domains. Mentioned relevant packages.
+4AK cross-ref. to undocumented function `MappingGeneratorsImages'.
+5 cross-ref. to ``Stabilizer Chains for Automorphisms Acting on Enumerators''
  (in former `ext' manual, mentioned as ``not yet available in GAP''
  --is this a good idea?) AK: seems not bad to me -- the referenced section 
  is non-trivial.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 41: Group Actions
% File: ./grpoper.xml (line 12)
% Who: Thomas Breuer
% Started: December 01, 2008
% Finished: December 05, 2008
% Comments:
+2AK strange sentence in ``About Group Actions'':
  ``the call to <C>ExampleActionFunction</C> implements the induced action
  of <A>G</A>'';
  I think this is nonsense, and have commented is out.
  (For example, there is no GAP function `ExampleActionFunction'.)
  AK: removed it completely
-3 `OnLines' and other action functions promise an error when the argument
  point is not normalized,
  but this is not true for `OnLines'.
  `OnSets' does not tell what happens if the argument set is not a set,
  but runs into an error in this case.
  1. I think that the predefined action functions should behave the same
     with respect to tests of the conditions on their arguments,
     and this should be documented consistently.
     (Currently there is a section ``Action on canonical representatives''
     *behind* the introduction of the action functions.)
  2. Aren't such tests an unnecessary overhead?
     (If we really want to have foolproof behaviour here, we could introcude
     `NC' variants, and change all the occurrences in the library ...)
-5* `Orbit': The action function is optional - this is now clear. 
    (The whole chapter should be checked for consistency.)
    We checked and stated the default value of action. May be improved by 
    cross-ref to the place where all other optional arguments (Omega, pnt, 
    gens, acts) are explained.
-4 `OrbitStabilizer' and `StabilizerOfExternalSet':
  What does the statement ``The stabilizer must have G as its parent.'' mean?
  The function *constructs* this stabilizer, so there is no requirement on
  the arguments, or?
  (And for `OrbitStabilizer', there is no description what the return value
  is ...)
  I have replaced the ``must'' by ``will'', as is used in the `Stabilizer'
  description.
  TODO: document the return value of OrbitStabilizer.
-6* GAPDoc issue:
  When a declaration line is too long, such as the first one for
  `ActionHomomorphism', then it is not left aligned in the PDF version.
  Can this be fixed easily?
-3 Is it really needed to call `ActionHomomorphism' with a result of
  `Action' (``for GAP 3 compatibility'')?
  In other words, is `Action' really required to store information about
  the arguments in its return value?
-3 `SparseActionHomomorphism': What does the sentence ``If G acts on a 
   very large domain Omega not surjectively'' mean?
  Is surjective here the same as transitive?
  (Several formulations in this chapter sound strange.)
-3 `ActorOfExternalSet': This works only if 
   `CanonicalRepresentativeDeterminatorOfExternalSet' is available, or?
-3 `IsTransitive': The definition does not assume that the group really 
  acts on the domain given. So for example the ``action on'' any singleton 
  set is always regarded as transitive. Is this a meaningful definition?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 42: Permutations
% File: ./permutat.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 08, 2008
% Comments:
+1SL contradictory statements about the maximal permutation degree:
  ``The points on which permutations in &GAP; act are the positive integers
  less than <M>2^{28}-1</M>'' vs.
  ``the maximal degree of any permutation in &GAP; is
  <M>m = 2^{22}-1024 = 4{,}193{,}280</M>''.
  Removed contradictory sentences from the manual.
+1 AH: I hope I have this fixed.
  confusing statement about the space requirement:
  ``The images are either all stored as <M>16</M>-bit integers or all as
  <M>32</M>-bit integers (actually as &GAP; immediate integers less than
  <M>2^{28}</M>), depending on whether <M>d \leq 65536</M> or not.
  This means that the identity permutation <C>()</C> takes <M>4m</M> bytes
  if it was calculated as
  <M>(1, 2, \ldots, m) * (1, 2, \ldots, m)^{{-1}}</M>.''
  If the images can be 16 bit or 32 bit integers, the total space must
  depend on whether the degree m is small or not, or am I missing something?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 43: Permutation Groups
% File: ./grpperm.xml (line 13)
% Who: Thomas Breuer
% Started: December 01, 2008
% Finished: January 10, 2009
% Comments:
+3bAH Uncommented.
  A nice example for `SmallerDegreePermutationRepresentation' (from regular
  representation of Sym(6) to natural representation) is commented out. Why?
+2AK There is the statement: ``There are no methods yet for IsSymmetricGroup
  and IsAlternatingGroup!'' Really?
  AK: removed it, there are methods (at least some).
+3bAH Yes.
  Is the reference <Cite Key="eickhulpkeXX"/> (up to now commented out)
  meanwhile available?
+1*AH: changed text
  Statement about stabilizer chain records:
  ``This gives a recursive structure where the <Q>outermost</Q> record
  representing the <Q>topmost</Q> stabilizer is bound to the group record
  component <C>stabChain</C> and has the components explained below.''
  The term ``group record component'' is wrong, it is a relic from GAP 3.
  And the term ``topmost stabilizer'' is either wrong or at least misleading,
  since the chain given by `StabChain' represents the group itself and not
  the stabilizer of the first base point.
  (In GAP 3, the situation was different: The group record itself had
  components `base' and `orbit', and the component `stabChain' represented
  the stabilizer of the first point in the `orbit' component.)
  The rest of the text should be checked for more such wrong statements.
+5AK The list label ``limit (default Size( Parent( G ) ) or StabChainOptions(
  Parent( G ) ).limit if this is present'' is too long!
+2 Description of the component `orbit': How shall the sentence 
   ``ordered in such a way that the base point b_i is'' end?
+1AH `GroupStabChain':
  cross-reference to `Generators( S )' and to ``assigned as component
  stabChain'' --relics from GAP 3?
  AH: commented out.
-4AK ``Working with large degree permutation groups'':
  Does it make sense to show a fake ``example'' of ``a group of degree
  231000'', where the input data (the generators) are not described?
  Would it be sensible to have the full example somewhere on the GAP
  web pages, and to refer to this from the Reference Manual?
  (This would be possible also in other cases.)
  TODO: add a sentence about the file structure. If possible, provide
  the file on the GAP pages and put URL in the manual. The concept makes
  sense, it shows straight line programs, so it's really useful example.
  
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 44: Matrix Groups
% File: ./grpmat.xml (line 11)
% Who: Thomas Breuer
% Started: February 06, 2009
% Finished: February 07, 2009
% Comments:
-5*c There is a statement about changed line length in some examples.
  (What shall be the default, how to deal with such cases?)
-3 `(Default)FieldOfMatrixGroup': The fact that the domain must be a field 
  suggests that matrix groups over non-fields are not supported. On the 
  other hand, the description of `IsGeneralLinearGroup' etc. talks about 
  rings. What is the status here, what has to be documented?
-4 cross-references to undocumented variables `LeftAction', `RightAction'.
-3 Section ``Matrix Groups in Characteristic 0'' says:
  ``Most of the functions described in this and the following section have
  implementations which use functions from the &GAP; package Carat.
  If Carat is not installed or not compiled, no suitable methods are
  available.''
  So why are the functions in question documented at all in the main manual?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 45: Polycyclic Groups
% File: ./pcgs.xml (line 12)
% Who: Thomas Breuer
% Started: May 25, 2009
% Finished: May 25, 2009
% Comments:
+2BE,AK Change the introductory section ``In GAP 3 these methods have been
  available for AgGroups only; ...  At the current state of implementations
  the methods for polycyclic groups can only be applied to finite groups.
  However, a more general implementation is planned.'', as follows:
  - State that the pc group methods are applicable to permutation groups and
    matrix groups that are  known to be solvable, and that the methods are
    especially efficient for groups whose elements are represented w.r.t. a
    pc presentation (crossref. to the chapter in question).
    Perhaps add a *VERY SHORT* remark about the different situation in GAP 3,
    for example via ``contrary to GAP 3'', but this should not be very
    prominent; in fact I would completely omit it.
  - Can the last two sentences be replaced by a reference to the package
    `Polycyclic'? 
  (AK: all done)
-4AK Section ``Elementary Operations for a Pcgs'' (and other sections):
  common example for several subsections; split this?
+3cBE,AK Induced pcgs are defined in Section 45.7, but several earlier subsections
  require their arguments to be induced pcgs;
  should te ordering be changed, or would it be sufficient to add
  cross-references? (AK: added cross-references)
+3cBE,AK `SpecialPcgs':
  The code (but not the documentation) contains a statement that any method
  installed for a group as the only argument should delegate to the method
  for a pcgs.  This means that nobody should install another method for this
  situation.  Shouldn't this become documented? (BE: I guess that thought 
  that this is not of interest. I still think it is probably not of interest)  
+2AK `AffineOperation', `AffineOperationLayer', etc.:
  There are already `AffineAction', `AffineActionLayer', etc.;
  shouldn't the old ``Operation'' like names become undocumented?
  AK: replaced Operation by Action, undocumented synonyms and moved them
  to obsolete.gd.
+3cAH comment ``@The syntax of this function may change in a future rewrite!@''
  for `ClassesSolvableGroup' --status?
  AH: Looking through this, I think that at this point a syntax change is 
  not in the forseeable future. Thus I removed the remark.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 46: Pc Groups
% File: ./grppc.xml (line 12)
% Who: Thomas Breuer
% Started: May 25, 2009
% Finished: June 14, 2009
% Comments:
+2BE,AK In the introductory section, adjust the statement ``At the current level
  of implementation GAP can only deal with finite pc groups. This will be
  extended in near future.'', cf. the comments to Chapter ``Polycyclic Groups''.
  (AK: done in the same way as in Chapter ``Polycyclic Groups'').
+3cBE,AK statement ``Note that a pc presentation is a rewriting system.'':
  cross-ref. to the documentation for rewriting systems?
  (BE: Theoretically a pc presentation is a rewriting system, but I do not 
  think that this link has ever be implemented in GAP. Hence a reference 
  would be misleading)
-4 empty description for `FamilyPcgs' and the following functions,
  but there are several cross-references to `FamilyPcgs'
+2BE,AK `IsParentPcgsFamilyPcgs':
  another reference to GAP 3 which should be omitted or at least should be
  made less prominent (cf. Chapter ``Polycyclic Groups'') 
  (AK: removed reference to GAP 3)
+4AK ``2-Cohomology and Extensions'':
  The ``forthcoming GAP package on Group Construction Methods'' is
  mentioned; turn this into a proper citation/link.
+2BE,AK `PcGroupCodeRec':
  The statement and the example belong to `PcGroupCode'.
  (examples for pcgs codes were improved)
  BE: PcGroupCodeRec uses PcGroupCode and allows various rather technical
  features on top of PcGroupCode. I think that PcGroupCodeRec does not
  need to be documented. Just eliminate from the Manual (AK: eliminated).
+3cBE,AK `Random Isomorphism Testing', inconsistent description:
  Is the input a list of groups or a list of code records?
  (And unify the text before the subsection and the text inside it.)
  (AK: done)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 47: Finitely Presented Groups
% File: ./grpfp.xml (line 12)
% Who: Thomas Breuer
% Started: June 14, 2009
% Finished: June 14, 2009
% Comments:
+2AK `FactorCosetOperation':
  Shall this synonym of `FactorCosetAction' be documented at all?
  AK: removed from documentation, moved synonym to obsolete.gd
+2SL Section `Standardization of coset tables':
  A ``caveat paragraph'' explains the difference between the lenlex
  standardization of coset tables used in GAP and the semilenlex
  standardization ``that we have used in earlier GAP versions'';
  say precisely in which GAP version the change of concepts happened.
  (In subsection `CosetTableStandard', essentially the same is said;
  avoid this.)
  In subsection `StandardizeTable', ``old'' and ``new'' convention are
  mentioned --this is not helpful, change this.
+4AK `IsFpGroup':
  Added example: the return value for a free group is `true',
  the return value for a pc group is `false'.
+4AK `StringFactorizationWord':
  Added an explicit example instead of giving an example in the text.
+4AK references to undocumented variables `TCENUM', `GAPTCENUM' 
  AK: added index entries for TCENUM and GAPTCENUM
+2AK Where is the notation `F.1' etc. introduced, which is used in several
  examples? (only for free groups, or for arbitrary groups, or for free
  structures?)
  TODO: find out for which groups it work, then document it.
  AK: DONE: Described this notation in `GeneratorsOfDomain' 
  and added cross-references to relevant places detected from calls to
  `InstallAccessToGenerators' or `\.' method installations, namely, for 
  free algebras and free algebras with one - in descriptions of 
  `GeneratorsOfAlgebra' and `GeneratorsOfAlgebraWithOne', for groups - 
  in `GeneratorsOfGroup', for free magmas and free magmas with one - in 
  `GeneratorsOfMagma' and `GeneratorsOfMagmaWithOne'. 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 48: Presentations and Tietze Transformations
% File: ./pres.xml (line 12)
% Who: Thomas Breuer
% Started: July 03, 2009
% Finished: July 05, 2009
% Comments:
-3 Does it make sense to document the synonyms `TzGo' and
  `SimplifyPresentation' in two different subsections?
  (same for `PresentationSubgroup' and `PresentationSubgroupRrs',
  for `PresentationNormalClosure' and `PresentationNormalClosureRrs')
-6*AK AddRelator:
  One sentence ends with the argument P, the following sentence starts with
  the argument word.
  This should be reformulated.
  (Find all such stuations automatically?)
-5AK TzSearch:
  Default values for the Tietze parameters `SaveLimit' and
  `searchSimultaneous' are described in this section,
  and there is a cross-reference to section 46.11;
  better the defaults would be described only there! (only in one place)
-4 The terms ``abstract word'' and ``Tietze word'' are used in several places;
  at least they should be explained.
+2AK DecodeTree:
  wrong cross-reference to 46.6, which should be 46.11 (``Tietze Options'')?
  (The text is ``The reason is that the Tietze option parameters described in
  Section <Ref Sect="Tietze Transformations"/> apply to ...''.). AK: fixed.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 49: Group Products
% File: ./grpprod.xml (line 11)
% Who: Thomas Breuer
% Started: December 01, 2008
% Finished: January 10, 2009
% Comments:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 50: Group Libraries
% File: ./grplib.xml (line 15)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 25, 2008
% Comments:
-5 under `GeneralLinearGroup', there is an example how to construct PGL;
  why not simply a cross-reference?
+4 empty ManSection about `SizesPerfectGroups'
-4 cross-references to undocumented functions `DegreeOfMatrixGroup',
  `IsPrimitiveMatrixGroup', `IsLinearlyPrimitive', `MinimalBlockDimension',
  `IsSolvable', `IsImfMatrixGroup', `ImfRecord',
  `FrattinifactorSize', `FrattinifactorId'
+2* The LaTeX macro `\sl' is used in several places (inside math mode).
  AK: checked that all \sl occurences were removed
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 51: Semigroups
% File: ./semigrp.xml (line 11)
% Who: Thomas Breuer
% Started: December 01, 2008
% Finished: January 10, 2009
% Comments:
-3JM `FreeSemigroup': examples involve also `FreeGroup' (move them away?)
-4JM empty definition for `IsFullTransformationSemigroup'
-3JM What are semigroup ideals?
-3JM strange definition of `ReesCongruenceOfSemigroupIdeal'
  (in particular, does an ideal know the semigroup in which it is an ideal?
  Note that there is only one argument.)
-3JM `HomomorphismQuotientSemigroup': one or two arguments?
  (The whole chapter looks dubious w.r.t. the relation of the given arguments
  and the text.)
-3JM `Rees Matrix Semigroups': (s, i, \lambda) or (i, s, \lambda)?
-4JM almost no examples in the whole chapter!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 52: Monoids
% File: ./monoid.xml (line 11)
% Who: Thomas Breuer
% Started: December 01, 2008
% Finished: January 10, 2009
% Comments:
-4JM no examples in the whole chapter!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 53: Finitely Presented Semigroups and Monoids
% File: ./fpsemi.xml (line 11)
% Who: Thomas Breuer
% Started: December 01, 2008
% Finished: January 10, 2009
% Comments:
-3JM What is the difference between `FactorFreeSemigroupByRelations' and the
  infix `/'?
-3JM Is there no `FactorFreeMonoidByRelations'?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 54: Transformations
% File: ./trans.xml (line 11)
% Who: Thomas Breuer
% Started: December 01, 2008
% Finished: January 11, 2009
% Comments:
-3JM Is it a good idea to define the relevant notation in the beginning of the
  chapter, and to use this notation in the later sections, in particular
  without cross-references to the definitions
-4JM `RestrictedTransformation': should be defined; give an example
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 55: Additive Magmas 
% File: ./addmagma.xml (line 11)
% Who: Thomas Breuer
% Started: December 01, 2008
% Finished: January 11, 2009
% Comments:
(removed ``preliminary'' from the chapter title, this chapter does not
look worse than others)
-5 better discuss the various categories together in one section?
  (this would reduce the text, and make clearer what the differences are)
-5 no examples: either add them or explain why they are unnecessary
  (for example because interesting additive magmas in GAP have more
  structure and are explained in other chapters)
-4 `AsAdditiveMagma', `AsSubadditiveMagma':
  commented out, so not yet supported officially
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 56: Rings
% File: ./rings.xml (line 11)
% Who: Thomas Breuer
% Started: December 01, 2008
% Finished: January 11, 2009
% Comments:
+2AK no documentation on near rings and semirings -- where to put this?
 DONE: cross-ref to SONATA and Smallsemi packages.
+2AK Would it be useful to add a disclaimer that there is little support for
  rings that have no additional structure?
  For (small) finite rings one can do something but infinite rings are
  handled by GAP in an acceptable way at most if they are at least algebras.
  DONE: yes, said that.
+4AK only example and no definition for `DefaultRingByGenerators'
  (AK: put a definition).
-4 `AsRing': commented out, so not yet supported officially
-3 what about sums and products of ideals?
-4 cross-reference to undocumented `RightActingDomain'
-4 empty description of `LeftActingRingOfIdeal', `RightActingRingOfIdeal'
-4 only few examples
-5 ideals:
  Currently we seem to have no support for the closure under the action of
  two different rings from the left and from the right.
  Is there need for such a generalization?
-3 Should fields lie in the filters `IsUniqueFactorizationRing',
  `IsEuclideanRing'?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 57: Modules
% File: ./module.xml (line 11)
% Who: Thomas Breuer
% Started: February 06, 2009
% Finished: February 07, 2009
% Comments:
+3AK `AsFreeLeftModule': I think that the intention was to leave this function 
  out from the GAP 4.4 documentation, since the `\Declaration' statement in 
  `doc/build/module.msk' was preceded with `%W '; but the manual builder seems 
  to ignore this, so `doc/ref/module.tex' contains the documentation;
  I have now added it also to the 4.dev documentation.
  AK: No methods installed in the library and packages. Removed.
+4AK Several statements talk about ``scalars''.
  It should be made precise what this means for a given module.
  AK: added a note: here and below by scalars we mean elements of a domain 
  acting on <A>D</A> from left or right as appropriate.
-5 The whole chapter is suitable at most for the case of (left) vector spaces,
  and all examples deal with that context.
  In fact there is few support for more general situations,
  even for Z-modules.
  GAP is almost useless for dealing with R-modules where R is a ring that
  is not a field and not Z.
  And the distinction between left modules w.r.t. scalar action and right
  modules w.r.t. an algebra action (e.g., via matrices on row vectors)
  is not described.
  All this should be sorted out.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 58: Fields and Division Rings
% File: ./fields.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 20, 2008
% Comments:
+6AK In the PDF version, there is too small space between the text and
  ``Example'' boxes.
  AK: This is regulated by GAPDoc. In the current version I can't see any 
  such examples. Maybe GAPDoc already addressed this problem.
+5AK Explicit <Heading> elements would be good in some <ManSection> elements.
  AK: I did this in one mansection (Traces) where this is needed.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 59: Finite Fields
% File: ./fieldfin.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 20, 2008
% Comments:
+2SL Are the statements about Conway polynomials, in particular about the
  relation between FFEs and Conway polynomials, still correct?
  (yes, they are correct)
+3bSL Just for curiosity: What happens if two FFEs are compared, one of which
  is in IsLexOrderedFFE, the other is in IsLogOrderedFFE?
  (Is the statement ``all elements of a given field should belong to the same
  one'' strict, and is it reasonable?)
  Strictly should be "all irreducible elements" and then it's reasonable. Adjusted.
  This also means that comparisons are always resolved before you get to the case raised
  above. 
+3bSL Why are `DegreeFFE', `IntFFE', `IntFFESymm' not declared as attributes?
  No good reason. Changed.
+3bSL add cross-references between `IntFFE' and `IntFFESymm',
  or put them into the same subsection?
  DOne
-5 Generalize `IntFFE' to vectors and matrices of FFEs,
  analogous to `DegreeFEE', and get rid of `IntVecFFE'!
+4AK crossref to `ViewLength' (undocumented)
  At least put () after ViewLength, better even document it properly.
  AK: ViewLength moved to obsoletes for GAP 4.7, since there is now a 
  user preference "ViewLength" to specify it.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 60: Abelian Number Fields
% File: ./fldabnum.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 20, 2008
% Comments:
-5 missing: rings of integers in abelian number fields
  (something for GAP 4.6)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 61: Vector Spaces
% File: ./vspc.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 20, 2008
% Comments:
+3c section `StructureConstantsTable' refers to the Tutorial;
  should this be avoided in general?
  AK: reference works and makes sense.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 62: Algebras
% File: ./algebra.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 20, 2008
% Comments:
+3 <#GAPDoc Label="[2]{algebra}"> refers to the Tutorial;
  should this be avoided in general?
  AK: reference works and makes sense.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 63: Finitely Presented Algebras
% File: ./algfp.xml (line 11)
% Who: Thomas Breuer
% Started: September 20, 2008
% Finished: September 20, 2008
% Comments:
+4 This chapter consists of a disclaimer --there is no documentation about
  this topic (yet?).
  MN will ask AH 
  Leave without documentation since there is no functionality.
  There is a reference from this chapter to Lie Algebras chapter, so their 
  places were swapped to make this reference forward for more natural order.
-4 TODO: extend algfp.xml documenting data structures, categories, properties
  etc. at a basic level.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 64: Lie Algebras
% File: ./alglie.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 20, 2008
% Comments:
+2AK some formulae (were not clean and still) are not clean,
  math mode and <C> elements and plain text are mixed up  
+3bAK,WdG The meaning of the 2nd argument of DominantWeights is not documented.
+3bAK RestrictedLieAlgebraByStructureConstants probably should be made 
  a separate mansection; what's the meaning of the 'nameinfo' argument in the 
  same section?
+5 RestrictedLieAlgebraByStructureConstants should be supplied with an example. 
+3aAK The section "Finitely Presented Lie Algebras" refers to 
  NiceAlgebraMonomorphism which is not documented (the method for the
  NiceAlgebraMonomorphism simply calls FpLieAlgebraEnumeration, which is,
  however, also undocumented).
  (AK: documented NiceAlgebraMonomorphism in algfp.gd and liealg.xml)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 65: Magma Rings
% File: ./mgmring.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: October 08, 2008
% Comments:
+2AK* (not only in this chapter) several empty <Description> elements inside
  <ManSection>:
  In the old manual, this might have been o.k. (a section containing some
  text and some lines of function declaration embedded into this text),
  but now this means that there are empty subsections!
  AK: I've done this systematically, identifying 57 empty mansections
  and putting a comment <!-- TODO: fill description -->.
-6* (not only in this chapter) some cross-references point to both a subsection
  and the corresponding section or chapter (which is unnecessary)
  AK: I did not find any of these in this chapter.
+3AK Polynomial rings are listed as examples of free magma rings.
  This is correct in theory, but formally, GAP's polynomial rings are not
  free magma rings. Done: added a remark about this.
+4AK cross-ref. to undocumented variable `IsMagmaRingObjDefaultRep'
  Done: documentation was in .gi file, converted it to a proper mansection.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 66: Polynomials and Rational Functions
% File: ./ratfun.xml (line 12)
% Who: Thomas Breuer
% Started: February 06, 2009
% Finished: February 07, 2009
% Comments:
+3AK Why is `Discriminant' not an attribute? Done: it is now an attribute
  and the 2-arg version is an operation.
+2AH: rewritten
  The introductory text in section "Indeterminates" is not understandable.
-5AK In the sections "Operations for Rational Functions",
  "Comparisons of Rational Functions", the <C> lines should be turned into
   <ManSection> structures.
-5 Are `NumeratorOfRationalFunction', `DenominatorOfRationalFunction' as
  independent attributes a meaningful concept,
  that is, shouldn't the information better be stored in a pair?
  Indeed, but for compatibility we must retain the existing setup.
-5 `LeadingMonomial':
  ``returns the leading monomial (with respect to the ordering given by
  MonomialExtGrlexLess''
  Wouldn't it be more sensible to admit an ordering as optional second
  argument?
+3AK In the examples, `Indeterminate' was replaced by `X'.  Why?
  (I would vote for avoiding the one-letter variable name,
  and eventually get rid of the operation name `X'.)
  AK: replaced X by Indeterminate in manual examples and code. Left it 
  only in the mansection for Indeterminate where X is documented as a 
  synonym. Suggestion to move X to obsoletes and withdraw it from the
  documentation was not accepted.
-5 Cryptic abbreviations, unnecessary or inappropriate notation,
  lots of parentheses especially in this chapter
  make it hard to understand
+4AK `QuotRemLaurpols': Say what the relevant values of the argument <mode> are!
+4AK `GcdCoeffs':
  There is the remark ``This should eventually become an operation and
  dispatch specially for rationals.'' It was removed.
+4AK `UnivariatenessTestRationalFunction': The description is completely useless.
  AK: I rewrote it and added examples.
+3AK `CoefficientsOfUnivariatePolynomial':
  ``It returns the empty string if pol is 0.'' --Why a string?
  (And isn't the empty list an obvious result,
  why is it useful to state this prominently?)
  AK: Fixed, returns empty list. Still useful to document.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 67: Algebraic extensions of fields
% File: ./algfld.xml (line 11)
% Who: Thomas Breuer
% Started: April 19, 2009
% Finished: April 19, 2009
% Comments:
-3 Why is no iterated Kronecker construction allowed?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 68: p-adic Numbers (preliminary)
% File: ./padics.xml (line 11)
% Who: Thomas Breuer
% Started: April 19, 2009
% Finished: April 19, 2009
% Comments:
+1AK Already the trivial example to express 4/5 as a 2-adic number
  is not correct, the value must be the *periodic* expansion
  0.010110011001100...
  (Without that, the subsequently introduced notion of approximation
  makes no sense.)
  AK: corrected this example; also extended the example for PadicNumber.
-4AK It should be made precise what precision means.
-4 Useless definition, and no example:
  ``The valuation is the p-part of the p-adic number.''
-4 `IsPurePadicNumber', `IsPurePadicNumberFamily', `IsPadicExtensionNumber',
  `IsPadicExtensionNumberFamily': empty description
-5AK The description of extensions of the p-adic number fields (Section 66.2)
  should be moved to the beginning of the chapter,
  or at least a link should be given at the beginning of the chapter;
  otherwise the introduction of the chapter suggests that only ``pure
  p-adic numbers'' are supported.
-5AK `PadicNumber' is explained in two sections; after rearrangement of the
  material (see above), this can be unified.
  Can we ask AH? So far AK at least put cross-references between both sections.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 69: The MeatAxe
% File: ./meataxe.xml (line 12)
% Who: Thomas Breuer
% Started: April 19, 2009
% Finished: April 19, 2009
% Comments:
-4MN The only reference given is [Par84]; cite also Holt-Rees and Ivanyos-Lux!
-4 State over which fields the tool works.
-3 Are the matrices entered in `GModuleByMats' really required to be group
  elements?
  (And why does the first sentence emphasize ``submodules of a group
  algebra''? --The MeatAxe does not deal with group algebras!)
-4 There are no examples for the functions in this chapter!
-3 SMTX.MinimalSubGModule: ``It assumes `Distinguish' has been called already.''
  Should this read as ``assumes that `MTX.Distinguish' has been called''
  or ``assumes that `SMTX.Distinguish' has been called''?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 70: Tables of Marks
% File: ./tom.xml (line 16)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 20, 2008
% Comments:
-3TB Should the section on ``Technical Details about Tables of Marks'' perhaps
  be moved to the end of the chapter?
-3TB Isn't there a better place for the section on standard generators?
-4TB In section ``The Library of Tables of Marks'', it is said that one can
  call `TableOfMarks' with argument a (library) character table.
  This should be documented either in the manual of the Character Table
  Library or in the ``Interface ...'' section of the current chapter,
  and then a proper link can be installed.
+4AK cross-references to the undocumented function AllLibTomNames,
  which belongs to the Library of Tables of Marks;
  so this function should be documented in this package,
  and then a proper link can be installed
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 71: Character Tables
% File: ./ctbl.xml (line 16)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 20, 2008
% Comments:
-4TB cross-references to undocumented functions ...
+1TB ConnectGroupAndCharacterTable: Do not support this function in the 
 next version.
-3TB IrreducibleRepresentations: refer to the GAP package in question!
  (also crossref to GAP's MeatAxe functions?)
-4TB There are disclaimers about features that are not yet available.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 72: Class Functions
% File: ./ctblfuns.xml (line 14)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 20, 2008
% Comments:
+6AK For `OrthogonalEmbeddingsSpecialDimension' and `RepresentativesFusions',
  the declarations are too long for a line in the PDF version.
  Can this be improved?
  AK: suggest to leave it as is. Shorter argument names would reduce 
  readability, while now argument names follow the naming conventions 
  used in other mansections.
+5AK There are still two <Display> elements (see `Norm', `Symmetrizations') 
  containing formulae that are nice in LaTeX but ugly otherwise. Shall we 
  use <Alt>? AK: MathJax handles them nicer, we may use <Alt> for text later.
  AK (later): In the text version, they are also displayed nicely in a 
  Unicode terminal, so I suggest to leave it as is too.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 73: Maps Concerning Character Tables
% File: ./ctblmaps.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 20, 2008
% Comments:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 74: Unknowns
% File: ./unknown.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 20, 2008
% Comments:
-4 cross-reference to undocumented variable `CyclotomicsFamily'
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 75: Monomiality Questions
% File: ./ctblmono.xml (line 12)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 20, 2008
% Comments:
-3TB better document `IsMonomial', already because of the implicit reference
  from ``IsMonomial for character tables'' to ``IsMonomial for groups''
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Former Chapter 77: Installing GAP - REMOVED
% File: ./install.xml (line 21)
% Who: Thomas Breuer
% Started: September 20, 2008
% Finished: September 20, 2008
% Comments:
+3 First of all:
  Does it make sense to put a chapter on the installation into the
  Reference Manual?
  (If one is able to read this chapter in one's own installation then
  the installation has worked.
  And the web version that can be read before the installation need not be
  part of the Reference Manual.)
  AK,MN et al. - this makes sense.
  AK: the chapter has been removed (16/09/2011). Some parts were re-used
  elsewhere. The plan is to have a single INSTALL document on Web and in
  the GAP root directory.
+3bAK Is the statement correct that there is no installer program?
  (We have two alternative installers for Windows and one alternative 
  installter for Mac OS X.) 
  AK: changed it to "there may be no installer program".
+2AK Are the required disk space and main memory mentioned up to date?
+2AK Is the statement correct that there is no Upgrade mode?
  AK: removed that sentence.
+3bAH NO
  Is the `htmie4r5p0' archive still needed,
  i.e., do we still have to mention old versions of browsers such as
  Internet Explorer which had difficulties with rendering Unicode correctly?
+3cAK Should ``Mozilla'' be replaced by ``Firefox''? (yes, replaced)
+3cTB The former chapter ``Migrating to  GAP4'' is mentioned (but not via a
  cross-reference, so one had to read the text for finding it ...).
  Should this better be removed completely?
  (removed the paragraph that addresses users with GAP 3 experience, i.e.,
  the statements about Migrating to GAP 4 and the compatibility mode)
+3AK Is it really necessary to discuss that there is no reason to print out
  the Reference Manual?
  (Yes, why not - as an extra reference to the Tutorial).
+1AK,JJM Installation instructions still refers to zoo archives, explains how 
   to get GAP for Mac OS and does not reflect recent changes in the build
   process (gmp and readline options) - this should be cleaned up.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 76: GAP Packages
% File: ./gappkg.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 20, 2008
% Comments:
+4AK has to be merged with the chapter gappkg.xml of the former `ext' manual,
  see the comments there
  Idea: Cross-ref to package loading log. Rename to "Using GAP packages".
  One chapter is for users, one for developers.
+4AK Should LoadAllPackages become documented (AK)? 
   It has no practical use except for the testing purposes, but it is good
   to advise to package authors to try their packages with it.
   AK: yes, it is now documented in the Example package.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 77: Replaced and Removed Command Names
% File: ./obsolete.xml (line 10)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: September 20, 2008
% Comments:
+3a other obsolete names for package functions? (AK: Thomas told also about
  PACKAGES_VERSIONS - I've mentioned it too).
+3cTB really document GAPInfo --but where? (in Chapter ``Running GAP'',
  Section ``Global Values that Control the GAP Session'')
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 78: Method Selection
% File: ./methsel.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 10, 2008
% Comments:
-5 cross-references to undocumented functions Degree, Rank, RankOperation
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 79: Creating New Objects
% File: ./create.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 10, 2008
% Comments:
+3aAK Section `NewCategory' contains the following promise:
    @Eventually tools will be provided to display hierarchies of categories
    etc., which will help to choose <A>super</A> appropriately.
  How to deal with this? (AK: I removed this promise)
-4 cross-references to undocumented functions IsInternalRep, IsDataObjectRep,
  IsComponentObjectRep, IsPositionalObjectRep, ComputedSylowSubgroups.
  IsAttributeStoringRep, IsCollsElms
+3a There is a remark: ``Categories and representations should not be 
  operations, the same for filters made by <C>NewFilter</C>!''
  (Done - now everything is displayed properly).
+3a Is the section ``External Representation'' really of interest?
  That is, where is this concept really used?
  Yes, this is useful.
+3a Is it really necessary to distinguish `DeclareGlobalFunction' and
  `DeclareGlobalVariable'? (Answer: YES)
  (In fact the implementation looks different.)
  The code contains the following statement:
  `` Global functions of the GAP library must be distinguished from other
  global variables (see variable.g) because of the completion mechanism.''
  Is this really true?
  Can't the system decide whether a variable is a function or not?
+3aMN We could get rid of `DeclareSynonymAttr' by checking in `DeclareSynonym'
  whether the variable in question is actually an attribute,
  and if yes then binding also the globals for its setter and its tester.
  Done: However: keep DeclareSynonymAttr in the library because it is
                 valuable information in the code and provides
                 backward compatibility, withdraw documentation 
  Completely reverted: Various uses in the library and packages make
                       changes to the documented behaviour essentially
                       impossible
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 80: Examples of Extending the System
% File: ./intrfc.xml (line 13)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 10, 2008
% Comments:
+3aAK In ``Extending the Range of Definition ...'', explain redeclaring
  operations? (For packages, this is anyhow necessary.)
  AK: said that it is also possible to re-declare an operation with another 
  number of arguments and/or different filters for its arguments.
-5* In ``Enforcing Property Tests'', one finds ``As mentioned above''.
  This is not very useful if one does not assume that someone reads the
  whole book.  So we should try to avoid such formulations, and to give
  explicit references instead.
  (This is of course a general statement for the whole documentation.)
+3aAK Section ``Adding a new Operation'' starts with ``The next step''
  --what does this refer to? (AK: reformulated)
+3aAK Section ``Components versus Attributes'' is not appropriate.
  For example, the aspect that the knowledge of attribute values can be
  used in the method selection is not mentioned.
  (And why do attributes need *two* filter bits?)
  AK: mentioned method selection, and changed to *one* filter bit
+5AK It should be stated which of the examples shown in the chapter are
  ``ficticious'' (not part of the GAP library) and which are taken from
  the library.
  For example, there is an example which introduces a new property
  `IsMGroup', whereas the GAP library uses the similar but different filter
  `IsMonomial'.
+2MN The description of categories vs. properties in ``Adding new Concepts''
  is not correct.
  TODO: What's namely is wrong there? AK asked Thomas 
+4AK Again there are cross-references to undocumented functions
  (NormalizerOp, GroupByGenerators).
+5AK overfull box because of a long list label in the ManSection for
  `ArithmeticElementCreator' --how to deal with this?
  AK: the problem vanished by itself
+6AK Finally, the two sections ``Adding new Concepts'' and ``Creating 
  Own Arithmetic Objects'' both start with ``finally''. AK: fixed.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 81: An Example -- Residue Class Rings
% File: ./xtndxmpl.xml (line 10)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 10, 2008
% Comments:
-4 cross-references to undocumented functions IsGeneratorsOfMagmaWithInverses
  and IsInternalRep
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 82: An Example -- Designing Arithmetic Operations
% File: ./arith.xml (line 10)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 10, 2008
% Comments:
+3aAK Wouldn't `ArithmeticElementCreator' simplify the example?
 (AK: left example as it is, added cross-ref to ArithmeticElementCreator
 which may be useful togetstarted but does not permit to exploit all 
 potential features).
+4AK cross-reference to the undocumented function (IsLieObject)
 (AK: it's already documented, made a proper cross-reference).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 83: Library Files
% File: ./libform.xml (line 10)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 10, 2008
% Comments:
+3aAK How much of the section ``File Structure'' will be correct for GAP 4.5?
  AK: section removed, partly used in the appendix to the example package.
+3aAK Which conventions are just recommended, what is compulsory?
  AK: explained in the Example package what is compulsory if gapmacro.tex is 
  used.
+3aAK Will revision entries in the format as created by cvs be supported
  also in the forthcoming library files? AK: not all version control systems
  support this. DisplayRevision will not make sense without revision numbers
  so it's documentation is withdrawn and the code moved to obsolete.gd.
+3AK The function headers which had been used by the manual builder
  are still present but are no longer needed.
  One can use them for `grep'ing information, as in the old times,
  but this might be not reliable in the future.
  Should an analogous tool for extracting this info from GAPDoc based
  library files be described here?
  Or should this section be moved to the document about the gapmacro.tex
  manual format?
  (Or perhaps to the documentation of its manual builder?)
  AK: so far I explained in the Example package what is compulsory if 
  gapmacro.tex is used. This is sufficient for the moment.
+2AK Add (to Example package's manual) a cross-reference to the document 
  ``The gapmacro.tex Manual Format'' (see above) in the web, as soon as 
  its URL is fixed (AK: moved to the Example package TODOs).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Former chapter 85: Writing a GAP Package - REMOVED
% now moved to the Appendix for the "Example" package.
% Chapters listed below renumbered (1--);
% File: ./gappkg.xml (line 11)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 10, 2008
% Comments:
+3aAK The `Example' package contains an appendix chapter ``Hints for writing a
  GAP package'', the GAP Reference Manual contains a chapter ``GAP Packages'',
  and the developers' manual in `doc/dev' also intends to contain a chapter
  on packages. It would be good to have only one descriptions, in order to 
  avoid contradictions. Where is the right place for the various bits of 
  information?
  AK: * "GAP Packages" stays in the reference manual.
      * "Writing a GAP Package" merged with the example package, 
        cross-referenced from "GAP Packages" chapter.
      * In the future, technical info (e.g. package loading mechanism 
        internals) should go to the GAP.dev manual
+2AK Add a cross-reference to the document ``The gapmacro.tex Manual Format''
  (see above) in the web, as soon as its URL is fixed (AK: moved to TODOs
  for the Example package).
+3aAK Is the example in section ``An Example of a GAP Package'' UNIX specific?
  (There is a comment line with this statement.)
  NO, the example is not UNIX-specific, and the comment can no longer be found.
+2AK The template file for `PackageInfo.g' is mentioned twice, but it is not
  specified where this file can be found.
  (Add an URL.)
+2AK The function `ValidatePackageInfo' should become documented here.AK: yes, 
  it's now documented in the chapter GAP Packages of the reference manual.
+2AK Add a remark to section ``Declaration and Implementation Part'' that it is
  not safe to *call* functions from (needed) packages during package loading.
  (Perhaps it will become necessary to add this functionality, via a function
  that can be added to a package and which is guaranteed to be called after
  the package and all needed packages have been loaded.)
+2AK The global variable `GAPInfo' should become documented in GAP 4.5
  (in the Reference Manual), then a proper cross-reference to this variable
  can be added in section `Version Numbers'.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 84: Interface to the GAP Help System
% File: ./helpintf.xml (line 15)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 10, 2008
% Comments:
+3a Why is the function HELP_ADD_BOOK written with capitals only?
    (let it be called as it is, it's undocumented)
+4AK the undocumented function HELP_VIEWER_INFO could be documented here
  AK: documentation was there, I've organised it into a proper ManSection.
+2AK add a cross-reference to the document ``The gapmacro.tex Manual Format''
  (see above) in the web, as soon as its URL is fixed.
  AK: instead of URL, this document is a part of the tools archive.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 85: Function-Operation-Attribute Triples
% File: ./foa.xml (line 10)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 10, 2008
% Comments:
+3a Besides the question whether the current implementation of functions via
  `KeyDependentOperation', `InParentFOA', `OrbitsishOperation',
  `OrbitishFO' is really a good idea for the GAP library (and thus worth
  being documented),
  I would like to ask whether these functions are interesting for GAP
  extensions (Answer: YES, leave it documented, this may be valuable).
  If they are not then one could regard this chapter as internal
  documentation of the current code, in the library files in question.
  What is the point in having a manual chapter with this contents?
  (I have moved the text from the `.xml' file to the `lib' files in
  question, so it would be easy to omit the section contents without losing
  the documentation of the code.)
-4 Lots of undocumented variables are referenced,
  such as `SylowSubgroupOp', `ComputedSylowSubgroups' and `BlocksAttr'.
  Should these variables be documented?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 86: Weak Pointers
% File: ./weakptr.xml (line 14)
% Who: Thomas Breuer
% Started: August 10, 2008
% Finished: August 10, 2008
% Comments:
+3aAK Weak pointers should not be regarded as ``only for internal use''.
  For example, recently they turned out to be very useful in a package
  about homology (by Barakat et al.): AK: reduced the level of warning.
-4 cross-references to the undocumented functions MarkBagWeakly, MARK_BAG,
  IS_WEAK_DEAD_BAG, ListsFamily.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 87: Stabilizer Chains (preliminary)
% File: ./stbchain.xml (line 10)
% Who: Thomas Breuer
% Started: August 10, 2008
% Finished: August 10, 2008
% Comments:
+3 The chapter is marked as ``preliminary'', but why?
  AK: The chapter is no longer marked as preliminary.
+3 untypical text, including several pseudo code listings
  (what is the recommended way to write this down?)
  and a lot of unnecessarily complicated math. formulae
  (which I have replaced)
  AK: I've removed line numbers from listings. They do not
  help readability, while the <Listing> element is properly
  used, and the text mentions that this is a pseudocode.
-4 lots of references to undocumented functions,
  even examples involving the undocumented function `Partition'
-5 Section ``Stabilizer Chains for Automorphisms Acting on Enumerators''
  mentions that the code ``is not yet included in the GAP library''.
  What is the status of this code?
  AK: Alexander H. told me: "This is not in the library (as it always was 
  experimental and had a lot of rough ends). The proper framework now would 
  be to use the genss package and it should be limited not only to p groups"
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Appendix A: Changes from Earlier Versions - REMOVED
% File: ./changes.xml
% Who: Thomas Breuer (when it was part of the tutorial's preface), then AK
% Started: January 24, 2008
% Finished: August 06, 2008
% Comments:
+3cAK Is it really a good idea to include release specific information such as
  a detailed list of changes in the beginning of the Tutorial?
  (This information is available on the GAP web pages,
  and I could imagine a collection of changes w.r.t. older versions being
  part of the Reference Manual --really as a reference-- for example as an
  appendix chapter.) I have not tried to beautify the changes list, since 
  the next release will anyhow have a new list.
  TODO: indeed it should be an appendix, references to it must be updated
+2AK References to GAP functions and packages should be proper links.
-5 Put a proper URL referring to the "Migrating to GAP4" document on the 
 GAP website.
+1AK A list of main changes for package authors should be available (for the
 beta, it is placed in the preface to the beta-release, later may be moved to
 the example package as a section on upgrading packages from GAP 4.4 to GAP 4.5)
+1AK Use preface for GAP 4.5 beta for a new section in the Example package
 manual about upgrading packages from GAP 4.4 to GAP 4.5 (AK: Done in Example 3.1)
+1 A list of main changes from 4.4 to 4.5 should be added before the release
 (This is now the new doc/changes manual) 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  Tutorial
%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 1: Preface
% File: ./preface.xml (line 13)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 06, 2008
% Comments:
+1AK Move the relevant parts to the Reference Manual,
  put only a very short paragraph into the Tutorial.
  (left only the introduction and two sections ("The GAP system" and
  "Further Information about GAP") reused from the preface to
  the reference manual using GAPDoc labels.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 2: A First Session with GAP
% File: ./introduc.xml (line 18)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 06, 2008
% Comments:
+2AK First typewriter style paragraph:
  The text claims that the examples are indented.  Are they?
  (Should this statement be omitted?)
  AK: updated the statement.
-6 Should we replace ``Read Evaluate Print'' by ``Read Evaluate View''?
  (In the preface, this term actually ors.)
-5AK For three summary paragraphs, the heading ``Summary'' is commented out.
  In the chapters about groups and operations, ``Summary'' headings
  appear.                     
  The other chapters have no summary paragraphs.
  Is this o.k.?
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 3: Lists and Records
% File: ./lists.xml (line 18)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 06, 2008
% Comments:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 4: Functions
% File: ./function.xml (line 18)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 06, 2008
% Comments:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 5: Groups and Homomorphisms
% File: ./group.xml (line 18)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 06, 2008
% Comments:
-4 reference to undocumented function ComputedSylowSubgroups
+2AK The term ``actions package'' occurs several times.
  (It does not mean a GAP package.). AK: clarified this. 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 6: Vector Spaces and Algebras
% File: ./algvspc.xml (line 10)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 06, 2008
% Comments:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 7: Domains
% File: ./domain.xml (line 18)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 06, 2008
% Comments:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 8: Operations and Methods
% File: ./opers.xml (line 15)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 06, 2008
% Comments:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  Removed from the manual
%%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 9 (Tutorial): Migrating to GAP 4
% File: ./migrat.xml (line 10)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 06, 2008
% Comments:
+2 Please confirm the status of the following:
  This chapter does not fit into a GAP 4 Tutorial,
  therefore it has been removed from it.
  I propose to turn the chapter into a self-contained document
  that is available only in the GAP 3 part of the GAP website,
  in PDF and HTML format. (A preliminary version is `doc/migratedoc.tex'; 
  shorten the copyright notice?)
+3a The only part of this chapter that is interesting for GAP 4 users
  is the section on ``Naming Conventions''.
  Put it somewhere?
  (Or is the contents already available somewhere else?)
  AK: placed it in the ``Functions'' chapter of the Reference Manual,
  documented also "As" and "With" conventions, added more cross-references.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Chapter 2 (Extending GAP): The gapmacro.tex Manual Format
% File: ./document.xml (line 36)
% Who: Thomas Breuer
% Started: January 24, 2008
% Finished: August 10, 2008
% Comments:
+3AK Please confirm the status of the following:
  It does not make sense to have a GAPDoc version of this chapter;
  note that it is self-referential.
  I propose to turn the chapter into a self-contained document
  that is available in the GAP website, in PDF and HTML format.
  (A preliminary version is `doc/gapmacrodoc.tex';
  shorten the copyright notice?)
  AK: this document is now supplied with GAP in the tools archive.
+3AK The text refers to the ``manual checker tools'', to the ``manual builder'',
  and to the ``HTML converter''. The relevant code and its documentation 
  should be kept in the same place as this chapter. Or should we just throw 
  this away? (Which packages do still need this stuff?)
  AK: Some packages may need it, keep it at least for now in the tools archive.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%