(require-library eggdoc)
(import eggdoc)

(define doc
  `((eggdoc:begin
     (name "scbib")
     (description "A bibliography management system.")
     (author (url "http://chicken.wiki.br/users/ivan-raikov" "Ivan Raikov"))

     (history 
      (version "1.0" "Initial release"))

     (requires (url "datatype.html" "datatype"))

     (documentation
      
      (p "The scbib library manages bibliographic data described as "
	 "S-expressions and is capable of generating BiBTeX entries from "
	 "a bibliographic database. ")

      (p "scbib maintains four databases: persons, journals, "
	 "publishers and bibliographic entries: "
	 
	 (symbol-table 
	  (describe "(scbib-db-person)"     
		    (tt "( (KEY-SYMBOL (name STRING)) ... )"))
	  (describe "(scbib-db-publisher)"  
		    (tt "( (KEY-SYMBOL (name STRING) (web STRING) (address STRING)) ... )"))
	  (describe "(scbib-db-journal)"    
		    (tt "( (KEY-SYMBOL (name STRING) (web STRING) ) ... )"))
	  (describe "(scbib-db-bib)"        
		    ((tt "(bibtype SYMBOL)")
		     (tt "(title STRING)")
		     (tt "(booktitle STRING)")
		     (tt "(author STRING-OR-KEY)")
		     (tt "(editor STRING-OR-KEY)")
		     (tt "(series STRING)")
		     (tt "(publisher STRING-OR-KEY")
		     (tt "(journal STRING-OR-KEY)")
		     (tt "(volume STRING)")
		     (tt "(pages STRING)")
		     (tt "(abbrev STRING)")
		     ))))

      (p "The person, journal and publisher databases can provide "
	 "abbreviations to be used in the bibliographic database. "
	 "Each " (tt "KEY-SYMBOL") " defined in the first three databases "
	 "can be used in the respective fields in the bibliographic database. "
	 "The entries in the bibliographic database can of type: " 
	 (tt "article") ", " (tt "book") ", " (tt "web") ", " (tt "web") ", " 
	 (tt "techreport") " or " (tt "inproceedings") ". ")


      (p "Each database is defined as a parameter, i.e. procedures of zero "
	 "or one arguments. To retrieve the value of a database call the "
	 "corresponding parameter-procedure with zero arguments. To change "
	 "the contents of a parameter, call the parameter-procedure with "
	 "the new value as argument: "

      (pre #<<EOF
	   ;; append a new item to the bibliographic database
	   (scbib-db-person (cons item (scbib-db-person))) 
EOF
))
	 
      (subsection "Procedures"

		  (procedure "scbib-find:: QUERY * DB -> ITEM"
			     (p "Locates an item in a database. This procedure applies the given query procedure "
				"to each element in the database and returns the first result where the query "
				"procedure returns a true value. " (tt "QUERY") " must be a procedure of one argument. "
				(tt "DB") " must be one of the database parameters defined by the library. "))

		  (procedure "scbib-values:: ITEM * NAME -> LIST"
			     (p "Returns the values associated with a certain field in the given bibliographic item. "
				"This procedure takes a bibliographic item and a field name and returns a list of values "
				"associated with the given field."))
				
		  (procedure "scbib-value:: ITEM * NAME -> ITEM"
			     (p "Returns a single value associated with a certain field in the given bibliographic item. "
				"This procedure takes a bibliographic item and a field name and returns the value "
				"associated with the given field."))

		  (procedure "scbib-load-db:: FILE-NAME -> UNDEFINED"
			     (p "Loads bibliographic entries from a file. "
				"This procedure takes a file name, reads all entries from the given file and puts them "
				"in the appropriate database(s). The file must contain entries in s-expression format of "
				"the format " (tt "(TYPE ITEM)") ", where " (tt "TYPE") " is one of "
				(tt "PERSON") ", " (tt "JOURNAL") ", " (tt "PUBLISHER") ", " (tt "BIB") ", and " 
				(tt "ITEM") " is in the format appropriate for this type of item (see the beginning "
				" of this document). "))

		  (procedure "scbib-load-db:: FILE-PORT -> UNDEFINED"
			     (p "Loads bibliographic entries from a file. "
				"This procedure takes an input file port, reads all entries from the given file and puts them "
				"in the appropriate database(s). The file must contain entries in s-expression format of "
				"the format " (tt "(TYPE ITEM)") ", where " (tt "TYPE") " is one of "
				(tt "PERSON") ", " (tt "JOURNAL") ", " (tt "PUBLISHER") ", " (tt "BIB") ", and " 
				(tt "ITEM") " is in the format appropriate for this type of item (see the beginning "
				" of this document). "))

		  (procedure "scbib-load-db-all:: UNDEFINED -> UNDEFINED"
			     (p "Loads bibliographic entries from all files in the load path. "
				"This procedure locates and reads all files with suffix .db in the scbib load path, " 
				"loads all entries from those files and puts them in the appropriate database(s). "
				"The files must contain entries in s-expression format of "
				"the format " (tt "(TYPE ITEM)") ", where " (tt "TYPE") " is one of "
				(tt "PERSON") ", " (tt "JOURNAL") ", " (tt "PUBLISHER") ", " (tt "BIB") ", and " 
				(tt "ITEM") " is in the format appropriate for this type of item (see the beginning "
				" of this document). "))

		  (procedure "scbib-load-path:: [PATH] -> PATH"
			     (p "Parameter procedure that contains the current bibliographic database load path."))

#|
		  (procedure "scbib-match:: [BIBTYPE] [CATEGORY] [SUBCATEGORY] -> (LAMBDA (ITEM) -> "
			     
;; (scbib-match item bibtype: "book")
;; (scbib-match item bibtype: "book" category: '(not "programming"))
;; (scbib-match item bibtype: '(or "book" "article"))
|#

                  (procedure "scbib-get-authors:: ITEM -> LIST"
			     (p "Returns the list of authors for the given bibliographic item. "))

                  (procedure "scbib-get-abbrev:: ITEM [* KEY-STYLE] -> STRING"
			     (p "Returns the abbreviation string for the given item. "
				"If " (tt "KEY-STYLE") " is not given, the abbreviation format is "
				"the family name of the first author, followed by a colon, followed by "
				"the publication year. If " (tt "KEY-STYLE") " is given, it is expected "
				"to be a procedure of two arguments, author and year. "))

		  (procedure "scbib-add-to-db!:: ITEM -> UNDEFINED"
			     (p "Adds the given entry to the appropriate database. "
				"The entry must be an s-expression of the form "
				(tt "(TYPE CONTENTS)") ", where " (tt "TYPE") " is one of "
				(tt "PERSON") ", " (tt "JOURNAL") ", " (tt "PUBLISHER") ", " (tt "BIB") ", and " 
				(tt "CONTENTS") " is in the format appropriate for this type of item (see the beginning "
				" of this document). "))
		  ))

      (examples (pre #<<EOF
(use scbib scbib-bibtex)

(define bibliography
  `((bib 
     (title   "Executable cell biology")
     (author  "Fisher, J" "Henzinger, T")
     (journal "Nature Biotechnology" )
     (number  "25") 
     (pages   "1239-1249")
     (year    "2007")
     (bibtype "article")
     (web     "http://www.nature.com/nbt/journal/v25/n11/abs/nbt1356.html"))

    (bib
     (title   "A computer architecture for highly parallel signal processing")
     (author  "Dennis, J" "Misunas, D")
     (journal "Proc. of the ACM Annual Conference")
     (pages   "402-409")
     (year    "1974")
     (bibtype "article")
     (web     "http://csg.csail.mit.edu/pubs/memos/Memo-108/Memo-108.pdf"))

    
    (bib
     (title    "The semantics of a simple language for parallel programming")
     (author   "Kahn, G")
     (journal  "Information Processing")
     (pages    "471-475")
     (year     "1974")
     (bibtype  "article")
     (web      "http://www1.cs.columbia.edu/~sedwards/papers/kahn1974semantics.pdf"))
  
    ))

(define (make-bib-db lst)
  (for-each (lambda (item) (scbib-add-to-db! item)) lst))

(define (generate-BiBTeX Content)
  (let ((key-style (lambda (author year) (format #f "~a:~a" author (substring year 2 4)))))
    (make-bib-db Content)
    (for-each (lambda (x) (scbib-bibtex-print-item x key-style)) (scbib-db-bib))))

(generate-BiBTeX bibliography)
EOF
))
     (license
      "Copyright (C) 2004 Satoru Takabayashi <satoru@namazu.org>.

Ported to Chicken Scheme and modified by Ivan Raikov. Portions
Copyright 2009 Ivan Raikov.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program 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
General Public License for more details.

A full copy of the GPL license can be found at
<http://www.gnu.org/licenses/>."))))

(if (eggdoc->html doc) (void))