Skip to content

Report source positions for Markdown errors #361

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fingolfin merged 1 commit into from
Mar 17, 2026
Merged

Report source positions for Markdown errors #361

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 27 additions & 29 deletions gap/DocumentationTree.gi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,7 +251,8 @@ InstallMethod( DocumentationChunk, [ IsTreeForDocumentation, IsString ],
if IsBound( tree!.chunks.( name ) ) then
return tree!.chunks.( name );
fi;
node := rec( content := [ ] );
node := rec( content := [ ],
content_source_positions := [ ] );
ObjectifyWithAttributes( node, TheTypeOfDocumentationTreeChunkNodes,
Label, name );
node!.is_defined := false;
Expand All @@ -266,9 +267,12 @@ InstallMethod( DocumentationManItem, [ ],
local node;

node := rec( description := [ ],
return_value := [ ] );
description_source_positions := [ ],
return_value := [ ],
return_value_source_positions := [ ] );
ObjectifyWithAttributes( node, TheTypeOfDocumentationTreeNodesForManItem );
node!.content := node!.description;
node!.content_source_field := "description_source_positions";
return node;
end );

Expand All @@ -280,7 +284,8 @@ InstallMethod( DocumentationGroup, [ IsTreeForDocumentation, IsString ],
if IsBound( tree!.cached_nodes_by_label.( name ) ) then
return tree!.cached_nodes_by_label.( name );
fi;
group := rec( content := [ ] );
group := rec( content := [ ],
content_source_positions := [ ] );
ObjectifyWithAttributes( group, TheTypeOfDocumentationTreeNodesForGroup,
Label, name );
tree!.cached_nodes_by_label.( name ) := group;
Expand Down Expand Up @@ -414,11 +419,13 @@ end );
#############################################

BindGlobal( "AUTODOC_ConvertHeadingToGAPDocXML",
function( heading )
function( heading, source_position )
local converted_heading;

converted_heading :=
AUTODOC_ConvertMarkdownToGAPDocXML( [ NormalizedWhitespace( heading ) ] );
converted_heading := AUTODOC_ConvertMarkdownToGAPDocXML(
[ NormalizedWhitespace( heading ) ],
[ source_position ]
);
if not ForAll( converted_heading, IsString ) then
Error( "headings must convert to inline GAPDoc XML" );
fi;
Expand All @@ -429,18 +436,20 @@ end );

