# doc-cache created by Octave 11.3.0
# name: cache
# type: cell
# rows: 3
# columns: 7
# name: <cell-element>
# type: sq_string
# elements: 1
# length: 11
build_DEMOS


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 2445
 -- pkg-octave-doc: HTML = build_DEMOS (FCNNAME)

     Build notebook-style HTML for the DEMO blocks of a function or class
     member.

     ‘build_DEMOS’ collects every ‘%!demo’ block of FCNNAME and returns HTML, a
     char string with the generated HTML for all of them.  FCNNAME is a char
     string with the name of a function or, for a class member, a "class/method"
     path.  Each demo is wrapped in the demos_template.html card layout and
     titled Example: N. When FCNNAME has no demos, HTML is returned empty.

     Notebook layout
     ...............

     Each demo is rendered as an interleaved _notebook_ instead of a single code
     block trailed by its aggregated output.  The demo is split into cells and
     laid out as a vertical stack of boxes:

        • *Comment* lines become prose (see the Markdown subset below).

        • *Code* statements become input boxes.  Consecutive statements that
          print nothing are merged into a single box, so muted setup code reads
          as one block.

        • *Output* produced by a statement is shown in an output box directly
          beneath it, rather than at the end of the demo.  A statement prints
          when it is left unterminated by a semicolon or when it calls ‘disp’,
          ‘printf’, and the like.

        • *Figures* are saved as PNG images under the assets/ folder of the
          working directory, shown right after the code that drew them.

     Markdown in comments
     ....................

     Comment text uses a small subset of *Markdown*, _not_ texinfo, so that the
     same demo stays readable in the terminal when it is run with the ‘demo’
     command.  The supported constructs are:

        • inline code 'code' rendered as ‘<code>’;

        • bold **text** and italic *text* emphasis;

        • links [text](url);

        • paragraphs, separated by a blank comment line;

        • unordered lists, whose items start with a - or * marker, and ordered
          lists, whose items start with a 1.  marker.

     All comment text is HTML-escaped before the markup is applied.  The
     following are deliberately _not_ supported: any texinfo markup; underscore
     emphasis _text_, which would mangle identifier names such as ‘a_b_c’; and #
     headings, which would clash with the Octave comment marker.

     See also: find_DEMOS, function_texi2html, classdef_texi2html.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 76
Build notebook-style HTML for the DEMO blocks of a function or class member.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 18
classdef_texi2html


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 4171
 -- pkg-octave-doc: classdef_texi2html (CLSNAME, PKGFCNS, INFO)

     Generate HTML page for a class definition.

     ‘classdef_texi2html’ requires three input arguments: CLSNAME, a char string
     with the class' name; PKGFCNS, a cell array with all available functions of
     a package; and INFO, a structure with relevant information about the
     package, which the function CLSNAME belongs to.

     PKGFCNS can be either a Nx2 or a Nx3 cell array, whose 1st column list all
     available function names, the 2nd column list the each function's category,
     and the 3rd column contains the URL to the function's source code.  PKGFCNS
     is used to create relative references to other pages of functions which are
     listed in the seealso tag.  When a third column is present,
     ‘classdef_texi2html’ uses it to add a source code link of the the function
     in CLSNAME.

     The INFO structure requires at least the following fields:

     Field Name       Description
     ----------------------------------------------------------------------------------
     PKG_ICON         The relative reference to the package's logo image which must
                      be either in .svg or .png format and it is located in the
                      newly created assets/ folder inside the working directory.
                      
     PKG_NAME         The package's name (e.g.  "pkg-octave-doc")
                      
     PKG_TITLE        The package's title (e.g.  "Octave Package Documentation")
                      
     OCTAVE_LOGO      The relative reference to Octave's logo, also located inside
                      the assets/ folder.
                      

     To generate a suitable Nx2 cell array for a specific package, use the
     ‘package_texi2html’ function and to populate is with the 3rd column use
     ‘find_GHurls’.  The INFO structure can also be created with
     ‘package_texi2html’.

     Layout: grouped vs. lumped methods
     ..................................

     The class is rendered in one of two layouts, chosen automatically from the
     class source:

        • A *lumped* classdef (the default) becomes a _single_ page: the class
          help and its properties, then the constructor and one collapsible
          block per public method, each holding that method's help and demos.

        • A *grouped* classdef - one whose methods are organised into named
          groups by banner comment blocks (see below) - becomes a main page with
          the class help, the properties, and one collapsible block per _group_.
          Each group lists its methods, each with a one-line description,
          linking to a standalone CLASS.METHOD.html page.  Every public method
          (the constructor included) gets such a page, laid out like a function
          page but with a class-scoped sidebar (the groups and their methods)
          and a breadcrumb back to the package index and the class page; its
          source-code link points to the class source file.

     A class counts as grouped when - and only when - its source holds at least
     one method-group *banner*; this is never decided by the class' size or line
     count.  A banner is a comment block of the form

          ################################################################
          ##                     ** Group Name **                       ##
          ################################################################

     placed before a ‘methods’ block, matching the convention used by the
     datatypes package.  Each public method is assigned to the most recent
     banner above its definition; groups whose methods are all non-public
     (‘Hidden’ or private) are omitted, and any public method before the first
     banner is collected under an "Other" group.

     The generated HTML is based on the classdef_template.html and default.html
     layouts; a grouped classdef additionally uses group_template.html for the
     method groups and methodpage_template.html for the per-method pages.

     See also: package_texi2html, function_texi2html, find_GHurls, build_DEMOS.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 42
