Unified Magic Lantern manual

Started by dlrpgmsvc, June 18, 2013, 02:17:37 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

dlrpgmsvc

This is to unify all the ML informations into a unique collaborative manual.

In the official ML repository there is the official manual. It's located here :

https://bitbucket.org/hudson/magic-lantern/src/tip/doc/

This is in different pieces: txt's, png's, bmp's, jpg's, drawings and so on. They are all organized into a precise structure, with chapters and so on, and this structures is as follows (but changes continuously as the manual develops) :

include(o, "FEATURES.txt");
include(o, "MANUAL.txt", 1);
include(o, "MENUSTART.txt");
include(o, "MN-AUDIO.txt");
include(o, "MN-EXPO.txt");
include(o, "MN-OVERLAY.txt");
include(o, "MN-MOVIE.txt");
include(o, "MN-SHOOT.txt");
include(o, "MN-FOCUS.txt");
include(o, "MN-DISPLAY.txt");
include(o, "MN-PREFS.txt");
include(o, "MN-DEBUG.txt");
include(o, "MENUEND.txt");
include_indent(o, "FAQ.txt");

This structure is controlled by scripts, so you can add chapters to it. All the scripts are in the doc directory (mkdoc.py is for pdf, mkdoc-cam for help bmp's, wikidoc for wiki output - but needs some tweaks). You need latex to compile them.

Each TXT file is plain text, you can edit it online, or offline and then commit it. The syntax is RST (http://docutils.sourceforge.net/docs/user/rst/quickstart.html) and can contain references to images (living in the same directory of the txt)  in this way :

.. figure:: 02.expo.png
    :align: center
    :width: 5cm

To add images, commit them like normal files to the official ML repository.
You can add files, sections, whatever.

The good of this system, is that, by modifying this manual, it's modified the help PDF in the nightly builds, it's modified the BMP ML help system inside the cameras and, if anyone fixes the wiki scripts, we can update the online version as well, all from a single source !
If you think it's impossible, you have lost beforehand


JulianH

Good idea :) I think it needs a bit more 'structure' to get started though. If 20 people start editing this document at the same time, that's bound to be inefficient.

What is the plan? What should be in it, what should not be? (I think it should be about raw - there is plenty of documentation for vanilla ML).

Make everything from scratch or try to collect all the available and relevant info into one place?

I think the latter is the easiest way. We could mail some websites who wrote tutorials for example to ask if we can include their tutorials/text (with credits/back link).

Distribution - how? Google Docs can be nice, but a public editable document isn't a good idea for distribution. A PDF is too easily outdated. Maybe make one final Google Doc / Presentation that is editable only by a few moderators who can keep it up to date?

a1ex

If you reuse the existing manual (from the repositiory), it can be compiled in many output formats (PDF, wiki, HTML, BMP for in-camera help, or whatever you may want to add.

Also I think translations should be done a bit later.

dlrpgmsvc

if the road man wants to print a manual, must go to repository, find the right txt among a myriad of other files, and print it ? or, worse, compile the txts together ? How ?

Do you agree this ready-readable format is better ? And you can add images inside. Or how to render the repository manual more user friendly ?
If you think it's impossible, you have lost beforehand

Redrocks

Quote from: JulianH on June 18, 2013, 02:24:27 PM
Good idea :)

What is the plan? What should be in it, what should not be? (I think it should be about raw - there is plenty of documentation for vanilla ML).


The chapter information in EOSHD's guide is the best place to start in organising what's needed:

Chapter 1 – Introduction
Chapter 2 – Enabling Raw Video
Chapter 3 – Recording Raw Video
Chapter 4 – Recommended settings
Chapter 5 – Recommended software and editing codecs
Chapter 6 – CineForm raw workflow
Chapter 7 – Uncompressed Cinema DNG raw workflow
Chapter 8 – ProRes / Ginger / After Effects
Chapter 9 – Kodak, Fuji and Alexa film looks for Resolve
Chapter 10 – Suitable Compact Flash cards
Chapter 11 – Raw shooting advice 

a1ex

Quote from: dlrpgmsvc on June 18, 2013, 02:55:47 PM
if the road man wants to print a manual, must go to repository, find the right txt among a myriad of other files, and print it ? or, worse, compile the txts together ? How ?

make docs

This will make PDF and BMP files, like the ones in ML 2.3 zip.

If you don't like that feature, let me know and I'll just delete it. Two years of work gone out of the window.

dlrpgmsvc

Quote from: a1ex on June 18, 2013, 03:03:15 PM
make docs

This will make PDF and BMP files.

If you don't like that feature, let me know and I'll just delete it. Two years of work gone out of the window.

Don't upset like this ! We are here to discuss and to clarify ! So, do this will produce a PDF file with BMP files embedded ?
If you think it's impossible, you have lost beforehand

a1ex

Yes, if you look at the latest changes, these PDFs and BMPs will be included in the nightly zip.

dlrpgmsvc

Very good ! So, i have some questions just to clarify (excuse the stupid questions, but so many more contributors can come in) :

- Do "manual.txt" is the root, and all the Others txt's are linked inside this ? Or all are separated from each others ? How they are organized ? And what files will be included in the nightly build and which not ?
- I can see we can modify the txt's, but how to add images inside the repository ?
If you think it's impossible, you have lost beforehand

a1ex

Here's how the document is split:


include(o, "FEATURES.txt");
include(o, "MANUAL.txt", 1);
include(o, "MENUSTART.txt");
include(o, "MN-AUDIO.txt");
include(o, "MN-EXPO.txt");
include(o, "MN-OVERLAY.txt");
include(o, "MN-MOVIE.txt");
include(o, "MN-SHOOT.txt");
include(o, "MN-FOCUS.txt");
include(o, "MN-DISPLAY.txt");
include(o, "MN-PREFS.txt");
include(o, "MN-DEBUG.txt");
include(o, "MENUEND.txt");
include_indent(o, "FAQ.txt");


So, each menu has a text file. There are also text files for other large sections (e.g. FAQ). The master document is created by the scripts.

The syntax is RST ( http://docutils.sourceforge.net/docs/user/rst/quickstart.html ). You can just write it as plain text, since the formatting is easy to fix afterwards.

To add images, commit them like normal files. To include them in doc, take the syntax from examples:


.. figure:: 02.expo.png
    :align: center
    :width: 5cm


Of course, you can use a visual editor for editing, then commit them to the repo and the changes will appear in both the PDF and the BMP versions. If anyone fixes the wiki scripts, we can update the online version as well, all from a single source.


dlrpgmsvc

Quote from: a1ex on June 18, 2013, 03:26:01 PM
Here's how the document is split:


include(o, "FEATURES.txt");
include(o, "MANUAL.txt", 1);
include(o, "MENUSTART.txt");
include(o, "MN-AUDIO.txt");
include(o, "MN-EXPO.txt");
include(o, "MN-OVERLAY.txt");
include(o, "MN-MOVIE.txt");
include(o, "MN-SHOOT.txt");
include(o, "MN-FOCUS.txt");
include(o, "MN-DISPLAY.txt");
include(o, "MN-PREFS.txt");
include(o, "MN-DEBUG.txt");
include(o, "MENUEND.txt");
include_indent(o, "FAQ.txt");



Great ! Do we can add menus to this list ? Where is located ?
What visual editor can be used to edit this manual ?
If you think it's impossible, you have lost beforehand

a1ex

I've used a plain text editor. You need latex to compile it. Of course, you can add files, sections, whatever.

All the scripts are in the doc directory (mkdoc.py is for pdf, mkdoc-cam for help bmp's, wikidoc for wiki output - but needs some tweaks).

dlrpgmsvc

Quote from: a1ex on June 18, 2013, 03:47:02 PM
All the scripts are in the doc directory (mkdoc.py is for pdf, mkdoc-cam for help bmp's, wikidoc for wiki output - but needs some tweaks).

Your work is Amazing ! but often the best things are not so evident to all people, so now I hope to give it the right spotlight on this ! I just changed the head post to reflect all your precious infos given here, many thanks !

Also, can you tell me the problems to the wiki script, so we can see if someone (or myself maybe) is able to solve them ? Many thanks !
If you think it's impossible, you have lost beforehand

a1ex

Well.. small formatting quirks for the new wiki (which seems down anyway). Copy/paste the output and you'll see it needs some manual adjustments.

On the old wiki I didn't have to do any such adjustment, just ran the script and pam! the user guide wiki page was updated.

dlrpgmsvc

Quote from: a1ex on June 18, 2013, 04:37:13 PM
Well.. small formatting quirks for the new wiki (which seems down anyway)

Do the new wiki is this ? -> http://magiclantern.wikia.com/wiki/Magic_Lantern_Firmware_Wiki     ...Or it's another one ?

I can see now it's online...
If you think it's impossible, you have lost beforehand

a1ex