Info file sdoc, handmade docs for Sdoc, -*- Text -*-  File: sdoc, Node: Top, Next: Copyright, Prev: (dir), Up: (dir) This Info file contains documentation for version 1.00 of the Sdoc documentation browsing package for GNU Emacs. This package is NOT a part of GNU Emacs. * Menu: * Copyright:: Legal stuff. * Introduction:: What can Sdoc do for you? * Usage:: It is really simple. * Setup:: User configuration. * Installation:: Making Sdoc available on your system. Database management * Creating a database:: * Adding to a database:: * Merging databases:: Information intented for Sdoc programmers. * Implementation:: From one programmer to another.  File: sdoc, Node: Copyright, Next: Introduction, Prev: Top, Up: Top Copyright © 1995 Torbjörn Axelsson This file is NOT part of the GNU Emacs. Verbatim copies of this file may be freely redistributed together with the elisp file sdoc.el. Modified versions of this file may be redistributed provided that this notice remains unchanged, the file contains prominent notice of author and time of modifications, and redistribution of the file is not further restricted in any way. This file is distributed `as is', without warranties of any kind. To contact the author, send email to torax@ctrl-c.liu.se. History: v1.00 1995-01-14: Developped using GNU Emacs 18.58, Amiga port1.26DG Features searching, adding matches and merging databases. (Not to mention this info file!)  File: sdoc, Node: Introduction, Next: Usage, Prev: Copyright, Up: Top When you have collected a bunch of programming packages for interfacing with anything from the graphics and sound system of your computer to your grandmothers dog, with documentation files ranging from "hi-there-try-this-out" readme file through unix-look-alike man pages and Amiga AutoDocs to hypertext type documents like Info files and AmigaGuide it is easy to get confused. And if you prefer using your Emacs for programming, you don't want to start three or four other programs to look for the information you need. The answer can be Sdoc, the documentation browser that extract precisely the information you need as simple as the other help commands in emacs. The recommended setup brings Sdoc right under your normal help key. (Mostly ^H.) Sdoc is also a kin of tags, in that you use keywords and positions in files, but while the tags system will move you to a position in a file, Sdoc will extract information from a part of a file and display information from all sources at once.  File: sdoc, Node: Usage, Next: Setup, Prev: Introduction, Up: Top If you have a database installed correctly, just invoke the command sdoc. (ex M-x sdoc) Sdoc will prompt for a regexp to search for and show the results in a buffer (*Sdoc). For each match found, Sdoc will print something like: 1> Sdoc looking for: RT.* > 2> #define found: RTS 3> Data file: /usr/include/devices/serial.h > ----------S-T-A-R-T---------- 4> #define RTS 0x10 > ----------E-N-D-------------- (excluding line numbers and the > signs of course) Line 1 says what regexp Sdoc is searching for. (In this case all keywords that begin with the characters RT, regardless of case.) Line 2 means that the type of match was "#define" and that the keyword matched was RTS. Line 3 says that the file that holds the #define was /usr/include/devices/serial.h. Line 4 (actually any number of lines between START and END) is the informationabout the keyword. More than one match can typically be found, and from several files.  File: sdoc, Node: Setup, Next: Installation, Prev: Usage, Up: Top The variable sdoc-buffer is a string holding the name of the Sdoc output buffer. It defaults to "*Sdoc*". The variable sdoc-database is a string with the full path of your Sdoc database file. This variable can either default to a standard system database or be useless depending on system setup. To set up sdoc for use, add the following to your .emacs: ; Sdocs interactive functions (autoload 'sdoc "sdoc" nil t) (autoload 'sdoc-add-region-as-match "sdoc" nil t) (autoload 'sdoc-merge-buffer-to-database "sdoc" nil t) ; Give Sdoc a place under help. (define-key help-map "h" 'sdoc) ; to use your own database: (setq sdoc-database "full path to the database")  File: sdoc, Node: Installation, Next: Creating a database, Prev: Setup, Up: Top To make Sdoc part of your Emacs environment install the sdoc.el (or preferably the compiled sdoc.elc) somewhere along the load-path of your emacs and add this info file to the info tree. If you wish, edit sdoc.el so that sdoc-database holds the path of a system database file and create that database.  File: sdoc, Node: Creating a database, Next: Adding to a database, Prev: Installation, Up: Top To create a new database, set the sdoc-database variable and start adding entries using whatever tools you have. (sdoc-add-region-as-match and sdoc-merge-buffer-to-database are currently the only available ways to do this.)  File: sdoc, Node: Adding to a database, Next: Merging databases, Prev: Creating a database, Up: Top The easy, but painfully slow, way to add database match entries is to use *note :sdoc-add-region-as-match. When called interactively, it will add the current region as an entry in the database, prompting for matchstring and matchtype. A lot faster way would be to have a tool create all those matches for you automatically by scanning include and documentation directories. Hopefully someone (looking at me? ok, working on it, no promises) will take the time to do this.  File: sdoc, Node: Merging databases, Prev: Adding to a database, Up: Top To merge two databases, load the database with the new definitions as a normal file and call *note sdoc-merge-buffer-to-database. Typically this would be done after a database tool has created a temporary Sdoc database buffer.  File: sdoc, Node: Implementation, Prev: Top, Up: Top The sdoc implementation is rather straightforward, since it started as (and still is) a "quick hack". It has however been through a couple of rewrites and as it is now should be usable. The menu below lists all functions and variables along with some design clarifications. * Menu: * File format:: Configuration variables * sdoc-buffer:: * sdoc-database:: User level interface functions * sdoc:: * sdoc-add-region-as-match:: * sdoc-merge-buffer-to-database:: Programmer level interface functions * sdoc-databasep:: * sdoc-add-match:: * sdoc-grab-match:: Low level assist functions * sdoc-print:: * sdoc-grab-filename:: * sdoc-grab-matchtype:: * sdoc-grab-filter:: * sdoc-add-filename:: * sdoc-add-matchtype:: Buffer local variables for internal use in database buffers * sdoc-eofiles:Sdoc buffer variables. * sdoc-botypes:Sdoc buffer variables. * sdoc-eotypes:Sdoc buffer variables. * sdoc-bomatches:Sdoc buffer variables.  File: sdoc, Node: File format, Prev: Implementation, Next: sdoc-buffer, Up:Implementation The database file (or buffer) has three parts delimited by ^L. The first section are the filenames, complete paths to all files that has references. The second section contains matchtypes. A matchtype is a short (preferably one word) description of what kind of match you have. The types can have filter functions attached to them, and the name of the filter function to use is separated with a ^L on the same line. The third section has actual match descriptions, on each line are a matchstring, a filenumber, a typenumber, a starting and an ending position in the file separated by ^L. Messy? Ok, I'll try using BNF: -> ^L ^L -> | -> A string with the complete path to a file containing data for a reference in the database. -> | -> | ^L -> A string that tells the user what kind of match this is. -> A string with the name of a filter function -> | -> ^L ^L ^L ^L -> A string to match against when searching the database. -> A string with the number of the entry to use. -> A string with the number of the entry to use. -> A string with the starting position of the information. -> A string with the end position of the information. What? Still confused? Then a small example: The file Explanation filename1 - Full path file names. filename2 ^L typename0^Lfilter-func - filter-func filters output. typename1 - No need to filter data. ^L foo^L1^L1^L42^L4711 - Information about "foo" is in the file "filename1" between position 42 and 4711. The type of information is typename1 and it can be read as extracted. Any questions? Mail me at the adress mentioned in *note Copyright::.  File: sdoc, Node: sdoc-buffer, Prev: File Format, Next: sdoc-database, Up: Implementation sdoc-buffer is a user level configuration variable. This variable is the name of the buffer Sdoc uses to print its output in. Defaults to "*Sdoc*".  File: sdoc, Node: sdoc-database, Prev: sdoc-buffer, Next: sdoc, Up: Implementation sdoc-buffer is a system/user level configuration variable. This variable holds the full path to your Sdoc database file. Defaults depends on system configuration.  File: sdoc, Node: sdoc, Prev: sdoc-database, Next: sdoc-add-region-as-match, Up: Implementation sdoc is a user level retrieval function. The main user interface. Takes one argument that can be read from the minibuffer and matches it against match entries of the database file named in sdoc-database, presenting all information in the sdoc-buffer. See *note Usage::  File: sdoc, Node: sdoc-add-region-as-match, Prev: sdoc, Next: sdoc-merge-buffer-to-database, Up: Implementation sdoc-add-region-as-match is a user/programmer level storage function. sdoc-add-region-as-match is used to add part of a text file as a match. If called interactively, it will ask for a matchtype entry and a matchstring id for the match. Then it will add to the database that the matchstring id has information of type matchtype in the file of the current buffer in the current region. When called from another lisp function, supply ID, MATCHTYPE, STARTPOS and ENDPOS as arguments, still refering to the current buffer. No filter function can be used with this function when called interactively, but an optional fifth argument FILTER can be added when called through lisp.  File: sdoc, Node: sdoc-merge-buffer-to-database, Prev: sdoc-add-region-as-match, Next: sdoc-databasep, Up: Implementation sdoc-merge-buffer-to-database is a user/programming level storage function. Can be called interactively, will add BUFFER (defaults to current buffer) which has to be a correct Sdoc database to the current Sdoc database.  File: sdoc, Node: sdoc-databasep, Prev: sdoc-merge-buffer-to-database, Next: sdoc-add-match, Up: Implementation sdoc-databasep is a programmer level predicate function. A predicate function that checks if BUFFER is correctly formatted to be an Sdoc database, and if so sets the Sdoc buffer local variables: sdoc-eofiles sdoc-botypes sdoc-eotypes and sdoc-bomatches. (See *note Sdoc buffer variables::) Of course returns t if BUFFER is an Sdoc database buffer and nil if it is not.  File: sdoc, Node: sdoc-add-match, Prev: sdoc-databasep, Next: sdoc-grab-match, Up: Implementation sdoc-add-match is a programmer level storage function. This function is the basis for adding to an Sdoc database buffer. Takes two arguments, a required MATCH entry and an optional BUFFER. Default is the _current_ buffer, not necessarily the Sdoc database buffer. If MATCH is nil, sdoc-add-match will return immediately with nil. If BUFFER is an Sdoc database buffer, then sdoc-add-match will add the MATCH to the database in BUFFER. If the buffer is completely empty, sdoc-add-match will initialize it as a database holding the single MATCH. If sdoc-add-match succeds, it will return t. If the buffer is not an Sdoc database and non-empty, sdoc-add-match will fail "Trying to add a match to a non sdoc database buffer.". The format of the match entry is a list: (matchstring filename matchtype filter startpos endpos) matchstring - string with the id of the match filename - string with the complete filename to look up matchtype - string saying what type of match this is filter - string with the name of the filter function or nil if no filter needed startpos, endpos - integers with the start and end of the region to display  File: sdoc, Node: sdoc-grab-match, Prev: sdoc-add-match, Next: sdoc-print, Up: Implementation sdoc-grab-match is a programmer level retrieval function. sdoc-grab-match takes two arguments, REGEXP and optional BUFFER. The default BUFFER is sdoc-database. Starting from current point in BUFFER, it searches forward for a match and if a match is found, sets point to the beginning of the line following the match and returning the match as a list on the same format as *note sdoc-add-match::. Normally REGEXP begins with ^ and ends with ^L to match only the keyword part of the match entries. To start a search of the whole database, do (goto-char sdoc-bomatches) in BUFFER before calling sdoc-grab-match.  File: sdoc, Node: sdoc-print, Prev: sdoc-grab-match, Next: sdoc-grab-filename, Up: Implementation sdoc-print is a low level general utility function. sdoc-print should possibly be a macro, since all it does is (mapcar 'princ l). I use it to print multiple objects to stdout.  File: sdoc, Node: sdoc-grab-filename, Prev: sdoc-print, Next: sdoc-grab-matchtype, Up: Implementation sdoc-grab-filename is a low level retrieval function. Takes a FILENUMBER and optionally a BUFFER (defaulting to current buffer) as arguments and returns a string with the filename.  File: sdoc, Node: sdoc-grab-matchtype, Prev: sdoc-grab-filename, Next: sdoc-grab-filter, Up: Implementation sdoc-grab-matchtype is a low level retrieval function. Takes a MATCHTYPENUMBER and optionally a BUFFER (defaulting to current buffer) as arguments and returns a string with the type for that matchtype.  File: sdoc, Node: sdoc-grab-filter, Prev: sdoc-grab-matchtype, Next: sdoc-add-filename, Up: Implementation sdoc-grab-filter is a low level retrieval function. Takes a MATCHTYPENUMBER and optionally a BUFFER (defaulting to current buffer) as arguments and returns a string with the filter function, or nil if there is no filter for that matchtype.  File: sdoc, Node: sdoc-add-filename, Prev: sdoc-grab-filter, Next: sdoc-add-matchtype, Up: Implementation sdoc-add-filename is a low level storage function. Adds FILENAME to the files section of current buffer if it's not there allready, will always return the filenumber.  File: sdoc, Node: sdoc-add-matchtype, Prev: sdoc-add-filename, Next: sdoc buffer variables, Up: Implementation sdoc-add-matchtype is a low level storage function. Take a MATCHTYPE as argument, and optionally a FILTER. Will add this MATCHTYPE/FILTER pair to the matchtypes section of the database if it is unique. Will always return the matchnumber for this matchtype/filter pair.  File: sdoc, Node: Sdoc buffer variables, Prev: sdoc-add-matchtype, Up: Implementation These four buffer local variables hold markers for the limits of the parts of the database. sdoc-eofiles The end of the files section. sdoc-botypes The beginning of the types section. sdoc-eotypes The end of the types section. sdoc-bomatches The beginning of the matches section. The main use of these are (goto-char sdoc-bomatches) before you start searching for matches in the database.