Generate HTML page for a class definition.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 10
find_DEMOS


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 396
 -- pkg-octave-doc: DEMOS = find_DEMOS (FCNNAME)

     Retrieve the DEMO code blocks from a particular function.

        • FCNNAME is a char string with the function's name.

        • DEMOS is cell array with each cell containing a char string with the
          code block of each DEMO available in FCNNAME.

     See also: build_DEMOS, function_texi2html, classdef_texi2html, find_GHurls.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 57
Retrieve the DEMO code blocks from a particular function.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 11
find_GHurls


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 1547
 -- pkg-octave-doc: PKGFCNS = find_GHurls (PKGURL, PKGFCNS)

     Retrieve unique URLs to every function's location within the package's
     GitHub repository.

     ‘find_GHurls’ requires two input arguments, PKGURL, a char string with the
     URL to the root directory to the package's GitHub repository and PKGFCNS, a
     Nx2 cell array containing the package's available functions (1st column)
     and their respective category (2nd column).

     Note: ‘find_GHurls’ explicitly works with repositories hosted on GitHub!
     PKGURL can be easily retrieved from the ‘PKG_URL’ field of the INFO
     structure returned from ‘package_texi2html’.

     ‘find_GHurls’ returns a cell array, PKGFCNS, by appending a third column to
     the input PKGFCNS with the URLs to the source code location of each
     individual function listed in the 1st column of PKGFCNS.  ‘find_GHurls’
     relies on ‘curl’ and ‘tar’, which must be installed and available to the
     system's ‘$PATH’, and an active internet connection to download and extract
     the targeted repository to a temporary directory.  If either ‘curl’ or
     ‘tar’ fail for any reason, ‘find_GHurls’ returns a verbatim copy of the
     input PKGFCNS.

     Use the following example to obtain a cell array with each function's URL
     to its source code location at GitHub:

          [pkgfcns, info] = package_texi2html ("pkg-octave-doc");
          pkgfcns = find_GHurls (info.PKG_URL, pkgfcns);

     See also: function_texi2html.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 80
