Add syntax for references

doc/Comments.xml

@@ -739,6 +739,34 @@ can be important.</E>
 
 </Subsection>
 
+<Subsection Label="MarkdownExtensionRef">
+  <Heading>References</Heading>
+
+  One can create a reference to a documented declaration (function, operation, etc)
+  by writing a hash symbol (#) in front of the name.  Example:
+
+<Listing><![CDATA[
+#! See also #AutoDocWorksheet.
+]]></Listing>
+
+  This produces the following output:<Br/>
+  See also <Ref Func="AutoDocWorksheet" />.
+  <P/>
+
+  For references to operations, attributes and properties,
+  the argument filters must be included,
+  as a comma-separated list in square brackets.
+  For example, if an operation is declared as
+<Listing><![CDATA[
+DeclareOperation( "DoSomething", [ IsInt, IsRat ] );
+]]></Listing>
+  then we can refer to it by writing
+<Listing><![CDATA[
+#! See also #DoSomething[IsInt,IsRat].
+]]></Listing>
+
+</Subsection>
+
 </Section>
 
 </Chapter>

gap/Markdown.gi

@@ -26,7 +26,9 @@ InstallGlobalFunction( CONVERT_LIST_OF_STRINGS_IN_MARKDOWN_TO_GAPDOC_XML,
     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,
-          already_inserted_paragraph, in_list, in_item;
+          already_inserted_paragraph, in_list, in_item,
+          str, pos, replace_start, replace_end, symbol_start, symbol_end, escape, symbol,
+          args_start, args_end, args, j, ref_tag;
 
     ## Check for paragraphs by turning an empty string into <P/>
 
@@ -181,6 +183,51 @@ InstallGlobalFunction( CONVERT_LIST_OF_STRINGS_IN_MARKDOWN_TO_GAPDOC_XML,
             Error( "did you forget some ", commands[ 1 ] );
         fi;
     od;
+
+    # #foo -> <Ref Subsect="foo" />
+    for i in [ 1 .. Length( string_list ) ] do
+        str := string_list[ i ];
+        pos := Position( str, '#' );
+        while pos <> fail do
+            replace_start := pos;
+            symbol_start := pos + 1;
+            escape := false;
+            for j in [ symbol_start .. Length( str ) ] do
+                if escape then
+                    escape := false;
+                elif str[ j ] = '\\' then
+                    escape := true;
+                elif not ( IsDigitChar( str[ j ] ) or IsAlphaChar( str[ j ] ) or str[ j ] in "@_" ) then
+                    break;
+                fi;
+            od;
+            symbol_end := j - 1;
+            symbol := str{ [ symbol_start .. symbol_end ] };
+            if str[ j ] = '[' then
+                args_start := j + 1;
+                j := Position( str, ']', args_start );
+                if j = fail then
+                    Error( "missing ']'" );
+                fi;
+                args_end := j - 1;
+                args := SplitString( str{ [ args_start .. args_end ] }, "," );
+            else
+                args := fail;
+            fi;
+            replace_end := j;
+            ref_tag := Concatenation( "<Ref Func=\"", symbol, "\" " );
+            if args <> fail then
+                ref_tag := Concatenation( ref_tag, "Label=\"for ",
+                                          JoinStringsWithSeparator( args, ", " ),
+                                          "\" " );
+            fi;
+            ref_tag := Concatenation( ref_tag, "/>" );
+            str := INSERT_IN_STRING_WITH_REPLACE( str, ref_tag, replace_start,
+                                                  replace_end - replace_start + 1 );
+            pos := Position( str, '#' );
+        od;
+        string_list[ i ] := str;
+    od;
 
     return string_list;
 end );

tst/worksheets/general.expected/_Chapter_SomeChapter.xml

@@ -42,6 +42,9 @@ This is <Code>inline code</Code> in a list item.
 </List>
 <P/>
 All of this can <Emph>also</Emph> be <Emph>used</Emph> outside of a <Code>list</Code>.
+<P/>
+We can refer to <Ref Func="AnOperation" Label="for IsInt, IsList" />
+or to <Ref Func="AnOperation" Label="for IsRat" />.
 <ManSection>
   <InfoClass Name="InfoTESTCLASS" />
  <Description>
@@ -50,6 +53,22 @@ An info class
 </ManSection>
 
 
+<ManSection>
+  <Oper Arg="x, y" Name="AnOperation" Label="for IsInt, IsList"/>
+ <Description>
+An operation.
+ </Description>
+</ManSection>
+
+
+<ManSection>
+  <Oper Arg="r" Name="AnOperation" Label="for IsRat"/>
+ <Description>
+An operation.
+ </Description>
+</ManSection>
+
+
 </Section>
 
 

tst/worksheets/general.sheet/worksheet.g

@@ -33,8 +33,20 @@ Print( "(Even though we never use it that way.\n" );
 #! * This is `inline code` in a list item.
 #!
 #! All of this can **also** be __used__ outside of a `list`.
+#!
+#! We can refer to #AnOperation[IsInt,IsList]
+#! or to #AnOperation[IsRat].
 
 #! @Description
 #!   An info class
 DeclareInfoClass("InfoTESTCLASS");
 
+#! @Description
+#!  An operation.
+#! @Arguments x, y
+DeclareOperation( "AnOperation", [ IsInt, IsList ] );
+
+#! @Description
+#!  An operation.
+#! @Arguments r
+DeclareOperation( "AnOperation", [ IsRat ] );