Author Topic: Let's restore camera help (Help needed)  (Read 1584 times)

Erik Krause

  • Freshman
  • **
  • Posts: 55
Let's restore camera help (Help needed)
« on: May 31, 2018, 09:27:14 PM »
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

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 3510
  • Blunt and to the point
Re: Let's restore camera help (Help needed)
« Reply #1 on: June 21, 2018, 03:15:56 PM »
Thanks for taking time to tackle this project.

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

R

  • New to the forum
  • *
  • Posts: 33
Re: Let's restore camera help (Help needed)
« Reply #2 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?

Walter Schulz

  • Hero Member
  • *****
  • Posts: 6203
Re: Let's restore camera help (Help needed)
« Reply #3 on: July 01, 2018, 10:24:07 AM »
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

  • Freshman
  • **
  • Posts: 55
Re: Let's restore camera help (Help needed)
« Reply #4 on: July 03, 2018, 10:57:49 AM »
Nice to see this starts rolling!

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

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

  • Hero Member
  • *****
  • Posts: 6203
Re: Let's restore camera help (Help needed)
« Reply #5 on: July 04, 2018, 12:16:34 PM »
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

  • Administrator
  • Hero Member
  • *****
  • Posts: 11653
  • 5D Mark Free
Re: Let's restore camera help (Help needed)
« Reply #6 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.

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:

Code: [Select]
        .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

  • Hero Member
  • *****
  • Posts: 6203
Re: Let's restore camera help (Help needed)
« Reply #7 on: July 04, 2018, 01:24:13 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

  • Hero Member
  • *****
  • Posts: 6203
Re: Let's restore camera help (Help needed)
« Reply #8 on: July 06, 2018, 09:25:33 PM »
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

  • Freshman
  • **
  • Posts: 55
Re: Let's restore camera help (Help needed)
« Reply #9 on: September 17, 2018, 06:39:26 PM »
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

  • Administrator
  • Hero Member
  • *****
  • Posts: 11653
  • 5D Mark Free
Re: Let's restore camera help (Help needed)
« Reply #10 on: September 18, 2018, 09:54:12 AM »
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.