Proposal for modules GUI - embed a README page in each module

Started by a1ex, August 30, 2013, 11:06:54 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

a1ex

Starting from this idea from Marsu42 that modules should have a longer description, I've experimented with something that looks like this:



Juicy details: https://bitbucket.org/hudson/magic-lantern/pull-request/213/modules-with-embedded-readme-page

Also a few UI tweaks (where I'm sure stevefal has something to say, and some of them are already in the main repo):

* modules should opt-in, not opt-out (autoload is on by default, but all modules are off - you choose what you want to load)
Rationale:
  - I use 2 or 3 modules out of more than 10 on the card. When formatting the card, most modules had to be turned off manually, and it takes many clicks.
  - Things that you don't need shouldn't be loaded IMO (saves memory, reduces clutter etc).
  - It encourages people to be aware of what they are loading

* toggle modules on/off with a single click (like all other boolean options in ML)
   (I've been toggling things on and off a lot lately, mostly for troubleshooting, and it required too many clicks)

* modules sorted by name, and loaded modules are always at the top
   (so you can see quickly what's loaded, instead of having to scroll)

* press Q to see more info about the module (for example you will know whether you should load it or not).
   (I wanted to map this to INFO, but the menu code requires some non-trivial changes)

* moved module options in a submenu (since you don't touch them all day long)

Thoughts?

dlrpgmsvc

Great idea. For me it's OK for all the proposals, no reserve at all. Very good work to implement !
If you think it's impossible, you have lost beforehand

engardeknave

I thought it was kind of crazy just loading everything by default.

arrinkiiii

All good !!!

I noticed with the new options and modules some screens from ML will pass down the screen... or is modules or menus in the different tabs. Some times im looking for something and i don't find... only after a few time searching i find that i need to scroll down the wheel for see the other modules or menus.

So, it's not possible to make some arrows down wend you have something more down to see or one arrow up wend you have stuff  upper and you don't see it? Even both wend you got both things, down and up, that you can't see... for example like the gps have...

I think if it's possible would make big diference having some reference about more info that you can't see it. 

xNiNELiVES

The main reason ML deters new users is because the settings can look/be too complicated from first look. This fixes this issue by supplying information for (hopefully) all settings and sub-settings.

a1ex

Quote from: arrinkiiii on August 31, 2013, 01:29:36 AM
I noticed with the new options and modules some screens from ML will pass down the screen... or is modules or menus in the different tabs. Some times im looking for something and i don't find... only after a few time searching i find that i need to scroll down the wheel for see the other modules or menus.

So, it's not possible to make some arrows down wend you have something more down to see or one arrow up wend you have stuff  upper and you don't see it? Even both wend you got both things, down and up, that you can't see... for example like the gps have...

This is why I'm trying to avoid scrolling in menus. Do you have any menu that requires scrolling, other than the module tab, Debug and Modified? (I don't)

arrinkiiii

Quote from: a1ex on August 31, 2013, 09:00:45 AM
This is why I'm trying to avoid scrolling in menus. Do you have any menu that requires scrolling, other than the module tab, Debug and Modified? (I don't)

Uhmmm, i think that in the Expo tab, at least with older version of ML (1 week ago) but i later make test with all the modules load and see. I also see that ML got some kind of bar in the right side of screen that can tell you if you got more stuff down...or up. I think is alright for me,just see it this last night because i operate with camera at night/dark situation... and also because im looking/finding for him.

Sorry, didn't know that you are trying to avoid that. More info that the camera can have embedded the better... if don't get in the way of performance/velocity  :) 

Marsu42

Quote from: a1ex on August 30, 2013, 11:06:54 PM
Starting from this idea from Marsu42 that modules should have a longer description, I've experimented with something that looks like this:

All very good, esp. the info screen :-p (I used multiple MODULE_STRING until now which is rather messy), though I finally have to get LaTeX to run on my Windows box :-o ... for everything else I'll comment in bitbucket in the pull request.

a1ex

Quote from: arrinkiiii on August 31, 2013, 11:49:18 AM
Uhmmm, i think that in the Expo tab, at least with older version of ML (1 week ago)

Correct, if you load both autoexpo and ETTR (which both do basically the same thing, so you only need one of them), the expo menu got 12 items (normally 11 items fit there without any tricks).

I could squeeze 12 items by trimming 2 pixels from each item (which is hardly visible). I could even squeeze 13 items, but it looks a bit crammed. So, my proposal to solve this would be:

- 11 items or less => use normal spacing
- 12 items => cram by 2 pixels
- 13 items => cram by 4 pixels (assumming squeezed text is better than scrolling)
- 14 items or more => use scrolling and normal spacing (or maybe cram by 1-2 px)

arrinkiiii


a1ex

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.rst

All 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 fields

All 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

Internals
When 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 migration

Older 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.

RenatoPhoto

I am happy to see that this smaller option was selected considering the memory limitations.  In this case smaller is better ;D
http://www.pululahuahostal.com  |  EF 300 f/4, EF 100-400 L, EF 180 L, EF-S 10-22, Samyang 14mm, Sigma 28mm EX DG, Sigma 8mm 1:3.5 EX DG, EF 50mm 1:1.8 II, EF 1.4X II, Kenko C-AF 2X

arrinkiiii


coutts

I like it. could probably be integrated with main website too since I kept the <div> tag layout pretty structured / easy to implement.

:D looks great!

Doyle4

Could there possibly be quick load option for Video and Photo loading? put your choice of modules into either video and photo when it comes to loading modules, if your shooting video press the video load module option, if photoing that day press the load button for photo.

a1ex


Doyle4

Kinda thing.


No not really, convenience really, if i know what im doing on the day be nice to have couple of pre sets i can quick load too, if video say is loaded and press photo, its could ask if you would like to disable videos and load photo or keep video modules loaded.

a1ex

After implementing the proportional fonts, the About page looks like this (compare with old font and with LaTeX rendering):



I also suggest adding the :Forum: tag to README.rst, so the Bitbucket page will show a link to the relevant forum thread, like this: https://bitbucket.org/hudson/magic-lantern/src/tip/modules/dual_iso/

Audionut

Quote from: a1ex on September 01, 2013, 07:42:27 PM
Correct, if you load both autoexpo and ETTR (which both do basically the same thing, so you only need one of them), the expo menu got 12 items (normally 11 items fit there without any tricks).

How often do people change general exposure settings in ML?  What about rolling them into a submenu?

dmilligan

The only time I do is in movie mode on the 1100D. There's no manual video mode on that camera so the only way to change basic expo parameters is through ML menu. In most situations I wouldn't care if that stuff was in a submenu, there are much easier ways to change basic expo settings, but on 1100D in movie mode, it would be a huge PITA b/c that's one more button press I have to make to change a very basic exposure setting.