;;; readers.tdt                                         -*- scheme -*-

(text-db-table-config
 (delim . "\f")
 (fields (#:tag sexp)
         (#:pretty sexp-line)
         (#:url line)
         (#:description sexp)))


#:alist "association list"
../software/guile/doc/Association-Lists.html
(~p
 "This is a list of pairs, with (normally) unique " (~code "car") "s."
 " If the elements of the pairs are limited to symbols,  strings, and"
 " simple numbers, then the alist can be read by many programs, including"
 " " (~a 'href "http://www.gnu.org/software/emacs/" "Emacs") ","
 " " (~a 'href "../software/guile/" "Guile") ","
 " and other Scheme and Lisp implementations.")


#:text-db-table "text db table"
../software/ps/scm-html/ttn/read-text-db-table.scm.html.gz
(list
 (~p
  "This is a flexible file format that is partially self-describing."
  " For example, this text itself comprises the "
  (~code "#:description")
  " field of an entry in the "
  (~a 'href "readers.tdt" "file format text db table")
  " -- pretty funky stuff!")
 (~p
  "Because it is only partially describing, the rest of the semantics"
  " must necessarily be provided by the specific program in question."))


#:htmlization-map "htmlization map"
../software/ttn-do/scm-html/htmlize-scheme.scm.html.gz
(~p
 "This file format is used by a "
 (~code (~a 'href "../software/ttn-do/" "ttn-do"))
 " command in creating the "
 (~a 'href "../maint/cron-job-map.html" "cron job map") ","
 " among "
 (~a 'href "../software/ttn-do/scm-html/" "other things")
 ".")


#:eaab "eaab structured expression"
../software/ttn-do/scm-html/xml2sexp.scm.html.gz
(list
 (~p "This file format is a sexp with the following constraints:")
 (~ul (~li "only one top-level sexp in the file;")
      (~li "all sexps have the form ("
           (~code "element")
           " "
           (~code "attribute-alist")
           " "
           (~code "body")
           "), where " (~code "body") " can be zero or more sub-sexps."))
 (~p "We use it to avoid XML (blech!)."))


#:ttn-do-magic "compiled file for ttn-do magic"
../software/ttn-do/scm-html/magic.scm.html.gz
(list
 (~p "This file format is a compiled from a magic(5) file"
     " (the same format used by the file(1) command)."
     " Far out!")
 (~p "The first bytes of the file are " (~code "\".ttn-do-magic-N\"") ","
     " where " (~code "N") " is the ASCII representation of a small"
     " (fitting in one byte) integer.  This is the format version."
     " For versions 1 and 2, the rest of the file consists of structured"
     " expressions, amenable to Guile " (~code "read") ", mirroring the"
     " entries of the originating magic(5) file.")
 (~p "Each entry has the form: "
     (~code "(LEVEL OFFSET TYPE VALUE OUT-STRING)") ","
     " where")
 (~ul (~li (~code "LEVEL")
           " is a non-negative integer, starting with zero;")
      (~li (~code "OFFSET")
           " is an expression that resolves to a byte offset;")
      (~li (~code "TYPE")
           " is an expression that describes what kind"
           " of information must be extracted from the file,"
           " and also some parts of the matching strategy;")
      (~li (~code "VALUE")
           " is an expression that specifies the rest of the matching"
           " strategy, as well as the literal value to match against;")
      (~li (~code "OUT-STRING")
           " is a string, to be accumulated on match (if non-empty)."))
 (~p "Format versions 1 and 2 differ in the possible values for"
     " " (~code "VALUE") " and " (~code "OUT-STRING") ".  In version 1,"
     " " (~code "VALUE") " could also take the form " (~code "(#t #t)")
     " and " (~code "OUT-STRING") " could also be " (~code "#f") "."
     " These tokens cannot be read by Emacs (an interop target)"
     " however, so version 2 uses " (~code "x") " and the empty string,"
     " respectively, in those cases.")
 (~p "For more info, please see the"
     " " (~a 'href "http://linux.die.net/man/5/magic" "magic(5) manpage")
     "."))

;;; readers.tdt ends here