diff --git a/doc/Comments.autodoc b/doc/Comments.autodoc index 4f04414b..ffa14a20 100644 --- a/doc/Comments.autodoc +++ b/doc/Comments.autodoc @@ -542,8 +542,99 @@ since worksheets do not have a PackageInfo.g file from which this informa Files that have the suffix .autodoc and are listed in the autodoc.files option of , resp. are contained in one of the directories listed in autodoc.scan_dirs, are treated as -&AutoDoc; plain text files. These work exactly like &AutoDoc; comments, except -that lines do not need to (and in fact, should not) start with #!. +standalone &AutoDoc; input files. They are meant for manual text that does not +belong next to a single declaration: chapters, sections, tutorials, worked +examples, index entries, chunks, title-page metadata, and similar prose-heavy +material. + +Conceptually, a .autodoc file uses the same parser as &AutoDoc; +comments, but without the comment marker. In a .autodoc file, lines do +not need to start with #! and in fact usually should not. This makes +.autodoc files one convenient way to replace hand-written XML chapters +when you prefer &AutoDoc;'s command syntax and Markdown-like text features. +However, it is not the only supported style: chapter and section commands inside +source comments remain fully supported, and &AutoDoc; itself still uses that +style in files such as gap/Magic.gd. For the surrounding workflow, see +Chapter . + +The most important difference from declaration comments is that a plain text +file does not document a declaration by adjacency. There is no following +Declare... or InstallMethod statement for &AutoDoc; to inspect. +So commands whose meaning depends on such a declaration only make sense in +source comments immediately before that declaration. + +In practice, this gives the following rule of thumb. + + + + Use source comments beginning with #! to document declarations. + This is the mode for @Description, @Returns, + @Arguments, @Label, @Group, and @ChapterInfo. + + + Use either .autodoc files or source comments for standalone manual + structure and prose. Commands such as @Chapter, @Section, + @Subsection, grouping commands, examples and logs, chunks and code + insertion, @Index, title-page commands, Markdown-style headings, + fenced code blocks, and ordinary &GAPDoc; XML markup work in both styles. + + + +As a concrete example, the following file can serve as a complete chapter +written in .autodoc format. + +```@listing +@Chapter Test +@Section First Section +@Subsection First Subsection + +This text belongs directly to the manual chapter. +It can use XML tags such as arg or <Ref ...>. + +@BeginExampleSession +gap> S5 := SymmetricGroup(5); +Sym( [ 1 .. 5 ] ) +gap> Size(S5); +120 +@EndExampleSession + +@Index "Worksheet Autoplain" Plain worksheet index entry with `true` +``` + +This is essentially the style used in the worksheet fixture +tst/worksheets/autoplain.sheet/plain.autodoc. + +The same structural commands can also be used inside source comments, for +example: + +```@listing +#! @Chapter Reference +#! @Section The AutoDoc() function +#! Some introductory text for this section. +``` + +This source-comment style is still fully supported and is used in +gap/Magic.gd. + +The mixed-workflow case is equally common. Suppose an existing manual still has +a hand-written main XML file and perhaps some hand-written XML chapters. Then +you can keep those files, include _AutoDocMainFile.xml from the main XML +file as described in Chapter , and add one or +more .autodoc files via autodoc.files or autodoc.scan_dirs. +Those files can provide tutorial chapters or appendices, while declaration +documentation continues to live in source comments and older XML chapters remain +unchanged. + +One caveat is worth keeping in mind. If you want a standalone +.autodoc file to pause and resume around declaration documentation that +is written in source comments, the current workaround is to use chunks. That +interleaving workflow is currently limited; see issue #60 in the +AutoDoc issue tracker. + +So, while .autodoc files and source comments share most of the same text +syntax, they can be combined freely. The main distinction is simply that +declaration-bound commands attach metadata to a following declaration, while +standalone manual text can live wherever you find it most convenient. @Section Grouping @SectionLabel Groups diff --git a/doc/Overview.autodoc b/doc/Overview.autodoc index a3c854a2..e10da696 100644 --- a/doc/Overview.autodoc +++ b/doc/Overview.autodoc @@ -22,6 +22,8 @@ you can adopt only the parts that help you today, and add more over time. extract_examples := true. - Document declarations directly in source files via &AutoDoc; comments beginning with #!. +- Organize chapter and section text either in source comments or in + standalone .autodoc files. - Combine &AutoDoc; comments, classic &GAPDoc; source comments, and hand-written XML chapters in one manual. @@ -35,6 +37,8 @@ Typical adoption paths include: - Keep your existing title page but use generated entities such as &VERSION;, &RELEASEYEAR;, and &RELEASEDATE;. - Add &AutoDoc; comments only for new code, and leave old documentation as-is. +- Keep existing XML chapters, or gradually add source comments and + .autodoc files where they fit your preferred workflow. - Later, gradually move chapters or source documentation to your preferred style. This flexibility is central: &AutoDoc; should make your current setup better, @@ -45,4 +49,4 @@ without forcing a full rewrite first. For practical setup and migration workflows, continue with chapter . For the command reference of documentation comments, -see chapter . +including standalone .autodoc files, see chapter . diff --git a/doc/Tutorials.autodoc b/doc/Tutorials.autodoc index 0101059a..19361b6a 100644 --- a/doc/Tutorials.autodoc +++ b/doc/Tutorials.autodoc @@ -96,6 +96,14 @@ Section . @Section Documenting code with &AutoDoc; @SectionLabel Tut:AdvancedAutoDoc +&AutoDoc; supports several equally supported ways to organize your manual text. +You can put chapter and section material directly into #! comments inside +.g, .gd, or .gi files, you can put it into standalone +.autodoc files, and you can mix either style with existing &GAPDoc; XML. +Which arrangement is best is mostly a matter of taste and convenience. +The detailed command reference for these styles is in chapter +, especially Section . + To get one of your global functions, operations, attributes etc. to appear in the package manual, simply insert an &AutoDoc; comment of the form #! directly in front of it. For example: @@ -127,6 +135,21 @@ interpreted as &AutoDoc; commands). So, for instance, tags like <Ref>, <A>, <K>, <List>, etc. can be written directly in #! comment text. +For chapter text, tutorial material, worked examples, and similar prose, some +authors prefer to keep the material next to their code using +#! @Chapter, #! @Section, and related commands, while others prefer +standalone .autodoc files. In an .autodoc file you write the same +commands without the #! prefix, and you list the file in +autodoc.files or place it in a directory scanned via +autodoc.scan_dirs. AutoDoc itself still uses the source-comment style in +places, for example in gap/Magic.gd. + +One caveat applies if you decide to keep prose in a standalone +.autodoc file but want to interrupt it with the documentation of a +declaration that is written in source comments. Today that requires the chunk +mechanism, and that workflow is currently limited; see issue #60 in the +AutoDoc issue tracker. + For a thorough description of what you can do with &AutoDoc; documentation comments, please refer to chapter . @@ -168,13 +191,13 @@ AutoDoc( rec( scaffold := true, If you are not using the scaffolding feature, e.g. because you already have an existing &GAPDoc; based manual, then you can still use &AutoDoc; -documentation comments. Just make sure to first edit the main XML +documentation comments and standalone .autodoc files. Just make sure to first edit the main XML file of your documentation, and insert the line ```@listing <#Include SYSTEM "_AutoDocMainFile.xml"> ``` in a suitable place. This means that you can mix &AutoDoc; documentation -comments freely with your existing documentation; you can even still make +comments and .autodoc files freely with your existing documentation; you can even still make use of any existing &GAPDoc; documentation comments in your code. The following command should be useful for you in this case; it diff --git a/tst/manual.expected/_Chapter_Comments.xml b/tst/manual.expected/_Chapter_Comments.xml index 56fc942b..c460bc5b 100644 --- a/tst/manual.expected/_Chapter_Comments.xml +++ b/tst/manual.expected/_Chapter_Comments.xml @@ -646,8 +646,99 @@ since worksheets do not have a PackageInfo.g file from which this informa Files that have the suffix .autodoc and are listed in the autodoc.files option of , resp. are contained in one of the directories listed in autodoc.scan_dirs, are treated as -&AutoDoc; plain text files. These work exactly like &AutoDoc; comments, except -that lines do not need to (and in fact, should not) start with #!. +standalone &AutoDoc; input files. They are meant for manual text that does not +belong next to a single declaration: chapters, sections, tutorials, worked +examples, index entries, chunks, title-page metadata, and similar prose-heavy +material. +

