diff --git a/CHANGES b/CHANGES index 17164136..92d187ae 100644 --- a/CHANGES +++ b/CHANGES @@ -5,6 +5,7 @@ XXX AutoDoc version - Deprecate @BeginAutoDocPlainText and @EndAutoDocPlainText; they will be removed in a future AutoDoc version + - Fix @BeginCode / @EndCode / @InsertCode, which were broken in version 2019.07.03 2019.07.24 - Add support for ISO 8601 dates in package metadata (to prepare for GAP adding diff --git a/gap/DocumentationTree.gd b/gap/DocumentationTree.gd index b3251973..a04cac37 100644 --- a/gap/DocumentationTree.gd +++ b/gap/DocumentationTree.gd @@ -49,7 +49,6 @@ DeclareOperation( "SectionInTree", [ IsTreeForDocumentation, IsString, IsString DeclareOperation( "SubsectionInTree", [ IsTreeForDocumentation, IsString, IsString, IsString ] ); DeclareOperation( "DocumentationExample", [ IsTreeForDocumentation ] ); DeclareOperation( "DocumentationChunk", [ IsTreeForDocumentation, IsString ] ); -DeclareOperation( "DocumentationCode", [ IsTreeForDocumentation, IsString ] ); DeclareOperation( "DocumentationManItem", [ IsTreeForDocumentation ] ); DeclareOperation( "SetManItemToDescription", [ IsTreeForDocumentationNode ] ); DeclareOperation( "SetManItemToReturnValue", [ IsTreeForDocumentationNode ] ); diff --git a/gap/DocumentationTree.gi b/gap/DocumentationTree.gi index e6991ac0..947e40ad 100644 --- a/gap/DocumentationTree.gi +++ b/gap/DocumentationTree.gi @@ -104,14 +104,6 @@ BindGlobal( "TheTypeOfDocumentationTreeExampleNodes", NewType( TheFamilyOfDocumentationTreeNodes, IsTreeForDocumentationExampleNodeRep ) ); -DeclareRepresentation( "IsTreeForDocumentationCodeNodeRep", - IsTreeForDocumentationNodeRep, - [ ] ); - -BindGlobal( "TheTypeOfDocumentationTreeCodeNodes", - NewType( TheFamilyOfDocumentationTreeNodes, - IsTreeForDocumentationCodeNodeRep ) ); - ################################### ## ## Tools @@ -238,27 +230,6 @@ InstallMethod( DocumentationChunk, [ IsTreeForDocumentation, IsString ], return node; end ); -## -InstallMethod( DocumentationCode, [ IsTreeForDocumentation, IsString ], - function( tree, name ) - local node; - - name := Concatenation( "System_", name ); - - node := rec( content := [ ], - level := tree!.current_level ); - - ObjectifyWithAttributes( node, TheTypeOfDocumentationTreeCodeNodes, - Label, name ); - - if IsBound( tree!.nodes_by_label.( name ) ) then - Add( tree!.nodes_by_label.( name )!.content, node ); - fi; - - tree!.nodes_by_label.( name ) := node; - return node; -end ); - ## InstallMethod( DocumentationManItem, [ IsTreeForDocumentation ], function( tree ) @@ -537,8 +508,8 @@ InstallMethod( WriteDocumentation, [ IsString, IsStream, IsInt ], ## In case the list is empty, do nothing. ## Once the empty string = empty list bug is fixed, ## this could be removed. - text := NormalizedWhitespace( text ); - if text = "" then + text := Chomp( text ); + if NormalizedWhitespace( text ) = "" then return; fi; AppendTo( filestream, text, "\n" ); @@ -657,25 +628,3 @@ InstallMethod( WriteDocumentation, [ IsTreeForDocumentationExampleNodeRep, IsStr od; AppendTo( filestream, "]]>\n\n" ); end ); - -## -InstallMethod( WriteDocumentation, [ IsTreeForDocumentationCodeNodeRep, IsStream, IsInt ], - function( node, filestream, level_value ) - local content, i; - - if node!.level > level_value then - return; - fi; - - content := node!.content; - - if content = [ ] then - return; - fi; - - AppendTo( filestream, "\n" ); -end ); diff --git a/gap/Parser.gi b/gap/Parser.gi index daff2abf..6c6c905c 100644 --- a/gap/Parser.gi +++ b/gap/Parser.gi @@ -410,7 +410,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, end; read_code := function( ) local code, temp_curr_line, comment_pos, before_comment; - code := [ ]; + code := [ "\n" ); return code; end; read_example := function( is_tested_example ) @@ -744,7 +745,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, @BeginCode := function() local label_name, tmp_system; label_name := ReplacedString( current_command[ 2 ], " ", "_" ); - tmp_system := DocumentationCode( tree, label_name ); + tmp_system := DocumentationChunk( tree, label_name ); Append( tmp_system!.content, read_code() ); end, @Code := ~.@BeginCode, diff --git a/tst/manual.expected/_Chapter_AutoDoc.xml b/tst/manual.expected/_Chapter_AutoDoc.xml index 0bee55f0..b7f03178 100644 --- a/tst/manual.expected/_Chapter_AutoDoc.xml +++ b/tst/manual.expected/_Chapter_AutoDoc.xml @@ -12,334 +12,334 @@ nothing -This is the main function of the &AutoDoc; package. It can perform -any combination of the following tasks: - - -It can (re)generate a scaffold for your package manual. -That is, it can produce two XML files in &GAPDoc; format to be used as part -of your manual: First, a file named doc/PACKAGENAME.xml -(with your package's name substituted) which is used as -main XML file for the package manual, i.e. this file sets the -XML doctype and defines various XML entities, includes -other XML files (both those generated by &AutoDoc; as well -as additional files created by other means), tells &GAPDoc; -to generate a table of content and an index, and more. -Secondly, it creates a file doc/title.xml containing a title -page for your documentation, with information about your package -(name, description, version), its authors and more, based -on the data in your PackageInfo.g. - - -It can scan your package for &AutoDoc; based documentation (by using &AutoDoc; -tags and the Autodoc command. -This will -produce further XML files to be used as part of the package manual. - - -It can use &GAPDoc; to generate PDF, text and HTML (with -MathJaX enabled) documentation from the &GAPDoc; XML files it -generated as well as additional such files provided by you. For -this, it invokes -to convert the XML sources, and it also instructs &GAPDoc; to copy -supplementary files (such as CSS style files) into your doc directory -(see ). - - -For more information and some examples, please refer to Chapter . + This is the main function of the &AutoDoc; package. It can perform + any combination of the following tasks: + + + It can (re)generate a scaffold for your package manual. + That is, it can produce two XML files in &GAPDoc; format to be used as part + of your manual: First, a file named doc/PACKAGENAME.xml + (with your package's name substituted) which is used as + main XML file for the package manual, i.e. this file sets the + XML doctype and defines various XML entities, includes + other XML files (both those generated by &AutoDoc; as well + as additional files created by other means), tells &GAPDoc; + to generate a table of content and an index, and more. + Secondly, it creates a file doc/title.xml containing a title + page for your documentation, with information about your package + (name, description, version), its authors and more, based + on the data in your PackageInfo.g. + + + It can scan your package for &AutoDoc; based documentation (by using &AutoDoc; + tags and the Autodoc command. + This will + produce further XML files to be used as part of the package manual. + + + It can use &GAPDoc; to generate PDF, text and HTML (with + MathJaX enabled) documentation from the &GAPDoc; XML files it + generated as well as additional such files provided by you. For + this, it invokes + to convert the XML sources, and it also instructs &GAPDoc; to copy + supplementary files (such as CSS style files) into your doc directory + (see ). + + + For more information and some examples, please refer to Chapter . +

+ The parameters have the following meanings: + + packageOrDirectory + + The purpose of this parameter is twofold: to determine the package + directory in which &AutoDoc; will operate, and to find the metadata + concerning the package being documented. The parameter is either a + string, an IsDirectory object, or omitted. + If it is a string, &AutoDoc; interprets it as the name of a + package, uses the metadata of the first package known to ⪆ + with that name, and uses the InstallationPath specified in that + metadata as the package directory. If packageOrDirectory is + an IsDirectory object, this is used as package directory; + if the argument is omitted, then the current directory is used. + In the last two cases, the specified directory must contain a + PackageInfo.g file, and &AutoDoc; extracts all needed metadata + from that. The IsDirectory form is for example useful if you + have multiple versions of the package around and want to make sure the + documentation of the correct version is built. +

+ Note that when using AutoDocWorksheet (see + ), there is + no parameter corresponding to packageOrDirectory and so the + package directory is always the current directory, and + there is no metadata. + + optrec + + optrec can be a record with some additional options. + The following are currently supported: + + dir + + This should either be a string, in which case it must be a path + relative to the specified package directory, or a + Directory() object. (Thus, the only way to designate an + absolute directory is with a Directory() object.) This + option specifies where the package documentation + (e.g. the &GAPDoc; XML or the manual PDF, etc.) files are stored + and/or will be generated. +
+ Default value: "doc/". + + scaffold + + This controls whether and how to generate scaffold XML files + for the package documentation. +

+ The value should be either true, false or a + record. If it is a record or true (the latter is + equivalent to specifying an empty record), then this feature is + enabled. It is also enabled if opt.scaffold is missing but the + package's info record in PackageInfo.g has an AutoDoc entry. + In all other cases (in particular if opt.scaffold is + false), scaffolding is disabled. +

+ If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is + assumed to be a record, and its contents are used as default values for + the scaffold settings. +

-The parameters have the following meanings: - -packageOrDirectory - -The purpose of this parameter is twofold: to determine the package -directory in which &AutoDoc; will operate, and to find the metadata -concerning the package being documented. The parameter is either a -string, an IsDirectory object, or omitted. -If it is a string, &AutoDoc; interprets it as the name of a -package, uses the metadata of the first package known to ⪆ -with that name, and uses the InstallationPath specified in that -metadata as the package directory. If packageOrDirectory is -an IsDirectory object, this is used as package directory; -if the argument is omitted, then the current directory is used. -In the last two cases, the specified directory must contain a -PackageInfo.g file, and &AutoDoc; extracts all needed metadata -from that. The IsDirectory form is for example useful if you -have multiple versions of the package around and want to make sure the -documentation of the correct version is built. + If opt.scaffold is a record, it may contain the following entries.

-Note that when using AutoDocWorksheet (see -), there is -no parameter corresponding to packageOrDirectory and so the -package directory is always the current directory, and -there is no metadata. - -optrec - -optrec can be a record with some additional options. -The following are currently supported: - -dir - -This should either be a string, in which case it must be a path -relative to the specified package directory, or a -Directory() object. (Thus, the only way to designate an -absolute directory is with a Directory() object.) This -option specifies where the package documentation -(e.g. the &GAPDoc; XML or the manual PDF, etc.) files are stored -and/or will be generated. -
-Default value: "doc/". - -scaffold - -This controls whether and how to generate scaffold XML files -for the package documentation. + + includes + + A list of XML files to be included in the body of the main XML file. + If you specify this list and also are using &AutoDoc; to document + your operations with &AutoDoc; comments, + you can add _AutoDocMainFile.xml to this list + to control at which point the documentation produced by &AutoDoc; + is inserted. If you do not do this, it will be added after the last + of your own XML files. + + index + + By default, the scaffold creates an index. If you do not want an index, + set this to false. + + appendix + + This entry is similar to opt.scaffold.includes but is used + to specify files to include after the main body of the manual, + i.e. typically appendices. + + bib + + The name of a bibliography file, in BibTeX or XML format. + If this key is not set, but there is a file doc/PACKAGENAME.bib + then it is assumed that you want to use this as your bibliography. + + entities + + A record whose keys are taken as entity names, set to the corresponding + (string) values. For example, if you pass the record SomePackage, +

SomePackage", + RELEASEYEAR := "2015" )]]> + then the following entity definitions are added to the XML preamble: + SomePackage'> + ]]> + This allows you to write &SomePackage; and &RELEASEYEAR; + in your documentation, which will be replaced by respective values specified + in the entities definition. + + TitlePage + + A record whose entries are used to embellish the generated title page + for the package manual with extra information, such as a copyright + statement or acknowledgments. To this end, the names of the record + components are used as XML element names, and the values of the + components are outputted as content of these XML elements. For + example, you could pass the following record to set a custom + acknowledgements text: + + For a list of valid entries in the title page, please refer to the + &GAPDoc; manual, specifically section . + + MainPage + + If scaffolding is enabled, by default a main XML file is generated (this + is the file which contains the XML doctype and more). If you do not + want this (e.g. because you have a handwritten main XML file), but + still want &AutoDoc; to generate a title page for you, you can set this + option to false + + document_class + + Sets the document class of the resulting PDF. The value can either be a string + which has to be the name of the new document class, a list containing this string, or + a list of two strings. Then the first one has to be the document class name, the second one + the option string ( contained in [ ] ) in &LaTeX;. + + latex_header_file + + Replaces the standard header from &GAPDoc; completely with the header in this &LaTeX; file. + Please be careful here, and look at &GAPDoc;'s latexheader.tex file for an example. + + + + autodoc + + This controls whether and how to generate additional XML documentation files + by scanning for &AutoDoc; documentation comments. +

+ The value should be either true, false or a + record. If it is a record or true (the latter is + equivalent to specifying an empty record), then this feature is + enabled. It is also enabled if opt.autodoc is missing but the + package depends (directly) on the &AutoDoc; package. + In all other cases (in particular if opt.autodoc is + false), this feature is disabled. +

-The value should be either true, false or a -record. If it is a record or true (the latter is -equivalent to specifying an empty record), then this feature is -enabled. It is also enabled if opt.scaffold is missing but the -package's info record in PackageInfo.g has an AutoDoc entry. -In all other cases (in particular if opt.scaffold is -false), scaffolding is disabled. + If opt.autodoc is a record, it may contain the following entries.

-If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is -assumed to be a record, and its contents are used as default values for -the scaffold settings. + + files + + A list of files (given by paths relative to the package directory) + to be scanned for &AutoDoc; documentation comments. + Usually it is more convenient to use autodoc.scan_dirs, see below. + + scan_dirs + + A list of subdirectories of the package directory (given as relative paths) + which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files + are then scanned for &AutoDoc; documentation comments. +
+ Default value: [ ".", "gap", "lib", "examples", "examples/doc" ]. + + level + + This defines the level of the created documentation. The default value is 0. + When parts of the manual are declared with a higher value + they will not be printed into the manual. + + + + gapdoc + + This controls whether and how to invoke &GAPDoc; to create HTML, PDF and text + files from your various XML files. +

+ The value should be either true, false or a + record. If it is a record or true (the latter is + equivalent to specifying an empty record), then this feature is + enabled. It is also enabled if opt.gapdoc is missing. + In all other cases (in particular if opt.gapdoc is + false), this feature is disabled. +

+ If opt.gapdoc is a record, it may contain the following entries.

-If opt.scaffold is a record, it may contain the following entries. + + main + + The name of the main XML file of the package manual. + This exists primarily to support packages with existing manual + which use a filename here which differs from the default. + In particular, specifying this is unnecessary when using scaffolding. +
+ Default value: PACKAGENAME.xml. + + files + + A list of files (given by paths relative to the package directory) + to be scanned for &GAPDoc; documentation comments. + Usually it is more convenient to use gapdoc.scan_dirs, see below. + + scan_dirs + + A list of subdirectories of the package directory (given as relative paths) + which &AutoDoc; then scans for .gi, .gd and .g files; all of these files + are then scanned for &GAPDoc; documentation comments. +
+ Default value: [ ".", "gap", "lib", "examples", "examples/doc" ]. + + LaTeXOptions + + Must be a record with entries which can be understood by + . Each entry can be a + string, which will be given to &GAPDoc; directly, or a list containing of + two entries: The first one must be the string "file", the second one a + filename. This file will be read and then its content is passed to &GAPDoc; + as option with the name of the entry. + + gap_root_relative_path + + Either a boolean, or a string containing a relative path. + By default (if this option is not set, or is set to false), + references in the generated documentation referring to external documentation + (such as the ⪆ manual) are encoded using absolute paths. + This is fine as long as the documentation stays on only a single + computer, but is problematic when preparing documentation that should be + used on multiple computers, e.g., when creating a distribution archive of + a ⪆ package.
+ Thus, if a relative path is provided via this option (or if it is set to true, + in which case the relative path ../../.. is used), then &AutoDoc; + and &GAPDoc; attempt to replace all absolute paths in references to ⪆ + manuals by paths based on this relative path.

- -includes - -A list of XML files to be included in the body of the main XML file. -If you specify this list and also are using &AutoDoc; to document -your operations with &AutoDoc; comments, -you can add _AutoDocMainFile.xml to this list -to control at which point the documentation produced by &AutoDoc; -is inserted. If you do not do this, it will be added after the last -of your own XML files. - -index - -By default, the scaffold creates an index. If you do not want an index, -set this to false. - -appendix - -This entry is similar to opt.scaffold.includes but is used -to specify files to include after the main body of the manual, -i.e. typically appendices. - -bib - -The name of a bibliography file, in BibTeX or XML format. -If this key is not set, but there is a file doc/PACKAGENAME.bib -then it is assumed that you want to use this as your bibliography. - -entities - -A record whose keys are taken as entity names, set to the corresponding -(string) values. For example, if you pass the record SomePackage, -

SomePackage", -RELEASEYEAR := "2015" )]]> -then the following entity definitions are added to the XML preamble: -SomePackage'> -]]> -This allows you to write &SomePackage; and &RELEASEYEAR; -in your documentation, which will be replaced by respective values specified -in the entities definition. - -TitlePage - -A record whose entries are used to embellish the generated title page -for the package manual with extra information, such as a copyright -statement or acknowledgments. To this end, the names of the record -components are used as XML element names, and the values of the -components are outputted as content of these XML elements. For -example, you could pass the following record to set a custom -acknowledgements text: - -For a list of valid entries in the title page, please refer to the -&GAPDoc; manual, specifically section . - -MainPage - -If scaffolding is enabled, by default a main XML file is generated (this -is the file which contains the XML doctype and more). If you do not -want this (e.g. because you have a handwritten main XML file), but -still want &AutoDoc; to generate a title page for you, you can set this -option to false - -document_class - -Sets the document class of the resulting PDF. The value can either be a string -which has to be the name of the new document class, a list containing this string, or -a list of two strings. Then the first one has to be the document class name, the second one -the option string ( contained in [ ] ) in &LaTeX;. - -latex_header_file - -Replaces the standard header from &GAPDoc; completely with the header in this &LaTeX; file. -Please be careful here, and look at &GAPDoc;'s latexheader.tex file for an example. - - - -autodoc - -This controls whether and how to generate additional XML documentation files -by scanning for &AutoDoc; documentation comments. + On a technical level, &AutoDoc; passes the relative path to the + gaproot parameter of

+ + + + extract_examples + + Either true or a record. + If set to true, then all manual examples are extracted and placed + into files tst/PACKAGENAME01.tst, tst/PACKAGENAME02.tst, ... + and so on, with one file for each chapter. + As a record, the entry can have the following entries itself, to specify some options. + + units + + This controls how examples are grouped into files. Recognized values are + "Chapter" (default), "Section", "Subsection" or "Single". Depending on the value, + one file is created for each chapter, each section, each subsection or each example. + For all other values only a single file is created.

-The value should be either true, false or a -record. If it is a record or true (the latter is -equivalent to specifying an empty record), then this feature is -enabled. It is also enabled if opt.autodoc is missing but the -package depends (directly) on the &AutoDoc; package. -In all other cases (in particular if opt.autodoc is -false), this feature is disabled. -

-

-If opt.autodoc is a record, it may contain the following entries. -

- -files - -A list of files (given by paths relative to the package directory) -to be scanned for &AutoDoc; documentation comments. -Usually it is more convenient to use autodoc.scan_dirs, see below. - -scan_dirs - -A list of subdirectories of the package directory (given as relative paths) -which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files -are then scanned for &AutoDoc; documentation comments. -
-Default value: [ ".", "gap", "lib", "examples", "examples/doc" ]. - -level - -This defines the level of the created documentation. The default value is 0. -When parts of the manual are declared with a higher value -they will not be printed into the manual. - - - -gapdoc - -This controls whether and how to invoke &GAPDoc; to create HTML, PDF and text -files from your various XML files. -

-The value should be either true, false or a -record. If it is a record or true (the latter is -equivalent to specifying an empty record), then this feature is -enabled. It is also enabled if opt.gapdoc is missing. -In all other cases (in particular if opt.gapdoc is -false), this feature is disabled. -

-

-If opt.gapdoc is a record, it may contain the following entries. -

- -main - -The name of the main XML file of the package manual. -This exists primarily to support packages with existing manual -which use a filename here which differs from the default. -In particular, specifying this is unnecessary when using scaffolding. -
-Default value: PACKAGENAME.xml. - -files - -A list of files (given by paths relative to the package directory) -to be scanned for &GAPDoc; documentation comments. -Usually it is more convenient to use gapdoc.scan_dirs, see below. - -scan_dirs - -A list of subdirectories of the package directory (given as relative paths) -which &AutoDoc; then scans for .gi, .gd and .g files; all of these files -are then scanned for &GAPDoc; documentation comments. -
-Default value: [ ".", "gap", "lib", "examples", "examples/doc" ]. - -LaTeXOptions - -Must be a record with entries which can be understood by -. Each entry can be a -string, which will be given to &GAPDoc; directly, or a list containing of -two entries: The first one must be the string "file", the second one a -filename. This file will be read and then its content is passed to &GAPDoc; -as option with the name of the entry. - -gap_root_relative_path - -Either a boolean, or a string containing a relative path. -By default (if this option is not set, or is set to false), -references in the generated documentation referring to external documentation -(such as the ⪆ manual) are encoded using absolute paths. -This is fine as long as the documentation stays on only a single -computer, but is problematic when preparing documentation that should be -used on multiple computers, e.g., when creating a distribution archive of -a ⪆ package.
-Thus, if a relative path is provided via this option (or if it is set to true, -in which case the relative path ../../.. is used), then &AutoDoc; -and &GAPDoc; attempt to replace all absolute paths in references to ⪆ -manuals by paths based on this relative path.

-

-On a technical level, &AutoDoc; passes the relative path to the -gaproot parameter of

- - - -extract_examples - -Either true or a record. -If set to true, then all manual examples are extracted and placed -into files tst/PACKAGENAME01.tst, tst/PACKAGENAME02.tst, ... -and so on, with one file for each chapter. -As a record, the entry can have the following entries itself, to specify some options. - -units - -This controls how examples are grouped into files. Recognized values are -"Chapter" (default), "Section", "Subsection" or "Single". Depending on the value, -one file is created for each chapter, each section, each subsection or each example. -For all other values only a single file is created. -

-On a technical level, &AutoDoc; passes the value to the -units parameter of . - - - -maketest - -This option is deprecated. Please use extract_examples instead. -

-Either true or a record. When it is true, -a simple maketest.g file is created in the main package directory, -which can be used to test the examples from the manual. As a record, -the entry can have the following entries itself, to specify some options. - -filename - -Sets the name of the test file. - -commands - -A list of strings, each one a command, which -will be executed at the beginning of the test file. - - - - - - + On a technical level, &AutoDoc; passes the value to the + units parameter of . + + + + maketest + + This option is deprecated. Please use extract_examples instead. +

+ Either true or a record. When it is true, + a simple maketest.g file is created in the main package directory, + which can be used to test the examples from the manual. As a record, + the entry can have the following entries itself, to specify some options. + + filename + + Sets the name of the test file. + + commands + + A list of strings, each one a command, which + will be executed at the beginning of the test file. + + + + + +

@@ -352,8 +352,8 @@ will be executed at the beginning of the test file. Examples

-Some basic examples for using AutoDoc were already shown in -Chapter . + Some basic examples for using AutoDoc were already shown in + Chapter . diff --git a/tst/manual.expected/_Chapter_AutoDoc_worksheets.xml b/tst/manual.expected/_Chapter_AutoDoc_worksheets.xml index e089480f..2d1f09ca 100644 --- a/tst/manual.expected/_Chapter_AutoDoc_worksheets.xml +++ b/tst/manual.expected/_Chapter_AutoDoc_worksheets.xml @@ -10,12 +10,12 @@ -The intention of these function is to create stand-alone pdf and html files -using AutoDoc without having them associated to a package. -It uses the same optional records as the &AutoDoc; command itself, but instead of -a package name there should be a filename or a list of filenames containing AutoDoc -text from which the documents are created. Please see the &AutoDoc; command for more -information about this and have a look at for a simple worksheet example. + The intention of these function is to create stand-alone pdf and html files + using AutoDoc without having them associated to a package. + It uses the same optional records as the &AutoDoc; command itself, but instead of + a package name there should be a filename or a list of filenames containing AutoDoc + text from which the documents are created. Please see the &AutoDoc; command for more + information about this and have a look at for a simple worksheet example. diff --git a/tst/manual.expected/_Chunks.xml b/tst/manual.expected/_Chunks.xml new file mode 100644 index 00000000..e69de29b diff --git a/tst/worksheets/general.expected/_Chapter_SomeChapter.xml b/tst/worksheets/general.expected/_Chapter_SomeChapter.xml index b3d9614f..b7019b36 100644 --- a/tst/worksheets/general.expected/_Chapter_SomeChapter.xml +++ b/tst/worksheets/general.expected/_Chapter_SomeChapter.xml @@ -4,7 +4,7 @@ SomeChapter -This is dummy text + This is dummy text S5 := SymmetricGroup(5); Sym( [ 1 .. 5 ] ) @@ -13,7 +13,7 @@ gap> Size(S5); ]]> -Some text between two examples + Some text between two examples A5 := AlternatingGroup(5); Alt( [ 1 .. 5 ] ) @@ -22,11 +22,11 @@ gap> Size(A5); ]]> -And we wrap up with some dummy text + And we wrap up with some dummy text

