Okay, after
discussing it on Bitbucket, I've reimplemented it with plain text metadata (no bitmaps). It may not look as pretty, but it has some practical advantages like:
- much smaller
- no need for LaTeX
- searchable docs will be possible (since we have IME)
So, for module authors, here are the specs:
README.rstAll modules must have a README.rst file. If not, the build system will give you a default template.
This file is written in
reStructuredText syntax (mostly plain text) and looks like this:
Expose To The Right
===================
:Author: a1ex
:License: GPL
:Summary: Expose To The Right - auto exposure that minimizes noise
ETTR is a techinque that optimizes your exposure for raw shooting, with the goal of minimizing noise without blowing the highlights.
Auto ETTR will adjust the exposure for you until the histogram will
touch the right side, but - whenever possible - without clipping. This will minimize image noise for your given set of restrictions
(e.g. slowest shutter, maximum ISO, or what highlights can be clipped).
You will usually have to darken the image in post (which is good).
Tip: on the raw histogram you will see an ETTR hint that can be used for manually exposing the image.
It will be rendered on Bitbucket like this (when you browse the source code):
https://bitbucket.org/hudson/magic-lantern/src/tip/modules/ettr/In the camera it will look like this:
And of course, it can be rendered as HTML and placed on our website.
In README.rst you can notice a few important parts:
*
Document title (first line, underlined): will be extracted as field
Name*
User fields: these are written in RST syntax, like this:
:name: value
*
Body text (first section, like an intro): will be extracted as field
Description (multiline)
*
Optional sections (e.g. usage, tips & tricks, whatever): will be extracted as
Help page 1,
Help page 2 and so on. I want to display these when you press INFO/DISP (not yet implemented).
Note: right now there's a limit of 20 lines per page. Page breaks are not automatic; each section is a page break (so add more sections if you need to write more). This may change if we'll implement scrolling.
Metadata fieldsAll metadata is optional.
Recommended tags:
*
:Name: and
:Description: extracted from README.rst (title and body text)
*
:Author: or
:Authors:*
:License:*
:Summary: will be displayed as help text in the Modules tab, in the bottom area:
*
:Forum: a link to the main forum thread for your module
*
:Website: for third party module authors, or from modules ported from other free software projects
Tagging modules by functionality (what it does):
*
:Tags: space-separated list of keywords
* Current tag set:
photo video raw exposure focus filesystem text-input audio games scripting (anything else would go to "Other", see module.c)
* Special tags:
experiments (for research code) and
diagnostics (for troubleshooting code that can be safely ran by users).
Stability ratings: (each rating is a space-separated list with camera models)
:Stable: developer has this model and it shows no misbehavior.
:Usable: seems to work on this model, hiccups may happen.
:Not working: reported as not working on your camera.
and anything not tagged defaults to
Untested: might work, might crash the camera, expect anything. Note, "untested" is not a field, it's just the fallback case.
Example of functionality tags and stability ratings:
:Tags: photo raw exposure
:Stable: 5D3 5D2 50D
:Usable: 6D 7D 500D 550D 60D 600D 650D 700D 1100D
:Not working: EOSM
Version tags, autogenerated:
*
Last update: date and changeset that affected that particular module directly (something changed in the module directory)
*
Build date: when the module was compiled
*
Build user: who compiled it
InternalsWhen you include module.h from a module, it will also include
module_strings.h from the current directory, auto-generated.
README.rst is rendered with rst2html and pre-formatted with html2text.py from Aaron Swartz. Currently, the text is pre-formatted for 59 columns x 20 lines; this may change once we'll have proportional fonts; g3gg0 has them almost ready:
Compatibility and migrationOlder modules are stil binary compatible. They are not source code compatible; for that, you will have to move the MODULE_STRINGS section from the C source file to README.rst.
