[MEncoder-users] Making manpage accessible

[Ilya Zakharevich]

[A complimentary Cc of this posting was NOT [per weedlist] sent to
Andrew Berg 
<mencoder-users at mplayerhq.hu>], who wrote in article <4C55E3AF.1030402 at gmail.com>:
> The man page assumes you know the basics of video encoding. It's not an
> introduction to encoding,

Do not we all know this! ...

> nor should it be.

... But THIS attitude is very counter-productive.  It makes the
manpage unusable to (IMO) 95% of people who want to read it.  While
including a COMPLETE introduction is, of course, out of question, a
very concise launch-vehicle IS possible (therefore, is NECESSARY).

IMO, all that is needed is a list of possible ISSUES with video
encoding, and references to where the reader can get some starting
information about what the issue is about.  When this list is
finalized, it may be accompanied by references to mencoder's options
related to each issue.

Here are examples of possible "issues" - just to illustrate how little
one may say AND BE helpful.  This list is not designed to be complete;
and I think that the final list would be very short too - about dozen
items...

  a) Decoding: decoded video formats result in a sequence of images
     (frames) (or half-images == fields, for interlaced formats).
     However, these frames may (1) go in a steady rate (at a certain
     FPS value), or (2) come arbitrarily with "a timestamp attached to
     them".  Conversion (1) ==> (2) is trivial, but (2) ==> (1) 

  a') mencoder is by design brain-damaged so that it encodes only to a
      "steady FPS" flows.  Hence conversion "(2) ==> (1)" is often
      needed.

  b) "Profile issues": many formats have features which are allowed to
     be only partially supported by decoders.  Therefore one may need
     to know in advance what decoders are going to be used, and how to
     inform mencoder about their limitations.

  c) Envelops versus formats.

  d) AVI format issues (sometimes OpenDML index is needed, sometimes
     not; some players do not support OpenDML index - and mencoder is
     not intelligent enough to choose the best strategy; can one embed
     chapters/subtitles?).  Mencoder being not good in producing
     anything but AVI...

  e) interlacing issues (including "solutions" such as using
     `interlace' flags for encoders); the fact that many streams
     consist of chunks with different interlacing modes.

  f) Subtitle issues (may be text- or image-based; may have timestamps
     in terms of time flow, or frame numbers; text-based have an
     explicit or assumed encoding).

  g) Aspect and cropping issues (including some players ignoring
     aspect hints, and cropping advices: divisibility by 16 etc).

  h) Broken "video chain" issues: initially a video stream might have
     been perfect, but during "studio work" some (irrepable, or only
     partially reparable) damage might have been done (frame rate
     conversions without paying attention to telecining/interlacing,
     frame rate conversion by "frame overlap", silly telecining
     algorithms, wrong telecine flags, dumb de-interlacing etc).

In the same section one COULD also mention some long-standing problems
of mencoder (like broken envelops).  And one can mention SOLUTIONS
which by hysterical raisins did not become mencoder defaults (like
ALWAYS using harddup)...

Hope this helps,
Ilya