+Conceptually, a .autodoc file uses the same parser as &AutoDoc; +comments, but without the comment marker. In a .autodoc file, lines do +not need to start with #! and in fact usually should not. This makes +.autodoc files one convenient way to replace hand-written XML chapters +when you prefer &AutoDoc;'s command syntax and Markdown-like text features. +However, it is not the only supported style: chapter and section commands inside +source comments remain fully supported, and &AutoDoc; itself still uses that +style in files such as gap/Magic.gd. For the surrounding workflow, see +Chapter . +

+The most important difference from declaration comments is that a plain text +file does not document a declaration by adjacency. There is no following +Declare... or InstallMethod statement for &AutoDoc; to inspect. +So commands whose meaning depends on such a declaration only make sense in +source comments immediately before that declaration. +

+In practice, this gives the following rule of thumb. +

+ + + Use source comments beginning with #! to document declarations. + This is the mode for @Description, @Returns, + @Arguments, @Label, @Group, and @ChapterInfo. + + + Use either .autodoc files or source comments for standalone manual + structure and prose. Commands such as @Chapter, @Section, + @Subsection, grouping commands, examples and logs, chunks and code + insertion, @Index, title-page commands, Markdown-style headings, + fenced code blocks, and ordinary &GAPDoc; XML markup work in both styles. + + +

+As a concrete example, the following file can serve as a complete chapter +written in .autodoc format. +

+

