[elpa] externals/rcirc-sqlite 804826dde3 5/6: Separated README and manual

[ELPA Syncer]

branch: externals/rcirc-sqlite
commit 804826dde3fe1cfdd1fee21ca768ac87e93ea32b
Author: matto <matto@matto.nl>
Commit: matto <matto@matto.nl>

    Separated README and manual
---
 README.org                     | 356 +++++------------------------------------
 README.org => rcirc-sqlite.org |   4 +-
 2 files changed, 42 insertions(+), 318 deletions(-)

diff --git a/README.org b/README.org
index 192fed3688..08b69de9ae 100644
--- a/README.org
+++ b/README.org
@@ -1,15 +1,7 @@
-#+TITLE:rcirc logging in SQLite
-#+AUTHOR: Matto Fransen
-#+TEXINFO_DIR_CATEGORY: Emacs misc features
-#+TEXINFO_DIR_TITLE: rcirc-sqlite: (rcirc-sqlite) 
-#+TEXINFO_DIR_DESC: rcirc logging in SQLite
-#+EXPORT_FILE_NAME: rcirc-sqlite.texi
-#+TEXINFO_FILENAME: rcirc-sqlite.info
-
-* Introduction
-:PROPERTIES:
-:ID:       c8cd5551-bf7c-11ee-aa8a-5cff350aad6a
-:END:
+* rcirc-sqlite: rcirc logging in SQLite
+
+Find here the source for ~rcirc-sqlite.el~, that stores the logging from
+~rcirc~ into a SQLite database.
 
 ~rcirc~ is a default, simple IRC client in Emacs. rcirc can be enable to
 log the IRC chats, it logs to files.
@@ -17,25 +9,8 @@ log the IRC chats, it logs to files.
 This minor mode, when activated, diverts the rcirc logs to a SQLite
 database.
 
-It also comes with some functionality to query the SQLite database.
-
-* Requirements
-:PROPERTIES:
-:ID:       f1a62fea-bc80-11ee-a315-5cff350aad6a
-:END:
-
-~rcirc-sqlite~ relies on the capability of Emacs to work together
-with SQLite. 
-
-- Emacs must be compiled with this capability.
-- SQLite 3 must be installed on the system.
 
 * Installation and activation
-:PROPERTIES:
-:ID:       fac7e092-bc80-11ee-a315-5cff350aad6a
-:END:
-#+findex: Installation
-
 ** Installation
 Create a directory for the package.
 
