<Example> in <ManSection> does not work

[markusbaumeister]

The following code throws an error (although it is valid GAPDoc-code):

#! <ManSection>
#!   <Filt Name="TestExample" Arg=""/>
#!   <Description>
#! <Example>
#! gap&gt; 1 + 2;
#! 3
#! </Example>
#!  </Description>
#! </ManSection>

This is relevant, since it is sometimes necessary to escape into GAPDoc-syntax, for example in documenting synonyms (which can't be easily classified).

[sebasguts]

I tested the example, and it is displayed nicely in both pdf and html files. Can you please attach the error message?

[sebasguts]

Please note that if you do this, you need to have a @Chapter and an @Section open, since ManItems are basically subsections.

[markusbaumeister]

I forgot about @chapter and @section which led me to messing up my minimal example. Sorry about that :(.
The original problem appeared because of an empty line in the example environment:

#! <ManSection>
#!   <Filt Name="TestExample" Arg=""/>
#!   <Description>
#! <Example>
#! gap&gt; 1 + 2;
#! 3
#! 
#! gap&gt; 2;
#! 2
#! </Example>
#!  </Description>
#! </ManSection>

and gives the error message

#I Checking XML structure . . .
XML Parse Error: Line 5045 Character 1
-----------
<Example>
^
-----------
Wrong element in Example: P
!!! Type 'Show();' to watch the input string in pager - starting with
    line containing error !!!
Error,  called from
ParseError( str, r.start, Concatenation( "Wrong element in ", name, ": ", r.content[Position( l, false )].name ) ); at /opt/gap4r8/pkg/GAPDoc/lib/GAPDoc.gi:99 called from
CheckAndCleanGapDocTree( x, str ) at /opt/gap4r8/pkg/GAPDoc/lib/GAPDoc.gi:157 called from
func( elm ) at /opt/gap4r8/lib/coll.gi:1613 called from
ForAll( r.content, function ( x )
      return CheckAndCleanGapDocTree( x, str );
  end ) at /opt/gap4r8/pkg/GAPDoc/lib/GAPDoc.gi:157 called from
CheckAndCleanGapDocTree( x, str ) at /opt/gap4r8/pkg/GAPDoc/lib/GAPDoc.gi:157 called from
...  at line 414 of makedoc.g
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue

This is not an issue in GAPDoc.

[sebasguts]

Yep. AutoDoc now replaces empty lines with a <P/> tag. This is what is happening here. You could

• Use AutoDoc's @ExampleSession environment
• Remove the empty line
• Make it two example session environments

[sebasguts]

I am not sure this is something we are ever going to fix, actually, since it can be avoided very easily and is probably very hard to fix properly (altough not impossible). I will leave it open for now anyway.

[markusbaumeister]

Using @ExampleSession works but removes colouring of example.

[sebasguts]

Not with the latest version.

[sebasguts]

Also, you can use > instead of >.

[markusbaumeister]

In my version @ExampleSession still removes the colouring if inside an <Example>-environment. Otherwise it works fine and the colouring works.

[sebasguts]

You have to replace the <Example> tag by @ExampleSession completely.

[markusbaumeister]

#! <ManSection>
#!   <Filt Name="TestExample" Arg=""/>
#!   <Description>
#! @ExampleSession
#! gap&gt; 1 + 2;
#! 3
#! 
#! gap&gt; 2;
#! 2
#! @EndExampleSession
#!  </Description>
#! </ManSection>

has no colours (with the current version of AutoDoc).
Oh, if you replace > by > there are colours. Nevermind then :).

[sebasguts]

This one has:

#! <ManSection>
#!   <Filt Name="TestExample" Arg=""/>
#!   <Description>
#! @ExampleSession
#! gap> 1 + 2;
#! 3
#! 
#! gap> 2;
#! 2
#! @EndExampleSession
#!  </Description>
#! </ManSection>

Apparently because AutoDoc adds CDATA tags around the GAP code, and you didn't. I don't know how it should be done, but the above example works.