arg or <Ref ...>. + +@BeginExampleSession +gap> S5 := SymmetricGroup(5); +Sym( [ 1 .. 5 ] ) +gap> Size(S5); +120 +@EndExampleSession + +@Index "Worksheet Autoplain" Plain worksheet index entry with `true` +]]> +

+This is essentially the style used in the worksheet fixture +tst/worksheets/autoplain.sheet/plain.autodoc. +

+The same structural commands can also be used inside source comments, for +example: +

+

+

+This source-comment style is still fully supported and is used in +gap/Magic.gd. +

+The mixed-workflow case is equally common. Suppose an existing manual still has +a hand-written main XML file and perhaps some hand-written XML chapters. Then +you can keep those files, include _AutoDocMainFile.xml from the main XML +file as described in Chapter , and add one or +more .autodoc files via autodoc.files or autodoc.scan_dirs. +Those files can provide tutorial chapters or appendices, while declaration +documentation continues to live in source comments and older XML chapters remain +unchanged. +

+One caveat is worth keeping in mind. If you want a standalone +.autodoc file to pause and resume around declaration documentation that +is written in source comments, the current workaround is to use chunks. That +interleaving workflow is currently limited; see issue #60 in the +AutoDoc issue tracker. +

+So, while .autodoc files and source comments share most of the same text +syntax, they can be combined freely. The main distinction is simply that +declaration-bound commands attach metadata to a following declaration, while +standalone manual text can live wherever you find it most convenient.

diff --git a/tst/manual.expected/_Chapter_Overview.xml b/tst/manual.expected/_Chapter_Overview.xml index 3726076e..fa4ccad5 100644 --- a/tst/manual.expected/_Chapter_Overview.xml +++ b/tst/manual.expected/_Chapter_Overview.xml @@ -38,6 +38,10 @@ Document declarations directly in source files via &AutoDoc; comments beginning with #!. +Organize chapter and section text either in source comments or in + standalone .autodoc files. + + Combine &AutoDoc; comments, classic &GAPDoc; source comments, and hand-written XML chapters in one manual. @@ -67,6 +71,10 @@ Keep your existing title page but use generated entities such as Add &AutoDoc; comments only for new code, and leave old documentation as-is. +Keep existing XML chapters, or gradually add source comments and + .autodoc files where they fit your preferred workflow. + + Later, gradually move chapters or source documentation to your preferred style. @@ -83,7 +91,7 @@ without forcing a full rewrite first.

For practical setup and migration workflows, continue with chapter . For the command reference of documentation comments, -see chapter . +including standalone .autodoc files, see chapter . diff --git a/tst/manual.expected/_Chapter_Tutorials.xml b/tst/manual.expected/_Chapter_Tutorials.xml index 4016d169..c5cb7e81 100644 --- a/tst/manual.expected/_Chapter_Tutorials.xml +++ b/tst/manual.expected/_Chapter_Tutorials.xml @@ -115,6 +115,14 @@ Section .

Documenting code with &AutoDoc; +

+&AutoDoc; supports several equally supported ways to organize your manual text. +You can put chapter and section material directly into #! comments inside +.g, .gd, or .gi files, you can put it into standalone +.autodoc files, and you can mix either style with existing &GAPDoc; XML. +Which arrangement is best is mostly a matter of taste and convenience. +The detailed command reference for these styles is in chapter +, especially Section .

To get one of your global functions, operations, attributes etc. to appear in the package manual, simply insert an &AutoDoc; comment @@ -147,6 +155,21 @@ interpreted as &AutoDoc; commands). So, for instance, tags like <Ref>, <A>, <K>, <List>, etc. can be written directly in #! comment text.

+For chapter text, tutorial material, worked examples, and similar prose, some +authors prefer to keep the material next to their code using +#! @Chapter, #! @Section, and related commands, while others prefer +standalone .autodoc files. In an .autodoc file you write the same +commands without the #! prefix, and you list the file in +autodoc.files or place it in a directory scanned via +autodoc.scan_dirs. AutoDoc itself still uses the source-comment style in +places, for example in gap/Magic.gd. +

+One caveat applies if you decide to keep prose in a standalone +.autodoc file but want to interrupt it with the documentation of a +declaration that is written in source comments. Today that requires the chunk +mechanism, and that workflow is currently limited; see issue #60 in the +AutoDoc issue tracker. +

For a thorough description of what you can do with &AutoDoc; documentation comments, please refer to chapter .

@@ -187,13 +210,13 @@ AutoDoc( rec( scaffold := true,

If you are not using the scaffolding feature, e.g. because you already have an existing &GAPDoc; based manual, then you can still use &AutoDoc; -documentation comments. Just make sure to first edit the main XML +documentation comments and standalone .autodoc files. Just make sure to first edit the main XML file of your documentation, and insert the line

]]> in a suitable place. This means that you can mix &AutoDoc; documentation -comments freely with your existing documentation; you can even still make +comments and .autodoc files freely with your existing documentation; you can even still make use of any existing &GAPDoc; documentation comments in your code.

The following command should be useful for you in this case; it