How to write a proper README.rst?

[Marsu42]

I cannot make my README.rst show the description text in camera - and I also don't see it from any other module *except* mini_iso.mo but that source code is unavailable atm ... where do I get a working README.rst sample? Thanks!

[Audionut]

Yeah, that looks broken here also.

Pressing the INFO button (5D3), brings up, Help files not found.
After pressing the Q button on the modules, you can scroll left or right which brings up another screen, but no description text.

[Marsu42]

Yeah, that looks broken here also.

The strange thing is that it works with mini_iso.mo, maybe you can confirm it and alex can upload this working README.rst somewhere as a sample....

[Audionut]

I deleted my local copy of the source.  If you say the binary works, then it works 

A code snippet would be nice.  It probably won't be till after the Libre Graphic Meeting though.

[a1ex]

I also don't see it from any other module *except* mini_iso.mo

Since for mini_iso you have a binary compiled by me... it's something in your build process. Can you paste a compilation log for some module?

(one normal and another with "make V=1")

[Marsu42]

Since for mini_iso you have a binary compiled by me... it's something in your build process.

Right, oh my, good thinking :-p ... I admit I didn't try nightly to see if the README.rst work there. There's indeed some error message in make V=1, I'll try a Linux vm instead cygwin to debug it myself and will report back with a solution or if I cannot figure it out. Good Audionut has the same problem with his compile, so I'm not alone :->

[Audionut]

Normal

V=1

/bin/sh: 1: } | sort > ettr.sym && cat ettr.sym: not found

/bin/sh: 1: } | sort > ettr.dep && cd ../../modules && python2 checkdep.py ettr: not found

Hrm!

[a1ex]

Okay, so V=1 is somewhat broken.

Anyway, for README.rst, the relevant line is:
 python2 ../readme2modulestrings.py > module_strings.h

Can you paste the output of module_strings.h? (for any module you like)

[Audionut]

http://pastebin.com/mbEFcVjH

Code: [Select]



    static char __module_string_a_name [] MODULE_STRINGS_SECTION = "Name";
    static char __module_string_a_value[] MODULE_STRINGS_SECTION = "Expose To The Right";
    static char __module_string_b_name [] MODULE_STRINGS_SECTION = "Author";
    static char __module_string_b_value[] MODULE_STRINGS_SECTION = "a1ex";
    static char __module_string_c_name [] MODULE_STRINGS_SECTION = "License";
    static char __module_string_c_value[] MODULE_STRINGS_SECTION = "GPL";
    static char __module_string_d_name [] MODULE_STRINGS_SECTION = "Summary";
    static char __module_string_d_value[] MODULE_STRINGS_SECTION = "Expose To The Right - auto exposure that minimizes noise";
    static char __module_string_e_name [] MODULE_STRINGS_SECTION = "Forum";
    static char __module_string_e_value[] MODULE_STRINGS_SECTION = "http://www.magiclantern.fm/forum/index.php?topic=5693.0";
    static char __module_string_f_name [] MODULE_STRINGS_SECTION = "Description";
    static char __module_string_f_value[] MODULE_STRINGS_SECTION = "";
    static char __module_string_g_name [] MODULE_STRINGS_SECTION = "Last update";
    static char __module_string_g_value[] MODULE_STRINGS_SECTION =
        "ce2ffe1 on 2014-03-09 20:58:57 UTC by a1ex:\n"
        "ETTR: fine-tuned printf's\n"
    ;
    static char __module_string_h_name [] MODULE_STRINGS_SECTION = "Build date";
    static char __module_string_h_value[] MODULE_STRINGS_SECTION = "2014-04-01 05:54:01 UTC";
    static char __module_string_i_name [] MODULE_STRINGS_SECTION = "Build user";
    static char __module_string_i_value[] MODULE_STRINGS_SECTION = "magiclantern@magiclantern-VirtualBox";
     
    MODULE_STRINGS_START()
        MODULE_STRING(__module_string_a_name, __module_string_a_value)
        MODULE_STRING(__module_string_b_name, __module_string_b_value)
        MODULE_STRING(__module_string_c_name, __module_string_c_value)
        MODULE_STRING(__module_string_d_name, __module_string_d_value)
        MODULE_STRING(__module_string_e_name, __module_string_e_value)
        MODULE_STRING(__module_string_f_name, __module_string_f_value)
        MODULE_STRING(__module_string_g_name, __module_string_g_value)
        MODULE_STRING(__module_string_h_name, __module_string_h_value)
        MODULE_STRING(__module_string_i_name, __module_string_i_value)
    MODULE_STRINGS_END()


unified+5D3.123 only.

[a1ex]

Code: [Select]

    static char __module_string_f_name [] MODULE_STRINGS_SECTION = "Description";
    static char __module_string_f_value[] MODULE_STRINGS_SECTION = "";


There's the problem. Here it looks like this:

Code: [Select]

static char __module_string_f_name [] MODULE_STRINGS_SECTION = "Description";
static char __module_string_f_value[] MODULE_STRINGS_SECTION =
    "Records 14-bit RAW video. Minimalist, no metadata.\n"
    "\n"
    "You may want to load mlv_play for reviewing clips.\n"
    "\n"
    "For details, please see the \"Raw Video\" section on the Magic\n"
    "Lantern forum.\n"
    "\n"
;

The code snippet that generates this text is:

Code: [Select]

# render the RST as html -> txt without the metadata tags
txt = run('cat README.rst | grep -v -E "^:([^:])+:.+$" | rst2html --no-xml-declaration | python ../html2text.py -b 700')

so try running these commands step by step:

Code: [Select]

cat README.rst
cat README.rst | grep -v -E "^:([^:])+:.+$"
cat README.rst | grep -v -E "^:([^:])+:.+$" | rst2html --no-xml-declaration
cat README.rst | grep -v -E "^:([^:])+:.+$" | rst2html --no-xml-declaration | python ../html2text.py -b 700

Best guess: missing rst2html? it's a tool from docutils, a Python package. In some distributions I think it's called rst2html.py.

[Audionut]

Installed python-docutils.  Problem solved.

edit:  And confirmed working in camera.

Code: [Select]

static char __module_string_f_name [] MODULE_STRINGS_SECTION = "Description";
static char __module_string_f_value[] MODULE_STRINGS_SECTION =
    "ETTR is a techinque that optimizes your exposure for raw\n"
    "shooting, with the goal of minimizing noise without blowing the\n"
    "highlights.\n"
    "\n"
    "Auto ETTR will adjust the exposure for you until the histogram will\n"
    "touch the right side, but - whenever possible - without clipping.\n"
    "This will minimize image noise for your given set of restrictions\n"
    "(e.g. slowest shutter, max ISO, or what highlights can be clipped).\n"
    "\n"
    "You will usually have to darken the image in post (which is good).\n"
    "\n"
    "Tip: on the raw histogram you will see an ETTR hint that can be\n"
    "used for manually exposing the image.\n"
    "\n"
;
Thanks a1ex.

[Marsu42]

Installed python-docutils.  Problem solved.

Thanks for solving it, probably a more verbose error message might be useful when other people are also missing this.

[a1ex]

Solved.