examples.xml is invalid, compiling manual fails

[Max Horn]

When processing fining's makedoc.g, I get this error

Generating documentation in Directory("/Users/mhorn/Projekte/GAP/repos/pkg/fining/doc/")
#I Composing XML document . . .
#I Parsing XML document . . .
#I Checking XML structure . . .
XML Parse Error: Line 717 Character 1
Original file: /Users/mhorn/Projekte/GAP/repos/pkg/fining/doc/examples.xml, line number 31.
-----------
<ManSection>
^
-----------
ManSection must contain at least one of the following elements:
Func, Oper, Meth, Filt, Prop, Attr, Constr, Var, Fam, InfoClass
!!! Type 'Show();' to watch the input string in pager - starting with
    line containing error !!!
Or 'ShowOrigin();' to look it up in its source file.
...

Indeed, looking at examples.xml, it contains ManSections looking like this, which do not satisfy the GAPDoc specification for ManSections (see https://www.gap-system.org/Manuals/pkg/GAPDoc-1.6/doc/chap3.html#X877B8B7C7EDD09E9)

<ManSection>
<Heading>subspaces of projective spaces</Heading>
<Description>
The following example shows how to create some subspaces of a projective space, test their
incidence, and determine their span and intersection. Projective spaces are considered as 
incidence geometries too. Incidence, to be tested with <F>IsIncident</F> or equivalently <F>\*</F>, 
is symmetrized set-theoretic containment, the latter which can be tested through the operation <F>in</F>.

<Example>
<#Include SYSTEM "../examples/include/examples_sub1.include">
</Example>
</Description>
</ManSection>

[Max Horn]

I noticed that this XML file is rather old, and wondered why the issue did not crop up before. Turns out it's because GAPDoc 1.6 is stricter about enforcing the DTD; the file "compiles" just fine with the older GAPDoc 1.5.1, which was the most recent release since 2012, with 1.6 and 1.6.1 being released just a few months ago.

[Max Horn]

To fix this, I suggest replacing ManSection by Subsection, and removing all the <Description> / </Description> lines. After doing that, the file seems to be accepted by GAPDoc, and then similar issues in other files are revealed, which I think can be fixed in a similar fashion.

Please consider testing fining with a pristine copy of GAP 4.8.8 (which includes GAPDoc 1.6).

On a mostly unrelated note, in that file, you may want to capitalize this heading: <Heading>subgeometries</Heading>

[Max Horn]

... aaand I created a PR to fix this: https://bitbucket.org/jdebeule/fining/pull-requests/1

[Jan De Beule]

Thanks Max for pointing this out! Strangely enough, I cannot reproduce the error with GAP4r8.8 and GAPDoc 1.6:

iMac-El-Capitan:~ jdebeule$ gap4r8 -l "./;/opt/gap4r8"
 ┌───────┐   GAP 4.8.8, 20-Aug-2017, build of 2017-09-18 19:20:45 (CEST)
 │  GAP  │   https://www.gap-system.org
 └───────┘   Architecture: x86_64-apple-darwin15.6.0-gcc-default64
 Libs used:  gmp
 Loading the library and packages ...
LoadPackage("autod Components: trans 1.0, prim 2.1, small* 1.0, id* 1.0
 Packages:   AClib 1.2, Alnuth 3.0.0, AtlasRep 1.5.1, AutPGrp 1.8, 
             CRISP 1.4.4, Cryst 4.1.12, CrystCat 1.1.6, CTblLib 1.2.2, 
             FactInt 1.5.4, FGA 1.3.1, GAPDoc 1.6, IO 4.4.6, IRREDSOL 1.4, 
             LAGUNA 3.7.0, Polenta 1.3.7, Polycyclic 2.11, RadiRoot 2.7, 
             ResClasses 4.6.0, Sophus 1.23, SpinSym 1.5, TomLib 1.2.6, 
             Utils 0.46
 Try '??help' for help. See also '?copyright', '?cite' and '?authors'
gap> LoadPackage("autodoc");
─────────────────────────────────────────────────────────────────────────────
Loading  AutoDoc 2016.12.04 (Generate documentation from GAP source code)
by Sebastian Gutsche (http://wwwb.math.rwth-aachen.de/~gutsche/) and
   Max Horn (http://www.quendi.de/math).
Homepage: https://gap-packages.github.io/AutoDoc
─────────────────────────────────────────────────────────────────────────────
true
gap> AutoDoc("fining");
#I  multiple versions of package fining are present, using the first one
Generating documentation in Directory("./pkg/fining/doc/")
#I Composing XML document . . .
#I Parsing XML document . . .
#I Checking XML structure . . .
#I Text version (also produces labels for hyperlinks):
#I First run, collecting cross references, index, toc, bib and so on . . .
#I Table of contents complete.
#I Producing the index . . .
#I Reading bibliography data files . . . 
#I   BibTeX format: fining
#I   checking and translating to BibXMLext . . .
#I Writing bibliography . . .
#I Second run through document . . .
#I Producing simplified search strings and labels for hyperlinks . . .
#I Constructing LaTeX version and calling pdflatex:
#I Writing LaTeX file, 4 x pdflatex with bibtex and makeindex, 
...

I will merge the from the pull request now.

[Jan De Beule]

Resolved using fix of Max