Some categories -Intro text + Intro text true or false @@ -67,18 +67,18 @@ Intro text -Let's wrap up with something, though. + Let's wrap up with something, though.
SomeSection -Some test just inside a section. + Some test just inside a section. SomeSubsection -This is a subsection! + This is a subsection! @@ -86,7 +86,7 @@ This is a subsection! MarkDown support

-We can use test some markdown features here: + We can use test some markdown features here: This is a list item. @@ -110,14 +110,14 @@ This is inline code in a list item.

-All of this can also be used outside of a list. + All of this can also be used outside of a list. -An info class + An info class @@ -126,13 +126,13 @@ An info class This text will only appear in the \LaTeX version. ]]>

@@ -146,9 +146,9 @@ This text will only appear in the HTML version and the text version, too. -First sentence. -Second sentence. -Third sentence. + First sentence. + Second sentence. + Third sentence. @@ -159,10 +159,20 @@ Third sentence.
Testing chunks -This test comes after the chunk is declared, but before it is inserted. + This test comes after the chunk is declared, but before it is inserted. <#Include Label="MyChunk"> -The text "Hello, world." is inserted right before this. + The text "Hello, world." is inserted right before this. +
+ + +
+Testing code chunks + + This test comes after the code chunk is declared, but before it is inserted. +<#Include Label="MyCode"> + + The text "Hello, world." is inserted right before this.
diff --git a/tst/worksheets/general.expected/_Chunks.xml b/tst/worksheets/general.expected/_Chunks.xml index 639f3fd1..a39b48ec 100644 --- a/tst/worksheets/general.expected/_Chunks.xml +++ b/tst/worksheets/general.expected/_Chunks.xml @@ -1,4 +1,17 @@ <#GAPDoc Label="MyChunk"> -Hello, world. + Hello, world. + This line is indented! + +<#/GAPDoc> +<#GAPDoc Label="MyCode"> + 2"); +fi; +]]> <#/GAPDoc> diff --git a/tst/worksheets/general.sheet/worksheet.g b/tst/worksheets/general.sheet/worksheet.g index 7a398d36..094095ed 100644 --- a/tst/worksheets/general.sheet/worksheet.g +++ b/tst/worksheets/general.sheet/worksheet.g @@ -98,6 +98,7 @@ KeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime ); #! @BeginChunk MyChunk #! Hello, world. +#! This line is indented! #! @EndChunk #! This test comes after the chunk is declared, but before it is inserted. @@ -105,3 +106,22 @@ KeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime ); #! @InsertChunk MyChunk #! The text "Hello, world." is inserted right before this. + +############################################################################# +#! @Section Testing code chunks + +#! @BeginCode MyCode +#! Hello, world. +x := 1 + 1; +if x = 2 then + Print("1 + 1 = 2 holds, all is good\n"); +else + Error("1+1 <> 2"); +fi; +#! @EndCode + +#! This test comes after the code chunk is declared, but before it is inserted. + +#! @InsertCode MyCode + +#! The text "Hello, world." is inserted right before this.