;;; documentation.scm --- Run-time documentation facility
;;; Copyright (C) 2000-2003,2006,2009,2010,2024 Free Software Foundation, Inc.
;;;
;;; This library is free software: you can redistribute it and/or modify
;;; it under the terms of the GNU Lesser General Public License as
;;; published by the Free Software Foundation, either version 3 of the
;;; License, or (at your option) any later version.
;;;
;;; This library is distributed in the hope that it will be useful, but
;;; WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
;;; Lesser General Public License for more details.
;;;
;;; You should have received a copy of the GNU Lesser General Public
;;; License along with this program.  If not, see
;;; <http://www.gnu.org/licenses/>.

;;; Commentary:

;;; * This module exports:
;;;
;;; file-commentary      -- a procedure that returns a file's "commentary"
;;;
;;; documentation-files  -- a search-list of files using the Guile
;;;                         Documentation Format Version 2.
;;;
;;; search-documentation-files -- a procedure that takes NAME (a symbol)
;;;                               and searches `documentation-files' for
;;;                               associated documentation.  optional
;;;                               arg FILES is a list of filenames to use
;;;                               instead of `documentation-files'.
;;;
;;; object-documentation -- a procedure that returns its arg's docstring
;;;
;;; * Guile Documentation Format
;;;
;;; Here is the complete and authoritative documentation for the Guile
;;; Documentation Format Version 2:
;;;
;;; HEADER
;;; ^LPROC1
;;; DOCUMENTATION1
;;;
;;; ^LPROC2
;;; DOCUMENTATION2
;;;
;;; ^L...
;;;
;;; The HEADER is completely ignored.  The "^L" are formfeeds.  PROC1, PROC2
;;; and so on are symbols that name the element documented.  DOCUMENTATION1,
;;; DOCUMENTATION2 and so on are the related documentation, w/o any further
;;; formatting.  Note that there are two newlines before the next formfeed;
;;; these are discarded when the documentation is read in.
;;;
;;; (Version 1, corresponding to guile-1.4 and prior, is documented as being
;;; not documented anywhere except by this embarrassingly circular comment.)
;;;
;;; * File Commentary
;;;
;;; A file's commentary is the body of text found between comments
;;;     ;;; Commentary:
;;; and
;;;     ;;; Code:
;;; both of which must be at the beginning of the line.  In the result string,
;;; semicolons at the beginning of each line are discarded.
;;;
;;; You can specify to `file-commentary' alternate begin and end strings, and
;;; scrub procedure.  Use #t to get default values.  For example:
;;;
;;; (file-commentary "documentation.scm")
;;; You should see this text!
;;;
;;; (file-commentary "documentation.scm" "^;;; Code:" "ends here$")
;;; You should see the rest of this file.
;;;
;;; (file-commentary "documentation.scm" #t #t string-upcase)
;;; You should see this text very loudly (note semicolons untouched).

;;; Code:

(define-module (ice-9 documentation)
  #:use-module (ice-9 rdelim)
  #:use-module (ice-9 regex)
  #:use-module (ice-9 match)
  #:export (file-commentary
            documentation-files search-documentation-files
            object-documentation))