Let's restore camera help (Help needed)

Started by Erik Krause, May 31, 2018, 09:27:14 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

Erik Krause

Let's restore ML help together!

Currently, if you press the Info button while in ML menu, you get "Undocumented feature". This shouldn't be the case. Until version 2.3 there where nice help texts. We should restore them for the current releases.

4 years ago Redrocks started the User Guide thread for the latest nightlies. After a good start it went inactive, probably because the update mechanism was too tedious.

A wiki is much easier to edit. I've transferred the texts from that thread to the ML wiki, which anyone can edit who also can write here, the credentials are the same. The more important part is camera help the other one general help

Goals
In my opinion the first goal should be to provide in-camera help. Have you ever been out in the field without internet access and you didn't get a needed function explained? With internet access it's always possible to find information, but in-camera help is essential and overdue.  Later on we can see, if and how we make this a good online user guide.

What can be done by anyone

  • Go through the text and see whether it would be helpful under the premise that you know little about that function.
  • A lot of sections where copied from the help that is already provided on the bottom of the ML screen. This need to be expanded, since there is no point duplicating this information.
  • Some sections are not available any more, have moved to a module or where renamed. Those need to be corrected.
  • As a first measure mark that sections as INCOMPLETE. How to do this is explained on top of the page. Of course you can also start to improve them right away.
  • Look for sections marked as INCOMPLETE and improve them. Remove the INCOMPLETE comment once you're satisfied.
  • Don't be afraid to edit something. It's a wiki, your edits will be reviewed and corrected if necessary. You also can add further comments to the section to ask for comment,  help or review.

Although the current text is pretty large it's better considered a framework to be filled.

What more is needed?
Apart of that I'd like to discuss how we can proceed. Please make this thread sticky instead of the User Guide thread and point to it from various places, namely from https://www.magiclantern.fm/forum/index.php?topic=12657.0 and from the User Guide thread itself. 

I'd also like to discuss the format and the future use. Once it is more up to date it should be used f.e. as a target on the feature matrix, which currently still uses the 2.3 user guide.

I have some experimental PHP code that splits the wiki article into files, one for each main menu point, and converts the content to RST format, much like the old menu text files in the /doc/ folder on bitbucket. This code could be turned into a dokuwiki plugin which writes those files on any save, but other uses are also possible.

I like Alex' proposal to embed the help texts in the source code in order to have them up to date more likely, for which a text only format would be probably better. In the end there should be a two-way exchange: The wiki text should update the embedded help and vice versa. There is already some python code in the /doc/ folder on bitbucket that can convert RST to dokuwiki text, so that way should be possible too.  Someone familiar with bitbucket could certainly automate both import and export.

And last but not least many agreements are necessary to have a uniform help file. F.e. the menu topics that are added by modules are listed under the respective menu but should be marked clearly as such.

A lot of work to do, but for a healthy community like this one it should be doable. What do you think?

Audionut

Thanks for taking time to tackle this project.

Pretty sure I got all of the links you sent via pm, plus my sig.

R

I would like to help, but since English is not my native language, I don't think I should update the wiki because of any mistakes I might make.

I can, however, translate everything into Spanish. Is I18N planned?

Walter Schulz

Started with some editing ...

@R: Damn the torpedoes! There are native speakers able to clean up our mess. ;-)

@Erik Krause:
Suggestions: "Incomplete" flag doesn't seem sufficient. There is no way to tell unedited sections from those considered perfect/complete. Just adding flag to all sections might be useful.
We may need additional flags for some kind of review process. 

@all: HDR-video section is in very bad shape. Most of the tool links are dead.
-> Is there someone able to "speak" HDR video and able to describe a workflow with tools - more or less - up-to-date? Help!

Erik Krause

Nice to see this starts rolling!

