Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

bibtex(n)                                          bibtex                                          bibtex(n)



____________________________________________________________________________________________________________

NAME
       bibtex - Parse bibtex files

SYNOPSIS
       package require Tcl  8.4

       package require bibtex  ?0.5?

       ::bibtex::parse ?options? ?text?

       ::bibtex::parse text

       ::bibtex::parse ?-command cmd? -channel chan

       ::bibtex::parse   ?-recordcommand     recordcmd?   ?-preamblecommand   preamblecmd?   ?-stringcommand
       stringcmd? ?-commentcommand  commentcmd? ?-progresscommand progresscmd? (text | -channel chan)

       ::bibtex::wait token

       ::bibtex::destroy token

       ::bibtex::addStrings token stringdict

____________________________________________________________________________________________________________

DESCRIPTION
       This package provides commands for the parsing of bibliographies in BibTeX format.

       ::bibtex::parse ?options? ?text?
              This is the general form of the command for parsing a bibliography. Depending on  the  options
              used  to  invoke it it will either return a token for the parser, or the parsed entries of the
              input bibliography. Instead of performing an immediate parse returning a predefined format the
              command  can  also  enter an event-based parsing style where all relevant entries in the input
              are reported through callback commands, in the style of SAX.

       ::bibtex::parse text
              In this form the command will assume that the specified text is a bibliography in BibTeX  for-mat, format,
              mat,  parse it, and then return a list containing one element per record found in the bibliog-raphy. bibliography.
              raphy. Note that comments, string definitions, preambles, etc. will not show up in the result.
              Each  element will be a list containing record type, bibliography key and record data, in this
              order. The record data will be a dictionary, its keys the keys of the record, with the associ-ated associated
              ated values.

       ::bibtex::parse ?-command cmd? -channel chan
              In  this  form the command will reads the bibliography from the specified Tcl channel chan and
              then returns the same data structure as described above.

              If however the option -command is specified the result will be a handle for the parser instead
              and  all  processing will be incremental and happen in the background. When the input has been
              exhausted the callback cmd will be invoked with the result of the parse. The exact  definition
              for the callback is


              cmd token parseresult
                     The  parse result will have the structure explained above, for the simpler forms of the
                     parser.

       Note that the parser will not close the channel after it has exhausted it. This is still the  respon-sibility responsibility
       sibility of the user of the parser.

       ::bibtex::parse   ?-recordcommand     recordcmd?   ?-preamblecommand   preamblecmd?   ?-stringcommand
       stringcmd? ?-commentcommand  commentcmd? ?-progresscommand progresscmd? (text | -channel chan)
              This  is  the most low-level form for the parser. The returned result will be a handle for the
              parser. During processing it will invoke the invoke the specified callback commands  for  each
              type of data found in the bibliography.

              The  processing will be incremental and happen in the background if, and only if a Tcl channel
              chan is specified. For a text the processing will happen immediately and all callbacks will be
              invoked before the command itself returns.

              The  callbacks,  i.e. *cmd, are all command prefixes and will be invoked with additional argu-ments arguments
              ments appended to them. The meaning of the arguments depends on the callback and is  explained
              below.  The  first argument will however always be the handle of the parser invoking the call-back. callback.
              back.

              recordcmd token type key recorddict
                     This callback is invoked whenever the parser  detects  a  bibliography  record  in  the
                     input.  Its  arguments  are the record type, the bibliography key for the record, and a
                     dictionary containing the keys and values describing  the  record.  Any  string  macros
                     known to the parser have already been expanded.

              preamblecmd token preambletext
                     This  callback  is invoked whenever the parser detects an @preamble block in the input.
                     The only additional argument is the text found in the preamble block. By  default  such
                     entries are ignored.

              stringcmd token stringdict
                     This  callback is invoked whenever the parser detects an @string-based macro definition
                     in the input. The argument is a dictionary with the  macro  names  as  keys  and  their
                     replacement  strings  as  values.  By  default such definitions are added to the parser
                     state for use in future bibliography records.

              commentcmd token commenttext
                     This callback is invoked whenever the parser detects a comment in the input.  The  only
                     additional argument is the comment text. By default such entries are ignored.

              progresscmd token percent
                     This  callback  is  invoked during processing to tell the user about the progress which
                     has been made. Its argument is the percentage of  data  processed,  as  integer  number
                     between  0  and 100.  In the case of incremental processing the perecentage will always
                     be -1 as the total number of entries is not known beforehand.


       ::bibtex::wait token
              This command waits for the parser represented by the token to complete and then  returns.  The
              returned result is the empty string.

       ::bibtex::destroy token
              This command cleans up all internal state associated with the parser represented by the handle
              token, effectively destroying it. This command can be called from within the parser  callbacks
              to terminate processing.

       ::bibtex::addStrings token stringdict
              This command adds the macro definitions stored in the dictionary stringdict to the parser rep-resented represented
              resented by the handle token.

              The dictionary keys are the macro names and the values their replacement strings. This command
              has the correct signature for use as a -stringcommand callback in an invokation of the command
              ::bibtex::parse.


BUGS, IDEAS, FEEDBACK
       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other  problems.
       Please   report   such   in   the   category   bibtex  of  the  Tcllib  SF  Trackers  [http://source -
       forge.net/tracker/? group_id=12883].  Please also report any ideas for enhancements you may  have  for
       either package and/or documentation.

KEYWORDS
       bibliography, bibtex, parsing, text processing

CATEGORY
       Text processing

COPYRIGHT
       Copyright (c) 2005 for documentation, Andreas Kupries <andreas_kupries@users.sourceforge.net>




bibtex                                               0.5                                           bibtex(n)