@@ -47,186 +22,47 @@ At this directory as a load path to your init file:
 
 #+begin_src emacs-lisp
 (add-to-list 'load-path "~/.emacs.d/manualpackages")
+(require 'rcirc-sqlite)
 #+end_src
 
 Re-evaluate your init file or restart Emacs, whatever you prefer.
 
-[[id:f1a62fea-bc80-11ee-a315-5cff350aad6a][Requirements]] describes the 
requirements.
-
 ** Activation
-:PROPERTIES:
-:ID:       fcca2f42-bc80-11ee-a315-5cff350aad6a
-:END:
-#+findex: Activation
-#+findex: rcirc-sqlite-log-mode
-
-- Command: rcirc-sqlite-log-mode ::
-  Activates or deactivates ~rcirc-sqlite~.
+The command ~rcirc-sqlite-log-mode~  toggles between activation
+and deactivation of ~rcirc-sqlite~.
 
-Issue the command ~rcirc-sqlite-log-mode~ to manually start
-~rcirc-sqlite~. This command toggles between activation
-and deactivation of ~rcirc-sqlite~. 
 
-To start ~rcirc-sqlite~ automatically when ~rcirc~
-is started, add the following to your init file:
+To start ~rcirc-sqlite~ automatically when ~rcirc~ is started, add the
+following to your init file:
 
 #+begin_src emacs-lisp
 (require 'rcirc-sqlite)
 (add-hook 'rcirc-mode-hook #'rcirc-sqlite-log-mode)
 #+end_src
 
-While ~rcirc-sqlite~ is activated, ~rcirc~ will no longer
-write the logs to files, until ~rcirc-sqlite~ is deactivated.
-Deactivate ~rcirc-sqlite~ using the command
-~rcirc-sqlite-log-mode~ again.
-
-The logging must be enabled in ~rcirc~.
-To do this, add for example the following to your init file:
-
-#+begin_src emacs-lisp
-(setq rcirc-log-flag t)
-#+end_src
-
-* Customization
-:PROPERTIES:
-:ID:       f4517d9c-bc80-11ee-a315-5cff350aad6a
-:END:
-
-To customize ~rcirc-sqlite~ run ~M-x customize-group rcirc-sqlite~,
-or use ~(setopt ...)~ in your init file, like ~/.emacs~.
-For example:
-
-#+begin_src emacs-lisp
-(setopt rcirc-sqlite-rows 100)
-#+end_src
-
-The user may custimize the following options.
-
-- User Option: rcirc-sqlite-database ::
-  The file in which SQLite stores the database.
-
-#+vindex: rcirc-sqlite-database
-
-The file in which SQLite stores the database can be customized.
-
-The default file is ~ricirc-log.db~, located in the default Emacs
-directory (e.g., ~~/.emacs.d/ricirc-log.db~).
-
-Set this option to use a different file.
-
-- User Option: rcirc-sqlite-time-format ::
-  The format for the date and time in the buffer ~*rcirc log*~.
-
-#+vindex: rcirc-sqlite-time-format
-
-The variable ~rcirc-sqlite-time-format~ describes the date and
-time format which is used when displaying the chat messages.
-
-This variable only influences how the date and time is formatted
-in the buffer ~*rcirc log*~.
-
-The default format is ~%Y-%m-%d %H:%M"~.
-
-Set this option to use a different time format in the buffer
-~*rcirc log*~.
+* Usage
+Use the following commands to query the database.
 
-- User Option: rcirc-sqlite-rows ::
-  The default maximum number of rows when viewing logs.
-
-#+vindex: rcirc-sqlite-rows
-
-The variable ~rcirc-sqlite-rows~ describes the maximum number
-of rows to display when viewing the chat logs.
-
-This only affects when viewing the chat logs. Search results are
-always shown unabridged.
-
-[[id:03ec6364-bc81-11ee-a315-5cff350aad6a][View the logs]] describes the 
command to view the logs.
-
-The default value is 200 rows.
-
-Set this option to change the default number of lines.
- 
-- User Option: rcirc-sqlite-channel-column-width ::
-  The default column width of the channel column in the buffer
-  ~*rcirc log*~.
-
-#+vindex: rcirc-sqlite-channel-column-width
-
-The variable ~rcirc-sqlite-channel-column-width~ describes the
-default width of the column that displays the channel names.
-
-The default value is 40 chars.
-
-Change this option to let the channel names be shown in a smaller or
-wider column in the buffer ~*rcirc log*~.
-
-[[id:126b1bec-bc81-11ee-a315-5cff350aad6a][The buffer ~*rcirc log*~]] has more 
information on this buffer.
-
-* Commands
-:PROPERTIES:
-:ID:       016dc6b9-bc81-11ee-a315-5cff350aad6a
-:END:
-** Summery of the commands
-#+vindex: command summary
-
-- ~M-x circ-sqlite-view-log~: display the logs.
+- ~M-x rcirc-sqlite-view-log~: display the logs.
 - ~M-x rcirc-sqlite-text-search~ perform full text search in the logs.
 - ~M-x rcirc-sqlite-stats~ displays some stats.
 
-** View the logs
-:PROPERTIES:
-:ID:       03ec6364-bc81-11ee-a315-5cff350aad6a
-:END:
-#+findex: rcirc-sqlite-view-log
-
-- Function: rcirc-sqlite-view-log channel &optional unlimited offset limit ::
-  Display the logs in a new buffer.
-
-Issue the command ~M-x rcirc-sqlite-view-log~ to view the logs
-of a specific channel. Default this command shows the last 200
-lines. This number can be changed by setting the variable
-~rcirc-sqlite-rows~. 
+** ~rcirc-sqlite-view-log~
+Default this commands shows the last 200 messages, optionally narrowed
+to a specific channel, or month.
 
-This command prompts the user for the channel and provides a list
-of available channels. Choose a channel using completion. 
-Choose the option ~All channels~ to show the last 200 lines of the
-chat log of *all* channels.
 
-Next, the user is prompted for a month, choose a month using
-completion.  When a month is choosen, the last 200 lines the chat log
-from that month are shown.  Choose the option ~Anytime~ or the
-latest month to get the most recent 200 lines.
+** ~rcirc-sqlite-text-search~
+Perform full text searches in the database.
 
-The buffer ~*rcirc log*~ displays the chat logs.
+Prompts:
 
-@subheading Optional arguments
+- for a search string
+- for a channel
+- for a month
+- for a nick
 
-This function has three optional arguments, ~unlimited~,
-~offset~, and ~limit~.
-
-- ~unlimited~
-  When non nil, ~rcirc-sqlite-view-log~ will show *all*
-  log lines in the database of the channel.
-- ~offset~ and ~limit~
-  Use ~offset~ and ~limit~ to select a number of lines from
-  the log lines in the database of the channel.
-
-** Full text search and load the result in a buffer
-#+findex: rcirc-sqlite-text-search
-
-- Function: rcirc-sqlite-text-search query channel nick ::
-  Perform full text search.
-
-Issue the command ~M-x rcirc-sqlite-text-search~ to perform
-full text search in the logs.
-
-When this command is issued:
-
-- The user is prompted for a search string.
-- The user is prompted to choose a channel (through completion).
-- The user is prompted to choose a specific month (through completion).
-- The user is prompted to choose a nick (through completion).
+Completion is used to choose a channel, month, or nick.
 
 When a channel is chosen, the search is performed within the
 chat logs of that specific channel. Choose ~All channels~ to
@@ -253,23 +89,8 @@ Likewise, to search for URLs, use something like 
~"http://*"~ or
 ~"gopher://*"~. Because of the colon (~:~), the double
 quotes (~"~) here are required.
 
-For more formatting of the search see the chapter ~Full-text
-Query Syntax} of the SQLite documentation (see
-~https://www.sqlite.org/fts5.html~).
-
-The buffer ~*rcirc log*~ displays the search results.
-
-** Stats
-:PROPERTIES:
-:ID:       0d1bc484-bc81-11ee-a315-5cff350aad6a
-:END:
-#+findex: rcirc-sqlite-stats
-
-- Function: rcirc-sqlite-stats nick ::
-  Create overview with some stats
-
-Issue the command ~M-x rcirc-sqlite-stats~ to get an overview
-of the number of rows (lines) in the database.
+** ~rcirc-sqlite-stats~
+This command gives an overview of the number of messages in the database.
 
 The user is prompted for a nick. Choose a nick through completion.
 
@@ -286,115 +107,18 @@ each channel the number of uniq nicks.
 When ~Channels per nick~ is chosen, the buffer shows for
 each nick the number of channels with messages from this nick.
 
-* The buffer ~*rcirc log*~
-:PROPERTIES:
-:ID:       126b1bec-bc81-11ee-a315-5cff350aad6a
-:END:
-
-The buffer ~*rcirc log*~ is used to show the output of the
-database queries. This buffer uses a derived mode from the
-~tabulated-list-mode~.  The default key bindings of the
-~tabulated-list-mode~ are available in this buffer.
-
-Some key binding examples:
-
-- Key: S (Sort) ::
-  Sort the buffer according to the values of the column of point.
-  
-  Use a numeric prefix argument N to sort the buffer according to the
-  values of the N-th column from point. Repeat to sort in the alternate
-  order (ascending or descending).
-
-- Key: @} ::
-  Widen the current column by N (the prefix numeric
-  argument) characters,
-
-- Key: @{ ::  
-  Narrow the current column by N (the prefix numeric
-  argument) characters.
-
-- Key: SPACE ::
-  Scroll the buffer up.
-
-- Key: BACKSPACE ::
-  Scroll the buffer down.
-
-- Key: n ::
-  Move down one screen line (next line).
-
-- Key: p ::
-  Move up one screen line (previous line).
-
-- Key: q ::
-  Close the buffer.
-
-* Inner workings
-:PROPERTIES:
-:ID:       179764f3-bc81-11ee-a315-5cff350aad6a
-:END:
-#+findex: rcirc-log-write
-#+findex: rcirc-sqlite-store-log
-
-~rcirc~ caches the IRC messages in a list, and periodically
-writes the contents of this cache to the log files.
-~rcirc-sqlite~ collects the contents of this cache.
-
-~rcirc-sqlite~ overrides the ~rcirc~-function
-~rcirc-log-write~ with the ~rcirc-sqlite~-function
-~rcirc-sqlite-store-log~ for this.
-
-To be able to easy parse the timestamp, ~rcirc-sqlite~ changes
-the ~rcirc-log-time-format~. It does this by advising around the
-~rcirc~-function rcirc-log.
-
-** Delay
-
-There is some delay between the arrival of chat messages in the chat
-buffer and the storage of the logs in the database.
-
-~rcirc~ uses the auto-save functionality to trigger the flushing
-of the cache to the log file. Hence, the storage of the chat logs to
-the SQLite database by ~rcirc-sqlite~ is also triggered by the
-auto-save functionality.
-
-* Database schema
-:PROPERTIES:
-:ID:       1a4a9a49-bc81-11ee-a315-5cff350aad6a
-:END:
-
-The SQLite database is created at the first time ~rcirc-sqlite~
-flushes the cache. The SQLite database is populated with a virtual
-table, using the SQLite FTS5 Extension. The schema of this table has
-the following fields.
-
-- channel:
-  This is the channel name in the format ~rcirc~ uses to
-  determine the log file. This format is
-  ~channelname~@@~servername~.log, for example
-  ~#rcirc@@LiberaChat.log~.
-- time:
-  The timestamp, stored in the unix timestamp format.
-- nick:
-  The nick name of the sender.
-- message:
-  The actual chat message.
-
-
-* GNU Free Documentation License
-:PROPERTIES:
-  :APPENDIX: t
-  :END:
-
-  #+INCLUDE: fdl.org
-
-* Command and Function Index
-:PROPERTIES:
-:DESCRIPTION: Command names and some internal functions.
-:INDEX:    fn
-:END:
-
-* Variable Index
-:PROPERTIES:
-:DESCRIPTION: Variables mentioned in the manual.
-:INDEX:    vr
-:END:
+* Contribute
+A copyright assignment to the FSF is required for all non-trivial code
+contributions.
+
+* Source code
+~rcirc-sqlite~ is developed at 
[[https://codeberg.org/mattof/rcirc-sqlite][Codeberg]].
+
+* Bugs and patches
+Please use the "Issues" option in the Codeberg repository.
+
+* Distribution
+~rcirc-sqlite.el~ and all other source files in this directory are
+distributed under the GNU Public License, Version 3, or any later
+version.
+
diff --git a/README.org b/rcirc-sqlite.org
similarity index 99%
copy from README.org
copy to rcirc-sqlite.org
index 192fed3688..2982773f2b 100644
--- a/README.org
+++ b/rcirc-sqlite.org
@@ -170,7 +170,7 @@ wider column in the buffer ~*rcirc log*~.
 ** Summery of the commands
 #+vindex: command summary
 
-- ~M-x circ-sqlite-view-log~: display the logs.
+- ~M-x rcirc-sqlite-view-log~: display the logs.
 - ~M-x rcirc-sqlite-text-search~ perform full text search in the logs.
 - ~M-x rcirc-sqlite-stats~ displays some stats.
 
@@ -269,7 +269,7 @@ The buffer ~*rcirc log*~ displays the search results.
   Create overview with some stats
 
 Issue the command ~M-x rcirc-sqlite-stats~ to get an overview
-of the number of rows (lines) in the database.
+of the number of rows (messages) in the database.
 
 The user is prompted for a nick. Choose a nick through completion.