2874f74c81
the rationale behind switching away from SGML/Docbook is the following:
* SGML is hard to edit for humans
* the output is not much prettier
* the toolchain is not well supported and missing from the build
* the build is not hooked into anywhere, no automation
the reason why RST was chosen:
* it allows for a strong structure like Docbook
* the theme from Read The Docs is pretty
* it also supports mobile devices
* sphinx can easily output to PDF and ePUB formats
* RST is plaintext that can be easily edited and diff'd
* RST can be automatically built by ReadTheDocs and the toolchain is
readily available
* the output is also parsed by Github so documentation can be read
straight from GH
the reason why Markdown was not chosen:
* the current strong structure would be hard to replicate
* markdown is not standardized and output varies according to the
implementation
the docs were converted with Pandoc, using the following commands:
mkdir oper-guide
for source in sgml/oper-guide/*.sgml; do
pandoc --toc -s -f docbook -t rst $source -o oper-guide/$(basename $source .sgml).rst
done
cd oper-guide
sphinx-quickstart
git add *.rst make.bat conf.py
git add -f Makefile
git rm -r ../sgml
24 lines
733 B
ReStructuredText
24 lines
733 B
ReStructuredText
.. contents::
|
|
:depth: 3
|
|
..
|
|
|
|
Introduction
|
|
============
|
|
|
|
Scope of this document
|
|
======================
|
|
|
|
This document describes the commands and functions available to
|
|
operators in the charybdis ircd, as used on
|
|
`AthemeNet <http://www.atheme.net>`__.
|
|
|
|
This document, and various ideas for features of charybdis, have been
|
|
taken from dancer-ircd/hyperion, the ircd used on freenode, mainly
|
|
written by Andrew Suffield and Jilles Tjoelker.
|
|
|
|
While this document may be of some interest to the users of charybdis
|
|
servers, it is intended as a reference for network staff.
|
|
|
|
Charybdis is based on ircd-ratbox 2.1.4, although much has changed.
|
|
`ircd-ratbox <http://www.ircd-ratbox.org>`__ is commonly used on efnet,
|
|
and some other networks.
|