Quote from: Walter Schulz on July 01, 2018, 10:24:07 AM
Started with some editing ...
Suggestions: "Incomplete" flag doesn't seem sufficient. There is no way to tell unedited sections from those considered perfect/complete. Just adding flag to all sections might be useful.
We may need additional flags for some kind of review process. 

No problem. Since those are comments we can also have a
>COMPLETE
comment and we can even have a brief discussion as f.e.
>INCOMPLETE
>>This section needs some more content...

Quote from: R on June 21, 2018, 06:37:55 PM
I would like to help, but since English is not my native language, I don't think I should update the wiki because of any mistakes I might make.
I can, however, translate everything into Spanish. Is I18N planned?
No fears! Correcting mistakes is far easier than providing content. So by all means, please provide content. It can be fixed later. It's a wiki!
I18N would be very nice. The old user guide was available in several languages and in the long run the new one should be as well.

Walter Schulz

Slow progress ... as expected ...

@a1ex: Not sure if sufficient for an issue report:
Focus tab -> Follow Focus
Highlighting most menu items you can use scroll wheel selecting available options. This one is weird (IMO) in 650D: You can select OFF and either Arrow Keys or LCD sensor. Depends which one you selected after pressing Q. There you have "LCD sensor" and "Arrow keys" but "OFF" is missing.
Lines at bottom are a little bit confusing, too: In submenu Follow Focus it says:
"You can focus with arrow keys or with the LCD sensor". Makes sense.
In Focus tab you will see:
"You can focus with arrow keys. MENU while REC = save focus point." Doesn't matter which option is selected. Just a matter of character length limit?

So, question: Clean it up now or just collect all inconsistencies?

a1ex

Better clean it up now; just not sure what the behavior should be. Is it better to move these to a pickbox with 3 choices? (OFF, Arrow keys, LCD Sensor). The last option would appear only on models with this sensor.

There are two help lines available now (back then, there was just one), so yeah, some help texts could be updated to make use of the extra space. Help can be also defined for every single option, using a newline (\n) as delimiter. For example:


        .help = "Focus with arrow keys or with the LCD sensor\n"                             /* this line appears when the "OFF" option is selected */
                "Arrow keys: up/down = quick focusing, left/right = slow focusing.\n"        /* this line appears when "Arrow keys" is selected */
                "LCD sensor: focus without touching the camera. Direction auto-reversed.\n", /* this line appears when "LCD sensor" is selected */
        .help2 = "MENU while recording: save focus point. PLAY: go to saved point.",         /* this line is always printed; you can use multi-line help here as well */


The text could still be improved, as the space is tight. The limit is about 50-70 characters; since fonts are proportional, the limit is not fixed.

A longer description can be made; that could be displayed when you press INFO. One "minipage" (that fits on the camera screen) for each option would be best. You may press Q in the Modules tab for an example of help text rendered with in-camera fonts (no BMP), just to get an idea of page size. Of course, I can use different fonts if needed.

I'd like to have some sort of rich formatting as well. With the BMPs created from RST -> LaTeX, that wasn't much of a problem; but the BMPs are large and not searchable. With built-in fonts, one would have to write some sort of rich text interpreter from scratch or adapt something existing (not exactly a HTML engine; something lighter). Will think about it; if there's good content with images and nice formatting, I'll find a solution.

Walter Schulz

Quote from: a1ex on July 04, 2018, 01:03:08 PM
Better clean it up now; just not sure what the behavior should be. Is it better to move these to a pickbox with 3 choices? (OFF, Arrow keys, LCD Sensor). The last option would appear only on models with this sensor.

Pickbox would be fine!

Walter Schulz

Status:
Obsolete menu entries deleted (ongoing), reordered remaining ones and added some missing.
Looks almost like nightly build menu structure now.


To do:
Checking 50D specific entries.
Filling it with content. Again: HDR is in bad shape. Anyone actually doing something with this option?

Erik Krause

Vacations are over...

So here is what my preliminary wikitext to  RST format converter outputs. Would be interesting to know, whether this is usable or not:
https://bitbucket.org/erik_krause/magic-lantern/downloads/

