examples.xml is invalid, compiling manual fails
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>
Comments (5)
-
reporter -
reporter To fix this, I suggest replacing
ManSection
bySubsection
, 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>
-
reporter ... aaand I created a PR to fix this: https://bitbucket.org/jdebeule/fining/pull-requests/1
-
repo owner 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.
-
repo owner - changed status to resolved
Resolved using fix of Max
- Log in to comment
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.