]> jfr.im git - solanum.git/commit - doc/oper-guide/ucommands.rst
convert SGML guide to RST
authorAntoine Beaupré <redacted>
Sat, 25 Mar 2017 14:42:32 +0000 (10:42 -0400)
committerSimon Arlott <sa.me.uk>
Sun, 12 Aug 2018 08:15:13 +0000 (09:15 +0100)
commit2ae078d87bd9255d798cf47078cf67ed95db71ca
treecca7cb6fbe59a1ff1b5fa55477d2e5f622c121d1
parent6d8a8851dffa00877c830da04b6f78b86e9d0ba5
convert SGML guide to RST

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

[merged from d4214e9445d9f9d0f0ede3e09a9f81deee9: doc/sgml/oper-guide/config.sgml]
21 files changed:
doc/oper-guide/Makefile [new file with mode: 0644]
doc/oper-guide/charybdis-oper-guide.rst [new file with mode: 0644]
doc/oper-guide/cmodes.rst [new file with mode: 0644]
doc/oper-guide/commands.rst [new file with mode: 0644]
doc/oper-guide/conf.py [new file with mode: 0644]
doc/oper-guide/config.rst [new file with mode: 0644]
doc/oper-guide/index.rst [new file with mode: 0644]
doc/oper-guide/intro.rst [new file with mode: 0644]
doc/oper-guide/make.bat [new file with mode: 0644]
doc/oper-guide/oprivs.rst [new file with mode: 0644]
doc/oper-guide/ucommands.rst [new file with mode: 0644]
doc/oper-guide/umodes.rst [new file with mode: 0644]
doc/sgml/oper-guide/charybdis-oper-guide.sgml [deleted file]
doc/sgml/oper-guide/cmodes.sgml [deleted file]
doc/sgml/oper-guide/commands.sgml [deleted file]
doc/sgml/oper-guide/config.sgml [deleted file]
doc/sgml/oper-guide/intro.sgml [deleted file]
doc/sgml/oper-guide/oprivs.sgml [deleted file]
doc/sgml/oper-guide/stylesheet.dsl [deleted file]
doc/sgml/oper-guide/ucommands.sgml [deleted file]
doc/sgml/oper-guide/umodes.sgml [deleted file]