Quote:
Originally Posted by jlutes
Chaley,
What is the documentation submission process? Is there a wiki or wiki-type system that I just haven't found yet or is there another method?
|
Calibre's documentation is included with the source code. To obtain the source code (you will ignore most of it), see
http://manual.calibre-ebook.com/develop.html, and in particular the section "Getting the code".
That aside, how you proceed depends on what you want to do. If you are making small changes to existing manual sections, then follow the instructions in the linked page above for submitting changes. The manual pages are in src/calibre/manual. They are in a form that is 'compiled' to generate the web pages (see below).
If you are thinking of writing something new/larger, then the process used by Manichean for the Regular Expression tutorial is a good one. He wrote a draft of the tutorial and posted it in a thread here. People commented, he reacted and edited the draft, etc. When he reached a point where he was satisfied, he submitted the draft to Kovid (don't know if he did it by email or through the forum). Kovid added it to the 'Tutorials' section.
When I did the 'Managing subgroups of books, for example “genre”' tutorial, I added it to the manual myself. This was easier for me because I manipulate the source all the time. Kovid added the link to the tutorials section.
Documentation is formatted using RST (reStructuredText) command. Quoting the RST web page (
http://docutils.sourceforge.net/rst.html):
Quote:
reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains. The reStructuredText parser is a component of Docutils. reStructuredText is a revision and reinterpretation of the StructuredText and Setext lightweight markup systems.
The primary goal of reStructuredText is to define and implement a markup syntax for use in Python docstrings and other documentation domains, that is readable and simple, yet powerful enough for non-trivial use. The intended purpose of the markup is the conversion of reStructuredText documents into useful structured data formats.
|
The tutorial on the RST page provides a lot of information, and calibre's existing documentation provides many germane examples.