Currently it outputs one file per main section of the camera_help page, named like the sections. The goal is to have a wiki plugin that updates the files any time the text is saved. This text files could be included in the Ml sources and, if changed there, wikitext could be created to update the wiki in turn (modifying existing module /doc/wikidoc.py)


a1ex

Thanks, looks like it's getting somewhere.

If we can get some sort of roundtrip between ML source, (intermediate) plain RST and wiki markup, that's pretty much all that's needed to allow edits in any of these places.

That's the workflow I'd imagine:

- developer editing ML sources -> extract RST from comments or whatever, render as wiki / pdf / bmp / whatever
    -> robot updating the wiki and other formats.

- wiki edit by regular users -> patch to ML sources -> pull request created by robot
    -> cross-check by rendering again as wiki and highlighting any differences.

Walter Schulz

Feedback time:
Debug tab help ready to be reviewed.

To discuss: Help text made for mere users. I omitted all the "nerdy" stuff. Q: Add a line for each menu item to tell users not to pay attention to that man behind the curtain?

Missing: RL numbers for benchmark runs for each cam.
Broken: Format for listings and sub-menus ... See "Benchmark"

Walter Schulz

Status Expo screen:

Almost done.

To do list:
About to delete ISO -> Color coding. Seems to be gone for good.

Asking for help for modules ETTR, DUAL_ISO and AUTOEXPO.

EDIT (18.01, High Noon):
Basic editing for Overlay screen done.
Missing helpful texts for Histograms, Vectorscope, Waveform.

Think will go into Display next.

Walter Schulz

Status: Last steps for "Focus" screen... Going to Shoot next. Movie thereafter
Found some bugs in Rack Focus implementation, see issue #2920
@a1ex: Any news on issue touched in replies 5-7?

Q: - Write permissions to Media Manager? Can not upload files and there are outdated ones and missing.

Assistance needed:
- Review all the stuff (Audio, Movie, Shoot almost untouched)
- Tutorials/Help texts for any item but most wanted: HDR, ETTR, Dual-ISO, RAW/MLV modules, Auto Exposure, Silent pics, Advanced Intervalometer

EDIT (2019.24.01) High Noon-ish: Getting stuck in "Focus", Stack Focus. Have to dive into "Post scripts" and "Intervalometer scripts" and enfuse workflow. Shoot screen has to wait.

EDITEDIT: And all those tiny bugs hidden in ML menu's dark corners (=less frequently used) :
#2921 Post Scripts
#2922 Intervalometer Script

Walter Schulz

Write permissions fixed, thanks!

@a1ex: If you have time to look into menu issue (replies 5-7): "Mirror Lockup" shares the same problem. In Shoot screen you can toggle by SET button but only between OFF and either "SelfTimer (ON)" or "HandH, 1/2-1/125" or "Always ON".

Status:
Shoot and Focus are almost done. Exception: Everything about modules Silent, Deflickr, Adv_int hasn't been touched yet.
I'm about to enter Movie tab but I'm (as almost a novice to movie tab) gonna have to work through all the options the hard way. Will cost lots of time. If there is anybody able to put the burden from me ... Help, please!
Same for ETTR and Autoexpo!

EDIT: Working on Silent pics ...
11.02.19: Silent pics almost done. Missing: FRSP (gradient, time-lapse workflow, limits, interaction issues) and naming with/without intervalometer/bracketing.

Walter Schulz

@a1ex: Curious about slit-scan timing. Is there a formula for scan time depending on exposure duration, resolution or else?

a1ex

LiveView frame rate gives the timing:
- one Bayer line in vertical scanning modes (top to bottom, bottom to top)
- 2 Bayer lines in center mode (to keep the colors)
- 4 Bayer columns in horizontal scanning modes (left to right, right to left); the restriction comes from 14-bit packing.

