This change began with recognizing DeclareSynonym and cascaded to involve a
number of related changes. First, in order for DeclareSynonym to be useful,
there must be some way to specify the manual item type for the identifier
being declared. Hence this change also implements a @ItemType command to allow
that. (Adding @ItemType also achieves the main recommendaton in issue gap-packages#74.)

In documenting these two changes, it seemed best to have their documentation
in gap/Parser.gi next to their implementation, on the general principle that
documentation should be as close to the relevant code as possible. Further, in
an effort at dogfooding, it seemed best for that documentation to be in
AutoDoc format. This turned into a change in which doc/Comments.xml became
doc/Comments.autodoc and became much smaller, as most of the documentation
moved to gap/Parser.gi and gap/Markdown.gi.

Being able to use Autodoc to document most of Autodoc then entailed a few
other changes. First, Markdown-like syntax with backticks for code expressions
that would suppress the AutoDoc behavior of the quoted items was
essential. Second, it was useful to add an @Index command for generating the
index entries. And third, reassembling Chapter 2 of the manual from portions
in several files necessitated allowing sections and subsections inside a chunk
to move with that chunk, and be inserted into the chapter or section at the
point at which the chunk was inserted.

(An implementation note on this last change. It was greatly facilitated by
merging the current_item ambient variable with the context_stack. The
current_item was in essence functioning as the top of the stack anyway. Having
the top of the stack in one variable and the rest of the stack in another made
some of the code a bit confusing. This change touched a large fraction of code
in the Parser, but in the end improved the locality of reference in that code
considerably, and I think made it clearer what is going on during parsing.)

In the course of these changes, it was trivial to add the ability to have code
blocks which add at the current location, with no @insertcode necessary. So
that change is included here as well.

Finally, with so many changes, extensive testing was clearly critical. So this
commit also beefs up the worksheet.tst, and adds a new test dogfood.tst which
consists of generating the AutoDoc manual and verifying that it matches the
expected contents of the manual.

I do understand that this turned into more of a complex of changes than would
ordinarily be packed into a single commit. But this portmanteau seemed a
fairly natural stable point in which the motivating changes
(DeclareSynonym/@ItemType) are made, documented, and tested in a cohesive way.

I would be happy to do the work of separating this out into more than one
successive change to AutoDoc if that would help advance these changes. Please
just let me know what pieces you'd like it carved up into, and in what order.

Thanks very much for your consideration.

Resolves: gap-packages#60, gap-packages#74, gap-packages#174, gap-packages#175, gap-packages#176, gap-packages#177, gap-packages#178.
It also makes further progress on gap-packages#48, in adding the backtick code quotes, and
on the testing issues gap-packages#57 and gap-packages#152. It also touches on Issue gap-packages#112, in that to
use makedoc.g in testing, I needed to add a backdoor to prevent it from
QUITting. Note also that the motivation in the original post for Issue gap-packages#144
was the need to document DeclareSynonym.

This change began with recognizing DeclareSynonym and cascaded to involve a
number of related changes. First, in order for DeclareSynonym to be useful,
there must be some way to specify the manual item type for the identifier
being declared. Hence this change also implements a @ItemType command to allow
that. (Adding @ItemType also achieves the main recommendaton in issue gap-packages#74.)

In documenting these two changes, it seemed best to have their documentation
in gap/Parser.gi next to their implementation, on the general principle that
documentation should be as close to the relevant code as possible. Further, in
an effort at dogfooding, it seemed best for that documentation to be in
AutoDoc format. This turned into a change in which doc/Comments.xml became
doc/Comments.autodoc and became much smaller, as most of the documentation
moved to gap/Parser.gi and gap/Markdown.gi.

Being able to use Autodoc to document most of Autodoc then entailed a few
other changes. First, Markdown-like syntax with backticks for code expressions
that would suppress the AutoDoc behavior of the quoted items was
essential. Second, it was useful to add an @Index command for generating the
index entries. And third, reassembling Chapter 2 of the manual from portions
in several files necessitated allowing sections and subsections inside a chunk
to move with that chunk, and be inserted into the chapter or section at the
point at which the chunk was inserted.

(An implementation note on this last change. It was greatly facilitated by
merging the current_item ambient variable with the context_stack. The
current_item was in essence functioning as the top of the stack anyway. Having
the top of the stack in one variable and the rest of the stack in another made
some of the code a bit confusing. This change touched a large fraction of code
in the Parser, but in the end improved the locality of reference in that code
considerably, and I think made it clearer what is going on during parsing.)

In the course of these changes, it was trivial to add the ability to have code
blocks which add at the current location, with no @insertcode necessary. So
that change is included here as well.

Finally, with so many changes, extensive testing was clearly critical. So this
commit also beefs up the general worksheet test, and moreover the migration to
documenting the second chapter of the manual with AutoDoc makes the self-test
(dogfood.tst) achieve much greater coverage.

I do understand that this turned into more of a complex of changes than would
ordinarily be packed into a single commit. But this portmanteau seemed a
fairly natural stable point in which the motivating changes
(DeclareSynonym/@ItemType) are made, documented, and tested in a cohesive way.

I would be happy to do the work of separating this out into more than one
successive change to AutoDoc if that would help advance these changes. Please
just let me know what pieces you'd like it carved up into, and in what order.

Thanks very much for your consideration.

Resolves: gap-packages#60, gap-packages#74, gap-packages#174, gap-packages#175, gap-packages#176, gap-packages#177, gap-packages#178.
It also makes further progress on gap-packages#48, in adding the backtick code quotes, and
on the testing issues gap-packages#57 and gap-packages#152. Note also that the motivation in the
original post for Issue gap-packages#144 was the need to document DeclareSynonym.

This change began with recognizing DeclareSynonym and cascaded to involve a
number of related changes. First, in order for DeclareSynonym to be useful,
there must be some way to specify the manual item type for the identifier
being declared. Hence this change also implements a @ItemType command to allow
that. (Adding @ItemType also achieves the main recommendaton in issue gap-packages#74.)

In documenting these two changes, it seemed best to have their documentation
in gap/Parser.gi next to their implementation, on the general principle that
documentation should be as close to the relevant code as possible. Further, in
an effort at dogfooding, it seemed best for that documentation to be in
AutoDoc format. This turned into a change in which doc/Comments.xml became
doc/Comments.autodoc and became much smaller, as most of the documentation
moved to gap/Parser.gi and gap/Markdown.gi.

Being able to use Autodoc to document most of Autodoc then entailed a few
other changes. First, Markdown-like syntax with backticks for code expressions
that would suppress the AutoDoc behavior of the quoted items was
essential. Second, it was useful to add an @Index command for generating the
index entries. And third, reassembling Chapter 2 of the manual from portions
in several files necessitated allowing sections and subsections inside a chunk
to move with that chunk, and be inserted into the chapter or section at the
point at which the chunk was inserted.

(An implementation note on this last change. It was greatly facilitated by
merging the current_item ambient variable with the context_stack. The
current_item was in essence functioning as the top of the stack anyway. Having
the top of the stack in one variable and the rest of the stack in another made
some of the code a bit confusing. This change touched a large fraction of code
in the Parser, but in the end improved the locality of reference in that code
considerably, and I think made it clearer what is going on during parsing.)

In the course of these changes, it was trivial to add the ability to have code
blocks which add at the current location, with no @insertcode necessary. So
that change is included here as well.

Finally, with so many changes, extensive testing was clearly critical. So this
commit also beefs up the worksheet.tst, and adds a new test dogfood.tst which
consists of generating the AutoDoc manual and verifying that it matches the
expected contents of the manual.

I do understand that this turned into more of a complex of changes than would
ordinarily be packed into a single commit. But this portmanteau seemed a
fairly natural stable point in which the motivating changes
(DeclareSynonym/@ItemType) are made, documented, and tested in a cohesive way.

I would be happy to do the work of separating this out into more than one
successive change to AutoDoc if that would help advance these changes. Please
just let me know what pieces you'd like it carved up into, and in what order.

Thanks very much for your consideration.

Resolves: gap-packages#60, gap-packages#74, gap-packages#174, gap-packages#175, gap-packages#176, gap-packages#177, gap-packages#178.
It also makes further progress on gap-packages#48, in adding the backtick code quotes, and
on the testing issues gap-packages#57 and gap-packages#152. It also touches on Issue gap-packages#112, in that to
use makedoc.g in testing, I needed to add a backdoor to prevent it from
QUITting. Note also that the motivation in the original post for Issue gap-packages#144
was the need to document DeclareSynonym.

This change began with recognizing DeclareSynonym and cascaded to involve a
number of related changes. First, in order for DeclareSynonym to be useful,
there must be some way to specify the manual item type for the identifier
being declared. Hence this change also implements a @ItemType command to allow
that. (Adding @ItemType also achieves the main recommendaton in issue gap-packages#74.)

In documenting these two changes, it seemed best to have their documentation
in gap/Parser.gi next to their implementation, on the general principle that
documentation should be as close to the relevant code as possible. Further, in
an effort at dogfooding, it seemed best for that documentation to be in
AutoDoc format. This turned into a change in which doc/Comments.xml became
doc/Comments.autodoc and became much smaller, as most of the documentation
moved to gap/Parser.gi and gap/Markdown.gi.

Being able to use Autodoc to document most of Autodoc then entailed a few
other changes. First, Markdown-like syntax with backticks for code expressions
that would suppress the AutoDoc behavior of the quoted items was
essential. Second, it was useful to add an @Index command for generating the
index entries. And third, reassembling Chapter 2 of the manual from portions
in several files necessitated allowing sections and subsections inside a chunk
to move with that chunk, and be inserted into the chapter or section at the
point at which the chunk was inserted.

(An implementation note on this last change. It was greatly facilitated by
merging the current_item ambient variable with the context_stack. The
current_item was in essence functioning as the top of the stack anyway. Having
the top of the stack in one variable and the rest of the stack in another made
some of the code a bit confusing. This change touched a large fraction of code
in the Parser, but in the end improved the locality of reference in that code
considerably, and I think made it clearer what is going on during parsing.)

In the course of these changes, it was trivial to add the ability to have code
blocks which add at the current location, with no @insertcode necessary. So
that change is included here as well.

Finally, with so many changes, extensive testing was clearly critical. So this
commit also beefs up the worksheet.tst, and adds a new test dogfood.tst which
consists of generating the AutoDoc manual and verifying that it matches the
expected contents of the manual.

I do understand that this turned into more of a complex of changes than would
ordinarily be packed into a single commit. But this portmanteau seemed a
fairly natural stable point in which the motivating changes
(DeclareSynonym/@ItemType) are made, documented, and tested in a cohesive way.

I would be happy to do the work of separating this out into more than one
successive change to AutoDoc if that would help advance these changes. Please
just let me know what pieces you'd like it carved up into, and in what order.

Thanks very much for your consideration.

Resolves: gap-packages#60, gap-packages#74, gap-packages#174, gap-packages#175, gap-packages#176, gap-packages#177, gap-packages#178.
It also makes further progress on gap-packages#48, in adding the backtick code quotes, and
on the testing issues gap-packages#57 and gap-packages#152. It also touches on Issue gap-packages#112, in that to
use makedoc.g in testing, I needed to add a backdoor to prevent it from
QUITting. Note also that the motivation in the original post for Issue gap-packages#144
was the need to document DeclareSynonym.