The Irssi Documentation Project

Project for irssi documentation.

Project start: 2003-02-26
Project members: reffie, Garion
Last update: 2003-03-04 by Garion

20030314 [Garion] Added info about templates and submitting.
20030314 [Garion] Added some more global properties for the docs.
20030314 [Garion] Added "scripts" and "config files" sections.
20030304 [Garion] Added pod as possible language alternative.


# ---------------------------------------------------------------------

What is the goal of this document?

As you might have noticed, there is no good and/or complete documentation
for irssi at this point in time.

This document shall determine a framework for irssi documentation, so
multiple people can start contributing to documentation for irssi.

# ---------------------------------------------------------------------

What is going to happen with this document?

First, it shall reside in the topic of #irssi for a while, to get as
much feedback as possible. When the document is nearing its final
first phase stages, it shall be sent to irssi-dev and irssi-users.

# ---------------------------------------------------------------------

Who is responsible for this document?

At the moment, reffie and Garion.

# ---------------------------------------------------------------------

How can I best comment on this document?

Emailing [email protected] with your comments is the preferred way.
Or join #irssi @ IRCnet and comment there.

Most importantly, we'd like to have your opinion on:
1) docbook
2) code commenting
See below for explanation.

Another way for you to help with this project is to collect FAQ questions,
with or without answers, and send them to [email protected]. This way, we
can already begin building a large collection of FAQ items and think
of a proper way to divide them into (sub)sections.

# ---------------------------------------------------------------------

What properties should irssi documentation have?

- It must be accessible through at least http, irssi, and command-line.
  (not _all_ the docs from below need be accessible inside irssi).
  
- It must all be in the same style/format.

- It must be searchable.

- It must be divided in logical sections, subsections and sub-sub-sections.

- It must be easy for someone to create help for a (sub)section.
  This means that anyone must be able to write help for a (sub)section
  without having to know what others have already written.

- In some way, the available link tags must be published somewhere. This
  way anyone who is writing help for a section can easily find out the
  names of links in other sections, so he/she can link to other sections
  without having to read them.

- It must be in some repository for easy version maintenance and
  moderation.


# ---------------------------------------------------------------------

Sections and subsections

* How to use the online documentation, and how/where to ask for further help

* Introduction - basic tasks in irssi
  * your first steps
  * joining/parting channels
  * creating queries/dcc chats
  * switching windows
  * showing and changing settings
  * creating and using aliases
  * creating and using keybindings
  * saving your settings and window layout

* Windowing - all help about window management
  * the statuswindow
  * creation, destruction
  * automatic creation and destruction
  * switching windows
  * moving around window items between windows
  * statusbars - creation and configuration
      [should statusbars be a separate section?]
  * split windows vs hidden windows
  * setting/changing window levels

* Advanced commands in irssi
  * hilight
  * ignore
  * upgrade
  * logging
  * using <tab> completion
  * completion
  * notify
  * executing shell commands
  * executing perl script commands
  * Irssi-proxy - explanation and tutorial

* Servers, channels, queries
  * proper ircnet/server/channel config
  
* Using Scripts - installing, upgrading, (auto)running scripts
  * introduction
  * getting scripts
  * (auto)running scripts
  * scriptassist

* Formats, themes, levels - a section with some leftovers
  * colors
  * existing formats
  * message levels

* Settings
  * list and explanation of all settings
  * list of all keybindings

* Config files
  * ~/.irssi/config
  * ~/.irssi/default.theme
  * runnig multiple irssis with different configuration files

* Scripting - all help about writing scripts
  * introduction (plus Your First Script)
  * headers
  * classes with members and member functions
  * signals with description and arguments
  * use Irssi::<whatever> descriptions
  * interaction between scripts
  * timers and delays
  * getting data from a server (/whois, /who)
  * getting properties of channels/clients
  * window functions (create, move, send text to)
  * message levels usage (MSGLEVEL_*)
  * creating and using new formats
  * theme functions
  * special variables
  * using numerics
  * statusbar items
  * finishing up your script - good practices
  * submitting your script to the scripts archive

* Command reference
  * all commands, alphabetically ordered
    [this is what you will get when you do /help <function> in irssi]

* FAQ - Frequently Asked Questions

* Installing irssi
  * per OS
  * in your homedir, if you don't have root privileges

* Switching - switching from a different client to irssi: why and how?
  * from BitchX
  * from ircii
  * from EPIC
  * from ScrollZ
  * from xchat
  * from mIRC or other windows GUI clients

* Troubleshooting - what to do when you encounter problems
  * what to do when you can't get your script working
  * error messages during startup


* About irssi - copyright, credits, etc

* Glossary - terms and abbreviations

# ---------------------------------------------------------------------

The Language of the documentation.

Obviously, to save effort, this documentation should be written in
some language that can easily be converted to other 'languages', like
HTML, manpages, irssi help files, whatever.

Also, it must allow formatting, linking, keyword definition, etc.

It seems that docbook is a good choice for this.

Creating docbook documents is apparently not easy to do in a text
editor, unless it is capable of docbook syntax highlighting. One of the
tools that could be used to create docbook documents is LyX, which is
available for both *nix and windows.

A possible alternative seems to be wiki, which is a way to make shared
documents via a browser. But, is this also a viable way to get indexed
and searchable docs?

Another alternative is pod. This is a bit like doc++ and javadoc, but
then for perl.


Comments? Alternatives? Argumentation?

# ---------------------------------------------------------------------

Templates and acceptance of submitted documentation

As soon as the language for the documentation has been chosen, one of
the first things that needs to be done is the creation of documentation
templates. This will ensure that all (sub)sections of the documentation
will have the same look and layout, and that someone who wants to write
some documentation will have an easy start.

Additionally, a document on "how to create irssi documentation for a 
(sub)section" needs to be made.

And finally, some process of moderation (everything submitted to the
documentation should be reviewed, of course) and then storage of the
submitted (sub)section into the irssi documentation storage area needs
to be done.

# ---------------------------------------------------------------------

Problems

One of the main problems there will probably arise is keeping the API 
documentation in sync with irssi's code.
If cras (the author of irssi) changes the arguments of a certain
event, this must be updated in the documentation as well.

This points towards code-comments generated documentation, for a part
of the documentation at least.

# ---------------------------------------------------------------------

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (GNU/Linux)

iD8DBQE+cyxXgEZhu2/y6RgRArJiAJ9ZijgyLbp4eZ2Tg8TmcLw6Pc+7EwCgiRcR
mb8OFKAcLN7OWJG8I0JqvoI=
=Zx8C
-----END PGP SIGNATURE-----