diff options
Diffstat (limited to 'bits/bbdb-filters/doc/main.texinfo')
| -rw-r--r-- | bits/bbdb-filters/doc/main.texinfo | 492 |
1 files changed, 0 insertions, 492 deletions
diff --git a/bits/bbdb-filters/doc/main.texinfo b/bits/bbdb-filters/doc/main.texinfo deleted file mode 100644 index 7edb948..0000000 --- a/bits/bbdb-filters/doc/main.texinfo +++ /dev/null @@ -1,492 +0,0 @@ -% This is really LaTeXInfo, but some time LaTeX mode is more useful -*- LaTeX -*- -% This is really LaTeXInfo, but some time LaTeX mode is more useful -*- Latexinfo -*- -% -% Revision: main.texinfo,v 1.1.1.1 1995/08/07 08:43:10 mohsen Exp -% -%\documentstyle[12pt,latexinfo,format,smallverb,tabular]{book} -%\documentstyle[12pt,latexinfo,format]{book} -\documentstyle[12pt,format,hyperlatex,latexinfo]{book} -%\documentstyle[12pt,times,latexinfo,format]{book} -%\documentstyle[12pt,avantgarde,latexinfo,format]{book} -%\documentstyle[12pt,palatino,latexinfo,format]{book} -%\documentstyle[10pt,avantgarde,latexinfo,format]{book} - -\pagestyle{empty} - -\c \input{transfig} \c Used with eepic -- not needed when using psfig. -\input{epsf} - -\begin{document} - -\c \bibliographystyle{alpha} \c [banan92] -\c \bibliographystyle{plain} \c Numbers [1] - -\c \textwidth 5.2in \c for .tty generation - -\htmldirectory{bbdbFilters} -\htmlname{bbdbFilters} -\htmltitle{BBDB Filters} -\htmlmathitalics -\htmladdress{\htmlrule{}info@neda.com} - -\c Declare which indices you want to make use of. -\newindex{cp} -\newindex{fn} - -\title{BBDB Input and Output Filters\\ - \vspace{0.25in} {\large DRAFT}\\ - {\normalsize Version 0.2}} - -\author{{\normalsize Prepared by}\\ - Mohsen Banan \\ - \code{mohsen@neda.com}\\ - Neda Communications, Inc.\\ - 17005 SE 31st Place\\ - Bellevue, WA 98008} - -\c (current-time-string) -\date{July 26, 1995} -\c \date{\today} - -\maketitle - -\c The following commands start the copyright page for the printed manual. -\clearpage -\vspace*{0pt plus 1filll} - - -\bigskip -\bigskip -\bigskip - - -This document describes the ``BBDB Input and Output Filters'' package, -a utility which translates BBDB information to and from various other -formats. - -\begin{display} - -Copyright \copyright 1995 Neda Communications, Inc. - -Published by: -Neda Communications, Inc. -17005 SE 31st Place, -Bellevue, WA 98008 USA - -\end{display} - - -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Foundation. - -\bigskip -\bigskip - -\clearpage -\pagestyle{headings} - -\c Use roman numerals for the page numbers and Insert the Table of Contents. -\pagenumbering{roman} -\tableofcontents - -\c \listoftables -\c \listoffigures - -\c End the Table of Contents and start numbering from 1 with Arabic numbers - -\clearpage -\pagenumbering{arabic} - -\c Anything before the setfilename will not appear in the Info file. -\setfilename{INFOFILE} - -\topnode{BBDB Filters} - -\htmlmenu{6} - -\begin{ifinfo} -Copyright \copyright \var{1995} \var{Neda Communications, Inc.} -\end{ifinfo} - -\c The Top node contains the master menu for the Info file. -\c This appears only in the Info file, not the printed manual. - -\chapter{Introduction} - -Over time much valuable data has been gathered in BBDB database files. -Many wish to share parts or all of this information with others. They -also wish to have access to this same information from other systems -(like personal digital assistants) lacking straightforward BBDB -access. - -For these reasons, we have prepared a family of filters that convert -the information in BBDB to and from a variety of other -formats. ``Output filters'' export BBDB information to other formats -while ``input filters'' import information from other formats into -BBDB. - -Our hope is that over time this collection of BBDB filters will grow -through contributed code. - -\section{About This Package} - -This package is a collection of filters and is called ``BBDB Input and -Output Filters''. It has been somewhat tested with BBDB version 1.50. -The present state of the software is still preliminary although it has -proved useful. - -\section{About This Manual} - -This documentation applies to Version 0.2 of the ``BBDB Input and -Output Filters'' package. The documentation is presently skeletal and -very preliminary. It mostly provides the user with instructions for -use, and very little background is included. Familiarity with Emacs -Lisp is assumed for some sections. - -\chapter{Output Filters} - -``Output filters'' are used to export BBDB information into formats -used by other systems. - -In general, an output filter uses the contents of your -\code{*BBDB*} buffer as input. Note that output filters do not use -BBDB files (typically `\code{~/.bbdb}') directly. - -An output filter is invoked by executing its associated lisp function. -The name of the function is conventionally named \code{bbdb-<system>-output} -(e.g., \code{M-x bbdb-hp200lx-output}). - -The result of running an output filter is to create a new buffer that -contains the \code{*BBDB*} information appropriately transformed into a -format suitable for use by the target system. The new buffer is given -a file name that you specify. - -\section{HP 200LX Phone Book} - -\cindex{HP 200LX Connectivity Pack} -This package has only been tested on HP 200LX palmtop systems. It -also requires the ``HP 200LX Connectivity Pack'' for converting -comma-delimited ASCII files into binary .PDB files which are read by -the HP 200LX Phone Book application. Version 1.00 of the ``HP 200LX -Connectivty Pack'' was used for testing. - -The HP 200LX output filter is in file \code{bbdb-hp200lx.el}. - -\begin{enumerate} - -\findex{bbdb-hp200lx-output} - -\item Invoke \code{M-x bbdb} to populate the \code{*BBDB*} buffer -with the contents you wish to export. - -\item Invoke \code{ bbdb-hp200lx-output} to create an ASCII .CDF -(Comma Delimited File). \cindex{.CDF file, HP 200LX Phone Book} - -\item Using Xlate/Merge option of HP Connectivity Pack convert the -.CDF file into a binary .PDB file used by the Phone Book program. -\cindex{.PDF file, HP 200LX Phone Book} - -\item Download the .PDB file to your palmtop's internal disk and -ensure that the Phone Book program is set use the newly downloaded -.PDB file. - -\end{enumerate} - -\section{PC Eudora} - -BBDB information can be exported to PC Eudora in two formats--as a -nickname database file and as a recipients database file. - -The PC Eudora output filter is in file \code{bbdb-eudora.el}. - -\subsection{PC Eudora Nickname Database} - -\begin{enumerate} - -\item Invoke \code{M-x bbdb} to populate the \code{*BBDB*} buffer -with the contents you wish to export. - -\findex{bbdb-eudora-nndbase-output} -\item Invoke \code{bbdb-eudora-nndbase-output} to create a PC Eudora -Nickname database file. - -\item Make the file accessible to PC Eudora. - -\end{enumerate} - -\subsection{PC Eudora Recipient Database} - -\begin{enumerate} - -\item Invoke \code{M-x bbdb} to populate the \code{*BBDB*} buffer -with the contents you wish to export. - -\findex{bbdb-eudora-rcpdbase-output} -\item Invoke \code{bbdb-eudora-rcpdbase-output} to create a PC Eudora -recipient's database file. - -\item Make the file accessible to PC Eudora. - -\end{enumerate} - -\section{Lotus cc:Mail Nicknames} - -The Lotus cc:Mail output filter is in file \code{bbdb-ccmail.el}. - -\begin{enumerate} - -\item Invoke \code{M-x bbdb} to populate the \code{*BBDB*} buffer -with the contents you wish to export. - -\findex{bbdb-ccmail-output} -\item Invoke \code{ bbdb-ccmail-output} to create a cc:Mail Nicknames file. - -\item Make the file accessible to cc:Mail. - -\end{enumerate} - -\section{PH} - -The PH output filter is in file \code{bbdb-ph.el}. - -\begin{enumerate} - -\item Invoke \code{M-x bbdb} to populate the \code{*BBDB*} buffer -with the contents you wish to export. - -\findex{bbdb-ph-output} -\item Invoke \code{bbdb-ph-output} to create a \code{ph} data file for -use with the \code{maked} program. - -\item Make the file accessible to \code{ph}. - -\end{enumerate} - -\section{Emacs Lisp Export} - -The Emacs Lisp Export output filter is in file \code{bbdb-export.el}. - -This output filter uses the current contents of your -\code{*BBDB*} buffer to generate a new buffer (\code{*BBDB* Export}) -that contains a single lisp \code{(progn ...)} expression. For -example, a \code{*BBDB*} buffer containing two records would result in -the following \code{*BBDB* Export} buffer: - -\begin{example} -;;; ======= Start of Exported BBDB Records ======= -(progn - (require 'bbdb-com) - (defun bbdb-maybe-create (name company net &optional addrs phones notes) - "Try to add a record to BBDB if it does not already exist." - (condition-case err - (progn - (bbdb-create-internal name company net addrs phones notes) - (message "%s %s added." name (if net (concat "<" net ">") "")) - (sleep-for 1)) - (error (ding) - (message "%s %s skipped. (%s)" - name - (if net (concat "<" net ">") "") - (car (cdr err))) - (sleep-for 1)))) - - (bbdb-maybe-create "Jill Doe--IMPORTED" - "CBS Corporation" - '("jilld@cbs.com") - '( - ["Home" - "368 222ND PL" - "" - "" - "Springfield" - "MA" 2117] - ) - '( - ["Office" 617 555 9983 0] - ) '"Movie Mogul") - (bbdb-maybe-create "John Doe--IMPORTED" - "ABC Incorporated" - '("jdoe@abc.com") - '( - ["Office" - "123 Any Street" - "" - "" - "Any Town" - "WA" (98027 7758)] - ) - '( - ["Office" 206 555 1234 0] - ) '"TV Producer") - ) -;;; ======= End of Exported BBDB Records ======= -\end{example} - -\cindex{Sending BBDB records via email} -This lisp expression can then be sent via email or some other -text-based messaging facility to another user who can then evaluate -the expression which will add the \code{BBDB} records to the -recipient's -\code{BBDB} database. - -Only new records are added. A record with the same name or net -address as one already existing in the \code{BBDB} is skipped -entirely. - -In the sample contents of a \code{*BBDB* Export} buffer presented, two -records are being exported--one for ``John Doe'' and the other for -``Jill Doe''. Notice that their names have been appended with -\code{--IMPORTED}. This string can be used to quick locate each record -that is added to the database using this mechanism. - -The following steps are for exporting BBDB records into Emacs Lisp: - -\begin{enumerate} - -\item Invoke \code{M-x bbdb} to populate the \code{*BBDB*} buffer -with the contents you wish to export. - -\findex{bbdb-export} -\item Invoke \code{bbdb-export} to create a \code{*BBDB* Export} buffer which contains a -single \code{(progn ...)} can be evaluated to add the records to the -existing \code{BBDB} database (if the records do not already exist). - -\item Use the contents of \code{*BBDB* Export} in email and other messaging systems. - -\end{enumerate} - -The following steps are for a user wishing to import the contents of a -\code{*BBDB* Export} buffer's expression into his or her own database: - -\begin{enumerate} - -\item Evaluate the region bounded by the lines \\ - \code{;;; ======= Start of Exported BBDB Records =======} \\ -and \\ - \code{;;; ======= End of Exported BBDB Records =======}. \\ -You can use such commands as -\code{M-x eval-region} or \code{M-x eval-last-sexp}. - -\item Review the newly imported entries. To see them, invoke \code{M-x -bbdb} and specify \code{--IMPORTED} at the \code{Regular Expression} -prompt. - -\item After reviewing the contents of the imported records, you may -wish to remove the \code{--IMPORTED} that is appended to the name by -\code{bbdb-export}. - -\end{enumerate} - -\chapter{Input Filters} - -``Input filters'' are used to import into BBDB information from a -foreign system's data file. - -The name of the function is conventionally named -\code{bbdb-<system>-input} (e.g., \code{bbdb-passwd-input} is the name -of the Emacs Lisp function for the UNIX password file input filter). - -In general, an ``input filter'' expects the foreign system's data to -be in the current buffer. The contents of the current buffer are used -to create an Emacs Lisp file which when loaded will add new records -into your BBDB database if they don't yet exist--existing BBDB records -will not be modified. - -\section{General Facilities for Input Filtering} - -The result of running an input filter is to produce a new buffer a -series of \code{bif-create-record} \findex{bif-create-record} -expressions, each corresponding to a single user's record. Notice -that input filters do not directly modify the contents of the BBDB -files (typically `\code{~/.bbdb}'). - -To actually modify the contents of the BBDB database, you must -evaluated the expressions in the resultant buffer created by the input -filter. One way to do so is simply to invoke \code{M-x eval-buffer}. -Another way is to simply save the buffer to disk and load its contents -into Emacs Lisp using \code{M-x load-file}. - -\section{UNIX Password Files} - -The UNIX password file input filter is in file \code{bbdb-passwd.el}. - -\begin{enumerate} - -\item Use \code{M-x find-file} to visit the UNIX password file you wish to import. - -\findex{bbdb-passwd-input} -\item With the password file in the current buffer, invoke the input -filter \code{M-x bbdb-passwd-input}. You will be prompted for the -domain name associated with that host's password file; an organization -name; as well as the file name to be associated with the buffer of -\code{bif-create-record} expressions. - -\item Evaluate the contents of the input filter's buffer to add records -into your BBDB database file. - -\end{enumerate} - -\chapter{Miscellany} - -\section{TODO List} - -\begin{itemize} - -\item Move generic input filter functionality out of -\code{bbdb-passwd.el} and into, say, \code{bbdb-ifilt.el}. -The generic functionality code has names typically prefixed with \code{bif-}. - -\item Add support for \code{gdbload} (as an alternative to the -Xlate/Merge application provided in the HP 200LX Connectivity Pack) -into the HP 200LX output filter. This is based on input from Robert -Nicholson \code{<robert@steffi.dircon.co.uk>}. - -\item Add documentation for variables in the various input and output filters. - -\item Check and document all dependencies on other packages. - -\end{itemize} - -\section{Credits} - -Pean Lim \code{<pean@neda.com>} wrote most of this package. Mohsen -Banan \code{<mohsen@neda.com>} put it all together and guided the -work. Neda Communications, Inc. sponsored the work. The output -filters code is based on \code{bbdb-print} by Boris Goldowsky\\ -\code{<boris@prodigal.psych.rochester.edu>}. - -\c ;;;;;;;;;;;;;;;; Appendix Starts Here ;;;;;;;;;;;;; -\appendix - -\mbinput{lgpl.tex} - -\begin{tex} -%\bibliography{/usr/local/lib/bib/gnu,/usr/local/lib/bib/networking,/usr/local/lib/bib/directory,/usr/local/lib/bib/rfcs} -\end{tex} - -\c \twocolumn -\node Concept Index, Top, First Chapter, Top -\unnumbered{Concept Index} - -\printindex{cp} - -\H \htmlprintindex - -\node Command Index, Top, First Chapter, Top -\unnumbered{Command Index} - -\printindex{fn} - -\end{document} - |