Merge remote-tracking branch 'cigaes/master'

* cigaes/master:
  doc/faq: explain DAR/SAR preserving.
  doc: set documentencoding on toplevel texi files.

Merged-by: Michael Niedermayer <michaelni@gmx.at>

27 files changed, 61 insertions, 0 deletions

diff --git a/doc/developer.texi b/doc/developer.texi
index f1351a5db2..a5e9c9915c 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle Developer Documentation
 @titlepage
diff --git a/doc/faq.texi b/doc/faq.texi
index 3d94d4d5ed..c3db720681 100644
--- a/doc/faq.texi
+++ b/doc/faq.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle FFmpeg FAQ
 @titlepage
@@ -466,6 +467,40 @@ point acceptable for your tastes. The most common options to do that are
 @option{-qscale} and @option{-qmax}, but you should peruse the documentation
 of the encoder you chose.
 
+@section I have a stretched video, why does scaling does not fix it?
+
+A lot of video codecs and formats can store the @emph{aspect ratio} of the
+video: this is the ratio between the width and the height of either the full
+image (DAR, display aspect ratio) or individual pixels (SAR, sample aspect
+ratio). For example, EGA screens at resolution 640×350 had 4:3 DAR and 35:48
+SAR.
+
+Most still image processing work with square pixels, i.e. 1:1 SAR, but a lot
+of video standards, especially from the analogic-numeric transition era, use
+non-square pixels.
+
+Most processing filters in FFmpeg handle the aspect ratio to avoid
+stretching the image: cropping adjusts the DAR to keep the SAR constant,
+scaling adjusts the SAR to keep the DAR constant.
+
+If you want to stretch, or “unstretch”, the image, you need to override the
+information with the
+@url{http://ffmpeg.org/ffmpeg-filters.html#setdar_002c-setsar, @code{setdar or setsar filters}}.
+
+Do not forget to examine carefully the original video to check whether the
+stretching comes from the image or from the aspect ratio information.
+
+For example, to fix a badly encoded EGA capture, use the following commands,
+either the first one to upscale to square pixels or the second one to set
+the correct aspect ratio or the third one to avoid transcoding (may not work
+depending on the format / codec / player / phase of the moon):
+
+@example
+ffmpeg -i ega_screen.nut -vf scale=640:480,setsar=1 ega_screen_scaled.nut
+ffmpeg -i ega_screen.nut -vf setdar=4/3 ega_screen_anamorphic.nut
+ffmpeg -i ega_screen.nut -aspect 4/3 -c copy ega_screen_overridden.nut
+@end example
+
 @chapter Development
 
 @section Are there examples illustrating how to use the FFmpeg libraries, particularly libavcodec and libavformat?
diff --git a/doc/fate.texi b/doc/fate.texi
index 4e5cbd7d0f..73c603cf76 100644
--- a/doc/fate.texi
+++ b/doc/fate.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle FFmpeg Automated Testing Environment
 @titlepage
diff --git a/doc/ffmpeg-bitstream-filters.texi b/doc/ffmpeg-bitstream-filters.texi
index e33e005024..bbde25708f 100644
--- a/doc/ffmpeg-bitstream-filters.texi
+++ b/doc/ffmpeg-bitstream-filters.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle FFmpeg Bitstream Filters Documentation
 @titlepage
diff --git a/doc/ffmpeg-codecs.texi b/doc/ffmpeg-codecs.texi
index 6f8f5a34d9..7df4391ae7 100644
--- a/doc/ffmpeg-codecs.texi
+++ b/doc/ffmpeg-codecs.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle FFmpeg Codecs Documentation
 @titlepage
diff --git a/doc/ffmpeg-devices.texi b/doc/ffmpeg-devices.texi
index b44bd7285b..721c0df800 100644
--- a/doc/ffmpeg-devices.texi
+++ b/doc/ffmpeg-devices.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle FFmpeg Devices Documentation
 @titlepage
diff --git a/doc/ffmpeg-filters.texi b/doc/ffmpeg-filters.texi
index bb920ce26c..b643f2c027 100644
--- a/doc/ffmpeg-filters.texi
+++ b/doc/ffmpeg-filters.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle FFmpeg Filters Documentation
 @titlepage
diff --git a/doc/ffmpeg-formats.texi b/doc/ffmpeg-formats.texi
index e205caabeb..d916ee84b7 100644
--- a/doc/ffmpeg-formats.texi
+++ b/doc/ffmpeg-formats.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle FFmpeg Formats Documentation
 @titlepage
diff --git a/doc/ffmpeg-protocols.texi b/doc/ffmpeg-protocols.texi
index d992e7571a..f3a09f6a69 100644
--- a/doc/ffmpeg-protocols.texi
+++ b/doc/ffmpeg-protocols.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle FFmpeg Protocols Documentation
 @titlepage
diff --git a/doc/ffmpeg-resampler.texi b/doc/ffmpeg-resampler.texi
index 5bef78967b..be3784f3ed 100644
--- a/doc/ffmpeg-resampler.texi
+++ b/doc/ffmpeg-resampler.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle FFmpeg Resampler Documentation
 @titlepage
diff --git a/doc/ffmpeg-scaler.texi b/doc/ffmpeg-scaler.texi
index c4ddc0972a..9ab12a1f95 100644
--- a/doc/ffmpeg-scaler.texi
+++ b/doc/ffmpeg-scaler.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle FFmpeg Scaler Documentation
 @titlepage
diff --git a/doc/ffmpeg-utils.texi b/doc/ffmpeg-utils.texi
index 581e2eab81..e39cfa85ec 100644
--- a/doc/ffmpeg-utils.texi
+++ b/doc/ffmpeg-utils.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle FFmpeg Utilities Documentation
 @titlepage
diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
index e7c86ccf18..6e51c44f29 100644
--- a/doc/ffmpeg.texi
+++ b/doc/ffmpeg.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle ffmpeg Documentation
 @titlepage
diff --git a/doc/ffplay.texi b/doc/ffplay.texi
index 45731a2dc6..d5397a9ecb 100644
--- a/doc/ffplay.texi
+++ b/doc/ffplay.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle ffplay Documentation
 @titlepage
diff --git a/doc/ffprobe.texi b/doc/ffprobe.texi
index 5c904704bb..0fdf45e27b 100644
--- a/doc/ffprobe.texi
+++ b/doc/ffprobe.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle ffprobe Documentation
 @titlepage
diff --git a/doc/ffserver.texi b/doc/ffserver.texi
index 83b6520dd1..57c95fbbda 100644
--- a/doc/ffserver.texi
+++ b/doc/ffserver.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle ffserver Documentation
 @titlepage
diff --git a/doc/general.texi b/doc/general.texi
index 49f5ade428..197a800578 100644
--- a/doc/general.texi
+++ b/doc/general.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle General Documentation
 @titlepage
diff --git a/doc/git-howto.texi b/doc/git-howto.texi
index 750662a458..8ece341321 100644
--- a/doc/git-howto.texi
+++ b/doc/git-howto.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle Using git to develop FFmpeg
 
diff --git a/doc/libavcodec.texi b/doc/libavcodec.texi
index 618f9f6b74..87b90db48c 100644
--- a/doc/libavcodec.texi
+++ b/doc/libavcodec.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle Libavcodec Documentation
 @titlepage
diff --git a/doc/libavdevice.texi b/doc/libavdevice.texi
index d5f790b675..9b10282cde 100644
--- a/doc/libavdevice.texi
+++ b/doc/libavdevice.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle Libavdevice Documentation
 @titlepage
diff --git a/doc/libavfilter.texi b/doc/libavfilter.texi
index 4f82944d36..52e075369c 100644
--- a/doc/libavfilter.texi
+++ b/doc/libavfilter.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle Libavfilter Documentation
 @titlepage
diff --git a/doc/libavformat.texi b/doc/libavformat.texi
index 85e49cb952..d505d644f6 100644
--- a/doc/libavformat.texi
+++ b/doc/libavformat.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle Libavformat Documentation
 @titlepage
diff --git a/doc/libavutil.texi b/doc/libavutil.texi
index 5ec7e84dfc..7a1c332b81 100644
--- a/doc/libavutil.texi
+++ b/doc/libavutil.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle Libavutil Documentation
 @titlepage
diff --git a/doc/libswresample.texi b/doc/libswresample.texi
index 383e53779a..bb57278314 100644
--- a/doc/libswresample.texi
+++ b/doc/libswresample.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle Libswresample Documentation
 @titlepage
diff --git a/doc/libswscale.texi b/doc/libswscale.texi
index 818e98880b..757fd24139 100644
--- a/doc/libswscale.texi
+++ b/doc/libswscale.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle Libswscale Documentation
 @titlepage
diff --git a/doc/nut.texi b/doc/nut.texi
index fee12da9e7..a02f86ace0 100644
--- a/doc/nut.texi
+++ b/doc/nut.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle NUT
 
diff --git a/doc/platform.texi b/doc/platform.texi
index a852170f4f..73b73fb490 100644
--- a/doc/platform.texi
+++ b/doc/platform.texi
@@ -1,4 +1,5 @@
 \input texinfo @c -*- texinfo -*-
+@documentencoding UTF-8
 
 @settitle Platform Specific Information
 @titlepage