source: project/release/4/scbib/trunk/scbib-eggdoc.scm @ 15306

Last change on this file since 15306 was 15306, checked in by Ivan Raikov, 11 years ago

scbib documentation and bug fixes

File size: 8.5 KB
Line 
1
2
3(require-library eggdoc)
4(import eggdoc)
5
6(define doc
7  `((eggdoc:begin
8     (name "scbib")
9     (description "A bibliography management system.")
10     (author (url "http://chicken.wiki.br/users/ivan-raikov" "Ivan Raikov"))
11
12     (history 
13      (version "1.0" "Initial release"))
14
15     (requires (url "datatype.html" "datatype"))
16
17     (documentation
18     
19      (p "The scbib library manages bibliographic data described as "
20         "S-expressions and is capable of generating BiBTeX entries from "
21         "a bibliographic database. ")
22
23      (p "scbib maintains four databases: persons, journals, "
24         "publishers and bibliographic entries: "
25         
26         (symbol-table 
27          (describe "(scbib-db-person)"     
28                    (tt "( (KEY-SYMBOL (name STRING)) ... )"))
29          (describe "(scbib-db-publisher)" 
30                    (tt "( (KEY-SYMBOL (name STRING) (web STRING) (address STRING)) ... )"))
31          (describe "(scbib-db-journal)"   
32                    (tt "( (KEY-SYMBOL (name STRING) (web STRING) ) ... )"))
33          (describe "(scbib-db-bib)"       
34                    ((tt "(bibtype SYMBOL)")
35                     (tt "(title STRING)")
36                     (tt "(booktitle STRING)")
37                     (tt "(author STRING-OR-KEY)")
38                     (tt "(editor STRING-OR-KEY)")
39                     (tt "(series STRING)")
40                     (tt "(publisher STRING-OR-KEY")
41                     (tt "(journal STRING-OR-KEY)")
42                     (tt "(volume STRING)")
43                     (tt "(pages STRING)")
44                     (tt "(abbrev STRING)")
45                     ))))
46
47      (p "The person, journal and publisher databases can provide "
48         "abbreviations to be used in the bibliographic database. "
49         "Each " (tt "KEY-SYMBOL") " defined in the first three databases "
50         "can be used in the respective fields in the bibliographic database. "
51         "The entries in the bibliographic database can of type: " 
52         (tt "article") ", " (tt "book") ", " (tt "web") ", " (tt "web") ", " 
53         (tt "techreport") " or " (tt "inproceedings") ". ")
54
55
56      (p "Each database is defined as a parameter, i.e. procedures of zero "
57         "or one arguments. To retrieve the value of a database call the "
58         "corresponding parameter-procedure with zero arguments. To change "
59         "the contents of a parameter, call the parameter-procedure with "
60         "the new value as argument: "
61
62      (pre #<<EOF
63           ;; append a new item to the bibliographic database
64           (scbib-db-person (cons item (scbib-db-person))) 
65EOF
66))
67         
68      (subsection "Procedures"
69
70                  (procedure "scbib-find:: QUERY * DB -> ITEM"
71                             (p "Locates an item in a database. This procedure applies the given query procedure "
72                                "to each element in the database and returns the first result where the query "
73                                "procedure returns a true value. " (tt "QUERY") " must be a procedure of one argument. "
74                                (tt "DB") " must be one of the database parameters defined by the library. "))
75
76                  (procedure "scbib-values:: ITEM * NAME -> LIST"
77                             (p "Returns the values associated with a certain field in the given bibliographic item. "
78                                "This procedure takes a bibliographic item and a field name and returns a list of values "
79                                "associated with the given field."))
80                               
81                  (procedure "scbib-value:: ITEM * NAME -> ITEM"
82                             (p "Returns a single value associated with a certain field in the given bibliographic item. "
83                                "This procedure takes a bibliographic item and a field name and returns the value "
84                                "associated with the given field."))
85
86                  (procedure "scbib-load-db:: FILE-NAME -> UNDEFINED"
87                             (p "Loads bibliographic entries from a file. "
88                                "This procedure takes a file name, reads all entries from the given file and puts them "
89                                "in the appropriate database(s). The file must contain entries in s-expression format of "
90                                "the format " (tt "(TYPE ITEM)") ", where " (tt "TYPE") " is one of "
91                                (tt "PERSON") ", " (tt "JOURNAL") ", " (tt "PUBLISHER") ", " (tt "BIB") ", and " 
92                                (tt "ITEM") " is in the format appropriate for this type of item (see the beginning "
93                                " of this document). "))
94
95                  (procedure "scbib-load-db:: FILE-PORT -> UNDEFINED"
96                             (p "Loads bibliographic entries from a file. "
97                                "This procedure takes an input file port, reads all entries from the given file and puts them "
98                                "in the appropriate database(s). The file must contain entries in s-expression format of "
99                                "the format " (tt "(TYPE ITEM)") ", where " (tt "TYPE") " is one of "
100                                (tt "PERSON") ", " (tt "JOURNAL") ", " (tt "PUBLISHER") ", " (tt "BIB") ", and " 
101                                (tt "ITEM") " is in the format appropriate for this type of item (see the beginning "
102                                " of this document). "))
103
104                  (procedure "scbib-load-db-all:: UNDEFINED -> UNDEFINED"
105                             (p "Loads bibliographic entries from all files in the load path. "
106                                "This procedure locates and reads all files with suffix .db in the scbib load path, " 
107                                "loads all entries from those files and puts them in the appropriate database(s). "
108                                "The files must contain entries in s-expression format of "
109                                "the format " (tt "(TYPE ITEM)") ", where " (tt "TYPE") " is one of "
110                                (tt "PERSON") ", " (tt "JOURNAL") ", " (tt "PUBLISHER") ", " (tt "BIB") ", and " 
111                                (tt "ITEM") " is in the format appropriate for this type of item (see the beginning "
112                                " of this document). "))
113
114                  (procedure "scbib-load-path:: [PATH] -> PATH"
115                             (p "Parameter procedure that contains the current bibliographic database load path."))
116
117#|
118                  (procedure "scbib-match:: [BIBTYPE] [CATEGORY] [SUBCATEGORY] -> (LAMBDA (ITEM) -> "
119                             
120;; (scbib-match item bibtype: "book")
121;; (scbib-match item bibtype: "book" category: '(not "programming"))
122;; (scbib-match item bibtype: '(or "book" "article"))
123|#
124
125                  (procedure "scbib-get-authors:: ITEM -> LIST"
126                             (p "Returns the list of authors for the given bibliographic item. "))
127
128                  (procedure "scbib-get-abbrev:: ITEM [* KEY-STYLE] -> STRING"
129                             (p "Returns the abbreviation string for the given item. "
130                                "If " (tt "KEY-STYLE") " is not given, the abbreviation format is "
131                                "the family name of the first author, followed by a colon, followed by "
132                                "the publication year. If " (tt "KEY-STYLE") " is given, it is expected "
133                                "to be a procedure of two arguments, author and year. "))
134
135                  (procedure "scbib-add-to-db!:: ITEM -> UNDEFINED"
136                             (p "Adds the given entry to the appropriate database. "
137                                "The entry must be an s-expression of the form "
138                                (tt "(TYPE CONTENTS)") ", where " (tt "TYPE") " is one of "
139                                (tt "PERSON") ", " (tt "JOURNAL") ", " (tt "PUBLISHER") ", " (tt "BIB") ", and " 
140                                (tt "CONTENTS") " is in the format appropriate for this type of item (see the beginning "
141                                " of this document). "))
142                  ))
143
144      (examples (pre #<<EOF
145(use scbib scbib-bibtex)
146
147(define bibliography
148  `((bib 
149     (title   "Executable cell biology")
150     (author  "Fisher, J" "Henzinger, T")
151     (journal "Nature Biotechnology" )
152     (number  "25") 
153     (pages   "1239-1249")
154     (year    "2007")
155     (bibtype "article")
156     (web     "http://www.nature.com/nbt/journal/v25/n11/abs/nbt1356.html"))
157
158    (bib
159     (title   "A computer architecture for highly parallel signal processing")
160     (author  "Dennis, J" "Misunas, D")
161     (journal "Proc. of the ACM Annual Conference")
162     (pages   "402-409")
163     (year    "1974")
164     (bibtype "article")
165     (web     "http://csg.csail.mit.edu/pubs/memos/Memo-108/Memo-108.pdf"))
166
167   
168    (bib
169     (title    "The semantics of a simple language for parallel programming")
170     (author   "Kahn, G")
171     (journal  "Information Processing")
172     (pages    "471-475")
173     (year     "1974")
174     (bibtype  "article")
175     (web      "http://www1.cs.columbia.edu/~sedwards/papers/kahn1974semantics.pdf"))
176 
177    ))
178
179(define (make-bib-db lst)
180  (for-each (lambda (item) (scbib-add-to-db! item)) lst))
181
182(define (generate-BiBTeX Content)
183  (let ((key-style (lambda (author year) (format #f "~a:~a" author (substring year 2 4)))))
184    (make-bib-db Content)
185    (for-each (lambda (x) (scbib-bibtex-print-item x key-style)) (scbib-db-bib))))
186
187(generate-BiBTeX bibliography)
188EOF
189))
190     (license
191      "Copyright (C) 2004 Satoru Takabayashi <satoru@namazu.org>.
192
193Ported to Chicken Scheme and modified by Ivan Raikov. Portions
194Copyright 2009 Ivan Raikov.
195
196This program is free software: you can redistribute it and/or modify
197it under the terms of the GNU General Public License as published by
198the Free Software Foundation, either version 3 of the License, or (at
199your option) any later version.
200
201This program is distributed in the hope that it will be useful, but
202WITHOUT ANY WARRANTY; without even the implied warranty of
203MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
204General Public License for more details.
205
206A full copy of the GPL license can be found at
207<http://www.gnu.org/licenses/>."))))
208
209(if (eggdoc->html doc) (void))
Note: See TracBrowser for help on using the repository browser.