So... the total time depends on LiveView frame rate and resolution (and scanning mode).

Walter Schulz

Thanks! I think it will get covered in Camera Help 1.x and x > 0.
Wishing for a slider/motorized pano head, though.

Erik Krause

Thank you Walter for your continuous efforts! Unfortunately I underestimated my daytime workload and hence couldn't work on this as I wanted. But I had another idea: bitbucket comes with a built-in wiki which can use ReStructuredText directly. This way it wouldn't be necessary to translate the wiki back and forth between RST and Dokuwiki markup, and the complete documentation would be already inside the common repository.

The drawbacks are:
- It's less comfortable than dokuwiki. There is no section editing f.e.
- If I understand correctly it's either completely public or restricted to bitbucket users. See https://confluence.atlassian.com/bitbucket/make-a-wiki-private-or-public-223216420.html for details.

I used pandoc to convert the whole page and put it on my bitbucket account for you to see how it looks: https://bitbucket.org/erik_krause/magic-lantern/wiki/Home This is without any adjustments, so some links might not work and there are no images (with one exception where I tried how to do it). In the end it would be better to have separate pages for any main menu topic, I guess.

What do you think?

Walter Schulz

At the moment it's almost a one-man-show. Therefore anything restricting collaboration doesn't really matter.
I cannot tell which platform or editing tool fits best in regard of easy integration into ML. That's up to a1ex, I think.

Erik Krause

Well, my information was that in-camera-help needs RST. What I originally though I could provide was a wiki extension that would convert dokuwiki to RST. Someone else would need to provide a conversion from RST to dokuwiki (there are still fragments that probably do this in the ciúrrent repository which could be revived). But of course there are still a lot of unclear things.

I would be happy if I don't need to tackle all this. But I don't know bitbucket very well and hence can't estimate what effort it would be to integrate wiki pages into the current build workflow.

Walter Schulz

Review time! Are we on the right track?
https://wiki.magiclantern.fm/camera_help!

Needed:
1) a1ex to tell where we are going Check!
2) Photogs/videographers checking content for correctness and missing content (is help really helping or just listing items?). Report here or comment/edit wiki.
3) Native speaker (if available) to translate germish into something resembling english language.


I worked through most of the items (leaving a trail of bug reports and feature requests). Movie tab: Haven't done that much yet and there are bits and pieces in need of some fine tuning in other sections, too.
Another thing widely neglected by your somehow exhausted editor: Screenshots and other pics.

====only for persons involved in transfering this stuff to camera (Erik and a1ex (atm))====
Internals: Introduced
"\\" to enforce line feed within paragraphs
"<nowiki></nowiki> for special character ">"


a1ex

Thumbs up from me!

In particular, I appreciate the bug reports a lot, even though I didn't go through them yet. During the small holiday I just had (about two weeks or so), pretty much all I did was to work on the DIGIC 6/7/8 ports...

Maybe I should stop researching and start coding :D

Walter Schulz

Thanks, a1ex!
Another bug report is waiting for confirmation (will bring some headache, I suppose) and there will be another feature request (without YAMLMO involved) ...

Item 2:
Photogs and videographers, please browse https://wiki.magiclantern.fm/camera_help and report misconceptions, errors, missing help items, additional info to be included, obsolete stuff and overcomplicated explanations.

It's up to you how to report. If you want to edit wiki: Fine. Or report here. Or send me a PM.


My 2 cents: Ask yourself which items, caveats, tips, etc., you want to have covered inside your cam!
Big picture: Not everything has to be covered in this in-camera help!
There are some items requiring some thorough reading and experimenting (+postprocessing): Dual ISO, HDR comes to mind. For thus things we need a balance between basic infos/traps to avoid in the field and links to (upcoming or existing) tutorials about concepts and workflows.

Keep'em coming!


Walter Schulz

@a1ex:
Animation in help files (MNG or other), possible/desireable feature?
I think it may be helpful for some topics.