BindGlobal( "AUTODOC_WriteStructuralNode",
function( node, element_name, stream )
local heading;
local heading, title_source_position;

if ForAll( node!.content, IsEmptyNode ) then
return false;
fi;

if IsBound( node!.title_string ) then
heading := NormalizedWhitespace( node!.title_string );
title_source_position := node!.title_string_source_position;
else
heading := ReplacedString( node!.name, "_", " " );
title_source_position := fail;
fi;
heading := AUTODOC_ConvertHeadingToGAPDocXML( heading );
heading := AUTODOC_ConvertHeadingToGAPDocXML( heading, title_source_position );

AppendTo( stream, "<", element_name, " Label=\"", Label( node ), "\">\n" );
AppendTo( stream, "<Heading>", heading, "</Heading>\n\n" );
Expand Down Expand Up @@ -491,7 +500,11 @@ BindGlobal( "WriteChunks",
fi;
AppendTo( chunks_stream, "<#GAPDoc Label=\"", current_chunk_name, "\">\n" );
if IsBound( current_chunk!.content ) then
WriteDocumentation( current_chunk!.content, chunks_stream );
AUTODOC_WriteDocumentationListWithSource(
current_chunk!.content,
current_chunk!.content_source_positions,
chunks_stream
);
fi;
AppendTo( chunks_stream, "\n<#/GAPDoc>\n" );
od;
Expand Down Expand Up @@ -566,29 +579,14 @@ InstallMethod( WriteDocumentation, [ IsList, IsStream ],
local current_string_list, i, FlushConvertedStrings;

FlushConvertedStrings := function()
local converted_string_list, in_cdata, item;
if current_string_list = [ ] then
return;
fi;
converted_string_list := AUTODOC_ConvertMarkdownToGAPDocXML( current_string_list );
in_cdata := false;
for item in converted_string_list do
if not IsString( item ) then
WriteDocumentation( item, filestream );
continue;
fi;
if AUTODOC_LineStartsCDATA( item ) then
in_cdata := true;
fi;
if in_cdata = true then
AppendTo( filestream, Chomp( item ), "\n" );
else
WriteDocumentation( item, filestream );
fi;
if AUTODOC_LineEndsCDATA( item ) then
in_cdata := false;
fi;
od;
AUTODOC_WriteStringListWithSource(
current_string_list,
fail,
filestream
);
current_string_list := [ ];
end;

Expand Down
100 changes: 83 additions & 17 deletions gap/Markdown.gi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,15 +47,24 @@ end );

##
BindGlobal( "AUTODOC_ConvertInlineBackticksInLine",
function( string, keyword_set )
function( string, keyword_set, source_position )
local opening_pos, closing_pos, inline_content, tag_name, search_string;

while PositionSublist( string, "`" ) <> fail do
opening_pos := PositionSublist( string, "`" );
search_string := string{ [ opening_pos + 1 .. Length( string ) ] };
closing_pos := PositionSublist( search_string, "`" );
if closing_pos = fail then
Error( "did you forget some `" );
if source_position = fail then
Error( "did you forget some `" );
fi;
Error(
"did you forget some `,\n",
"at ",
source_position.filename,
":",
source_position.line
);
fi;
closing_pos := opening_pos + closing_pos;

Expand Down Expand Up @@ -94,12 +103,21 @@ end );

##
BindGlobal( "AUTODOC_ConvertFencedMarkdownBlocks",
function( string_list )
local i, converted_string_list, skipped, trimmed_line,
function( arg )
local converted_source_positions, converted_string_list, i, skipped,
string_list, trimmed_line,
fence_char, fence_length, info_string, fence_element, code_block,
fence_content;
fence_content, source_positions;

string_list := arg[ 1 ];
if Length( arg ) > 1 then
source_positions := arg[ 2 ];
else
source_positions := ListWithIdenticalEntries( Length( string_list ), fail );
fi;

converted_string_list := [ ];
converted_source_positions := [ ];
i := 1;
skipped := false;
while i <= Length( string_list ) do
Expand All @@ -108,6 +126,7 @@ BindGlobal( "AUTODOC_ConvertFencedMarkdownBlocks",
fi;
if skipped = true then
Add( converted_string_list, string_list[ i ] );
Add( converted_source_positions, source_positions[ i ] );
if AUTODOC_LineEndsCDATA( string_list[ i ] ) then
skipped := false;
fi;
Expand Down Expand Up @@ -146,6 +165,7 @@ BindGlobal( "AUTODOC_ConvertFencedMarkdownBlocks",
od;
Add( converted_string_list,
DocumentationVerbatim( fence_element, rec( ), fence_content ) );
Add( converted_source_positions, source_positions[ i - Length( fence_content ) - 1 ] );
if code_block = true then
i := i + 1;
continue;
Expand All @@ -154,10 +174,14 @@ BindGlobal( "AUTODOC_ConvertFencedMarkdownBlocks",
fi;
fi;
Add( converted_string_list, string_list[ i ] );
Add( converted_source_positions, source_positions[ i ] );
i := i + 1;
od;

return converted_string_list;
return rec(
items := converted_string_list,
source_positions := converted_source_positions
);
end );

##
Expand All @@ -181,10 +205,11 @@ end );

##
BindGlobal( "AUTODOC_ConvertMarkdownStringsToGAPDocXML",
function( string_list )
function( string_list, source_positions )
local i, current_list, current_string, max_line_length,
current_position, already_in_list, command_list_with_translation, beginning,
commands, position_of_command, insert, beginning_whitespaces, temp, string_list_temp, skipped,
commands, opening_source_position, position_of_command, insert,
beginning_whitespaces, temp, string_list_temp, skipped,
already_inserted_paragraph, in_list, in_item, converted_string_list,
keyword_set;

Expand All @@ -193,7 +218,11 @@ BindGlobal( "AUTODOC_ConvertMarkdownStringsToGAPDocXML",
keyword_set := Set( ALL_KEYWORDS() );
AUTODOC_ForEachNonCDATALine( string_list, function( i )
string_list[ i ] :=
AUTODOC_ConvertInlineBackticksInLine( string_list[ i ], keyword_set );
AUTODOC_ConvertInlineBackticksInLine(
string_list[ i ],
keyword_set,
source_positions[ i ]
);
end );

## Check for paragraphs by turning an empty string into <P/>
Expand Down Expand Up @@ -245,13 +274,17 @@ BindGlobal( "AUTODOC_ConvertMarkdownStringsToGAPDocXML",
fi;
if already_in_list = false then
Add( string_list, "<Item>", i );
Add( source_positions, fail, i );
Add( string_list, "<List>", i );
Add( source_positions, fail, i );
i := i + 2;
string_list[ i ] := string_list[ i ]{[ current_position + 2 .. Length( string_list[ i ] ) ]};
already_in_list := true;
else
Add( string_list, "<Item>", i );
Add( source_positions, fail, i );
Add( string_list, "</Item>", i );
Add( source_positions, fail, i );
i := i + 2;
string_list[ i ] := string_list[ i ]{[ current_position + 2 .. Length( string_list[ i ] ) ]};
fi;
Expand All @@ -270,14 +303,18 @@ BindGlobal( "AUTODOC_ConvertMarkdownStringsToGAPDocXML",
elif already_in_list = true and PositionSublist( string_list[ i ], " " ) > current_position then
already_in_list := false;
Add( string_list, "</List>", i );
Add( source_positions, fail, i );
Add( string_list, "</Item>", i );
Add( source_positions, fail, i );
i := i + 2;
fi;
i := i + 1;
od;
if already_in_list = true then
Add( string_list, "</Item>" );
Add( source_positions, fail );
Add( string_list, "</List>" );
Add( source_positions, fail );
fi;
current_position := current_position + 1;
od;
Expand Down Expand Up @@ -320,21 +357,35 @@ BindGlobal( "AUTODOC_ConvertMarkdownStringsToGAPDocXML",

for commands in command_list_with_translation do
beginning := true;
opening_source_position := fail;
AUTODOC_ForEachNonCDATALine( string_list, function( i )
while PositionSublist( string_list[ i ], commands[ 1 ] ) <> fail do
position_of_command := PositionSublist( string_list[ i ], commands[ 1 ] );
if beginning = true then
insert := Concatenation( "<", commands[ 2 ], ">" );
opening_source_position := source_positions[ i ];
else
insert := Concatenation( "</", commands[ 2 ], ">" );
opening_source_position := fail;
fi;
string_list[ i ] := INSERT_IN_STRING_WITH_REPLACE( string_list[ i ], insert, position_of_command, Length( commands[ 1 ] ) );
beginning := not beginning;
od;
end );

if beginning = false then
Error( "did you forget some ", commands[ 1 ] );
if opening_source_position = fail then
Error( "did you forget some ", commands[ 1 ] );
fi;
Error(
"did you forget some ",
commands[ 1 ],
",\n",
"at ",
opening_source_position.filename,
":",
opening_source_position.line
);
fi;
od;

Expand All @@ -343,27 +394,42 @@ end );

##
InstallGlobalFunction( AUTODOC_ConvertMarkdownToGAPDocXML,
function( string_list )
local converted_items, current_string_list, item, FlushStringList;
function( string_list, source_positions )
local converted_blocks, converted_items, current_source_positions,
current_string_list, i, FlushStringList;

if source_positions = fail then
source_positions := ListWithIdenticalEntries( Length( string_list ), fail );
fi;

converted_items := [ ];
current_string_list := [ ];
current_source_positions := [ ];

FlushStringList := function()
if current_string_list = [ ] then
return;
fi;
Append( converted_items,
AUTODOC_ConvertMarkdownStringsToGAPDocXML( current_string_list ) );
AUTODOC_ConvertMarkdownStringsToGAPDocXML(
current_string_list,
current_source_positions
) );
current_string_list := [ ];
current_source_positions := [ ];
end;

for item in AUTODOC_ConvertFencedMarkdownBlocks( string_list ) do
if IsString( item ) then
Add( current_string_list, item );
converted_blocks := AUTODOC_ConvertFencedMarkdownBlocks(
string_list,
source_positions
);
for i in [ 1 .. Length( converted_blocks.items ) ] do
if IsString( converted_blocks.items[ i ] ) then
Add( current_string_list, converted_blocks.items[ i ] );
Add( current_source_positions, converted_blocks.source_positions[ i ] );
else
FlushStringList();
Add( converted_items, item );
Add( converted_items, converted_blocks.items[ i ] );
fi;
od;
FlushStringList();
Expand Down
Loading
Loading