# doc-cache created by Octave 10.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: 440
 -- pkg-octave-doc: HTML = build_DEMOS (FCNNAME)

     Generate HTML code from the available DEMOS of a particular
     function.

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

        • HTML is a char string with the generated HTML code based on
          the demos_template.html layout for every DEMO available in
          FCNNAME.

     See also: find_DEMOS, function_texi2html, classdef_texi2html,
     find_GHurls.


# name: <cell-element>
# type: sq_string
# elements: 1
# length: 69
Generate HTML code from the available DEMOS of a particular function.



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


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

     Generate HTML page for a class definition.

     ‘function_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, ‘function_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’.

     ‘function_texi2html’ depends on the texi2html command line tool
     version 1.82, which must be installed and available on the system's
     $PATH, and the generated HTML code is based on the
     function_template.html and default.html layouts.

     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: 401
 -- 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: 1553
 -- 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: 2303
 -- 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’.

     ‘function_texi2html’ depends on the texi2html command line tool
     version 1.82, which must be installed and available on the system's
     $PATH, and 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: 3527
 -- 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.

     For the ‘package_texi2html’ to work, the texi2html command line
     tool, version 1.82, must be installed and available to the system's
     ‘$PATH’.

     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.





