(use eggdoc)

(define doc
  `((eggdoc:begin
     (name "format-graph")

     (description "Output graph nodes and edges in different formats.")

     (author (url "http://chicken.wiki.br/users/ivan-raikov" "Ivan Raikov"))

     (history 
      (version "1.7" "Ported to Chicken 4")
      (version "1.6" "Somes updates to the .setup and .meta files")
      (version "1.5" "Fixed a bug in printing the title of a VCG graph")
      (version "1.4" "Build script updated for better cross-platform compatibility")
      (version "1.3" "eggdoc documentation fix")
      (version "1.2" "License upgrade to GPL v3")
      (version "1.1" "Fixes in the documentation")
      (version "1.0" "Initial release"))

     (requires)

     (usage "(require-extension format-graph)")

     (download "format-graph.egg")

     (documentation
      
      (p "The format-graph library defines procedures that print the nodes and edges of a graph "
	 "in different formats, such as the ones used by the " (url "http://www.graphviz.org/" "GraphViz") 
	 " or " (url "http://rw4.cs.uni-sb.de/~sander/html/gsvcg1.html" "VCG") " programs. " 
	 "The input graph objects must have the API defined by the " (url "digraph.html" "digraph module") ". ")


      (subsection "Procedures"

	     (procedure "make-format-graph:: TYPE -> FORMAT-PROC"
			(p "returns a graph formatter procedure of the specified types; "
			   "the following formats are  supported: "
			   (symbol-table 
			    (describe "'dot"  (p "dot format (see " 
						 (url "http://www.graphviz.org/doc/info/lang.html" 
						      "the GraphViz documentation") ")"))
			    (describe "'vcg"  (p "vcg format (see " 
						 (url "http://rw4.cs.uni-sb.de/~sander/html/gsvcg1.html#examples" 
						      "the VCG documetation") ")")))

			   "Each graph formatter procedure is of the form " 
			   (tt "LAMBDA OUT-PORT GRAPH [OPTION-LIST]") ", where "
			   (ul (li (tt "OUT-PORT") " is the port to which the graph representation should be output ")
			       (li (tt "GRAPH") " is a graph object that follows the API defined by the e.g. " 
				   (url "digraph.html" "digraph module"))
			       (li (tt "OPTION-LIST") " is a list of options of the form " (tt "STMT NAME VAL")
				   ", in the case of the dot formatter, or " (tt "NAME VAL") 
				   ", in the case of the dot and vcg formatters. "
				   "Each of the options will be included in the beginning of "
				   "the graph definition output. "))))

	     (procedure "graph->sexp:: GRAPH -> SEXP"
			(p "generates an s-expression description of the given graph, "
			   "with the following structure: "
			   (pre #<<EOF
(graph (name  GRAPH-NAME )
       (nodes (node (id NODE-ID ) (info NODE-INFO )) ... )
       (edges (edge (i EDGE-I-NODE )  (j EDGE-J-NODE )  (info (EDGE-INFO ))) ... ))
EOF
)))))

     (examples (pre #<<EOF
;; example adapted from the Boost graph library documentation
(require-extension srfi-1)
(require-extension digraph)
(require-extension format-graph)

(define used-by
  (list 
    (cons 'dax_h 'foo_cpp) (cons 'dax_h 'bar_cpp) (cons 'dax_h 'yow_h)
    (cons 'yow_h 'bar_cpp) (cons 'yow_h 'zag_cpp) (cons 'boz_h 'bar_cpp)
    (cons 'boz_h 'zig_cpp) (cons 'boz_h 'zag_cpp) (cons 'zow_h 'foo_cpp)
    (cons 'foo_cpp 'foo_o) (cons 'foo_o 'libfoobar_a) 
    (cons 'bar_cpp 'bar_o) (cons 'bar_o 'libfoobar_a) 
    (cons 'libfoobar_a 'libzigzag_a) (cons 'zig_cpp 'zig_o) 
    (cons 'zig_o 'libzigzag_a) (cons 'zag_cpp 'zag_o) 
    (cons 'zag_o 'libzigzag_a) (cons 'libzigzag_a 'killerapp)))

(define g (make-digraph 'depgraph "dependency graph"))

(define node-list (delete-duplicates 
		   (concatenate (list (map car used-by) (map cdr used-by)))))
	   
(define node-ids (list-tabulate (length node-list) values))

(for-each (lambda (i n) ((g 'add-node!) i n))
	  node-ids node-list)

(define node-map (zip node-list node-ids))

(for-each (lambda (e) 
	    (match e ((ni . nj) (let ((i (car (alist-ref ni node-map)))
				      (j (car (alist-ref nj node-map))))
				  ((g 'add-edge!) (list i j (format "~A->~A" ni nj)))))
		   (else (error "invalid edge " e))))
	  used-by)

((make-format-graph 'dot) (current-output-port) g )
((make-format-graph 'vcg) (current-output-port) g )
EOF
))
     (license
      "Copyright 2007 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))