Retrieve unique URLs to every function's location within the package's GitHub...



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 18
function_texi2html


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 2124
 -- pkg-octave-doc: function_texi2html (FCNNAME, PKGFCNS, INFO)

     Generate HTML page for a particular function.

     ‘function_texi2html’ requires three input arguments: FCNNAME, a char string
     with the function's name; PKGFCNS, a cell array with all available
     functions of a package; and INFO, a structure with relevant information
     about the package, which the function FCNNAME belongs to.

     PKGFCNS can be either a Nx2 or a Nx3 cell array, whose 1st column list all
     available function names, the 2nd column list the each function's category,
     and the 3rd column contains the URL to the function's source code.  PKGFCNS
     is used to relative references to other pages of functions which are listed
     in the See also tag.  When a 3rd column is present, ‘function_texi2html’
     uses it to add a source code link of the the function in FCNNAME.

     The INFO structure requires at least the following fields:

     Field Name       Description
     ----------------------------------------------------------------------------------
     PKG_ICON         The relative reference to the package's logo image which must
                      be either in .svg or .png format and it is located in the
                      newly created assets/ folder inside the working directory.
                      
     PKG_NAME         The package's name (e.g.  "pkg-octave-doc")
                      
     PKG_TITLE        The package's title (e.g.  "Octave Package Documentation")
                      
     OCTAVE_LOGO      The relative reference to Octave's logo, also located inside
                      the assets/ folder.
                      

     To generate a suitable Nx2 cell array for a specific package, use the
     ‘package_texi2html’ function and to populate is with the 3rd column use
     ‘find_GHurls’.  The INFO structure can also be created with
     ‘package_texi2html’.

     The generated HTML code is based on the function_template.html and
     default.html layouts.

     See also: package_texi2html, classdef_texi2html, find_GHurls, build_DEMOS.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 45
Generate HTML page for a particular function.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 13
list_packages


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 337
 -- pkg-octave-doc: VALID_PACKAGES = list_packages ()

     List pkg-installable packages from Octave Packages.

     ‘VALID_PACKAGES = list_packages ()’ returns a cell array of strings with
     the available names at Octave Package, which are installable with the ‘pkg’
     command, along with the URL to their latest release.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 51
List pkg-installable packages from Octave Packages.



# name: <cell-element>
# type: sq_string
# elements: 1
# length: 17
package_texi2html


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 3322
 -- pkg-octave-doc: package_texi2html (PKGNAME)
 -- pkg-octave-doc: [PKGFCNS, INFO] = package_texi2html (PKGNAME)

     Generate HTML pages for an entire package.

     ‘package_texi2html’ takes a single input argument, PKGNAME, which is a char
     string with the package's name whose HTML documentation need to be
     generated.  The function considers the current working path as the root
     directory of the built pages.  It creates an index.html page with the
     available functions (and their subdivision into separate categories) of the
     package according to its INDEX file.  Although the INDEX file (if absent)
     is automatically generated during the package's installation, it is best
     practice to include one in the package's source so there is full comtrol of
     the categorization among the functions.  Individual functions HTML pages
     area generated with ‘function_texi2html’.

     The generated pages follow the template of the Octave Packages GitHub Pages
     based on bootstrap 5 and the generated HTML code is based on the
     index_template.html and default.html layouts.

     For packages whose repository is available at GitHub, individual URLs to
     each function's location within the reposity are retrieved and used to add
     a link to source code in each function's page.  This requires an internet
     connection and ‘git’ installed and available to the system's ‘$PATH’.  If
     not available, the source code link is omitted and the functions' HTML
     pages are generated without it.

     Optionally, ‘package_texi2html’ can return two output arguments, namely
     PKGFCNS and INFO, which are necessary for the ‘find_GHurls’ and
     ‘function_texi2html’ functions.  In such case, the HTML pages generation is
     skipped.  This is useful for building individual function pages without the
     need to regenerate the package's entire documentation.

     Examples:

          [pkgfcns, info] = package_texi2html ("pkg-octave-doc");
          pkgfcns = find_GHurls (info.PKG_URL, pkgfcns);
          function_texi2html ("find_GHurls", pkgfcns, info);

     Returning arguments:

        • PKGFCNS is a Nx2 cell array containing the package's available
          functions (1st column) and their respective category (2nd column).

        • INFO is a structure with the following fields:

          Field Name       Description
          ----------------------------------------------------------------------------------
          PKG_URL          The URL to the package's repository at GitHub.
                           
          PKG_ICON         The relative reference to the package's logo image which must
                           be either in .svg or .png format and it is located in the
                           newly created ‘assets/’ folder inside the working directory.
                           
          PKG_NAME         The package's name (e.g.  "pkg-octave-doc")
                           
          PKG_TITLE        The package's title (e.g.  "Octave Package Documentation")
                           
          OCTAVE_LOGO      The relative reference to Octave's logo, also located inside
                           the assets/ folder.

     See also: function_texi2html, find_GHurls, build_DEMOS.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 42
Generate HTML pages for an entire package.





