Commit d4f4707e authored by Tim-Philipp Müller's avatar Tim-Philipp Müller 🐠

docs: remove FAQ which was moved into gst-docs module

parent ca3b05b9
DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc --enable-docbook
DISTCHECK_CONFIGURE_FLAGS=--enable-gtk-doc
# note: keep in sync with configure.ac
ACLOCAL_AMFLAGS = -I m4 -I common/m4
......
......@@ -53,7 +53,7 @@ fi
CONFIGURE_DEF_OPT='--enable-maintainer-mode --enable-gtk-doc'
if test "x$package" = "xgstreamer"; then
CONFIGURE_DEF_OPT="$CONFIGURE_DEF_OPT --enable-docbook --enable-failing-tests --enable-poisoning"
CONFIGURE_DEF_OPT="$CONFIGURE_DEF_OPT --enable-failing-tests --enable-poisoning"
elif test "x$package" = "xgst-plugins-bad"; then
CONFIGURE_DEF_OPT="$CONFIGURE_DEF_OPT --with-player-tests"
fi
......
......@@ -466,7 +466,6 @@ dnl check for gobject-introspection
GOBJECT_INTROSPECTION_CHECK([1.31.1])
dnl check for documentation tools
AG_GST_DOCBOOK_CHECK
GTK_DOC_CHECK([1.12])
AG_GST_PLUGIN_DOCS([1.12])
......@@ -1072,7 +1071,6 @@ common/Makefile
common/m4/Makefile
docs/Makefile
docs/design/Makefile
docs/faq/Makefile
docs/gst/Makefile
docs/gst/gstreamer.types
docs/libs/Makefile
......@@ -1153,8 +1151,7 @@ Configuration
Package name : ${GST_PACKAGE_NAME}
Package origin : ${GST_PACKAGE_ORIGIN}
Documentation (manuals) : ${enable_docbook}
Documentation (API) : ${enable_gtk_doc}
API Documentation : ${enable_gtk_doc}
Debug logging : ${enable_gst_debug}
Tracing subsystem hooks : ${enable_gst_tracer_hooks}
......
if ENABLE_DOCBOOK
SUBDIRS_DOCBOOK = faq
else
SUBDIRS_DOCBOOK =
endif
if ENABLE_GTK_DOC
if ENABLE_PLUGIN_DOCS
PLUGIN_DOCS_DIRS = plugins
......@@ -16,8 +10,8 @@ endif
BUILT_SOURCES = version.entities
SUBDIRS = design gst libs $(PLUGIN_DOCS_DIRS) $(SUBDIRS_DOCBOOK)
DIST_SUBDIRS = design gst libs plugins faq slides xsl
SUBDIRS = design gst libs $(PLUGIN_DOCS_DIRS)
DIST_SUBDIRS = design gst libs plugins slides xsl
EXTRA_DIST = \
manuals.mak htmlinstall.mak \
......
......@@ -6,12 +6,16 @@ IMPORTANT
Please make sure you've read and understood everything in this file
before you try changing documentation.
Some of the docbook-related bits in this README might be out of date now that
quite a bit of the documentation has moved into the gst-docs repository.
OVERVIEW
========
GStreamer has two sets of documentation that we maintain:
* API references, using gtk-doc (gstreamer, gstreamer-libs)
* "books", using DocBook/XML (faq, manual, pwg)
* FAQ / Application Development Manual / Plugin Writer's Guide / Tutorials -
these are maintained in markdown format and live in the gst-docs repository.
DOCBOOK NOTES
=============
......@@ -99,7 +103,7 @@ SPELL CHECKING
GTK-DOC NOTES
=============
* files under CVS control:
* files under revision control:
- Makefile.am
- gstreamer-sections.txt
describes which symbols later appear on one api-doc page
......
Makefile
Makefile.in
.deps
build
html
*.pdf
*.ps
### this is the part you can customize if you need to
# base name of doc
DOC = faq
# formats defined for upload-doc.mak
FORMATS=html ps pdf
# main xml file
MAIN = $(DOC).xml
# all xml sources
XML = $(notdir $(wildcard $(srcdir)/*.xml))
# base style sheet
CSS = base.css
# image sources
PNG_SRC =
FIG_SRC = $(notdir $(wildcard $(srcdir)/*.fig))
# extra sources to copy in build directory
EXTRA_SRC =
### this is the generic bit and you shouldn't need to change this
# get the generic docbuilding Makefile stuff
include $(srcdir)/../manuals.mak
# get the generic upload target
include $(top_srcdir)/common/upload-doc.mak
### this is standard automake stuff
# package up all the source
EXTRA_DIST = $(SRC)
# install documentation
faqdir = $(docdir)/$(DOC)
faq_DATA = $(PDF_DAT) $(PS_DAT)
include $(srcdir)/../htmlinstall.mak
pre.programlisting {
background: #E8E8FF;
}
<sect1 id="chapter-dependencies">
<title id="title-dependencies">Dependencies</title>
<qandaset defaultlabel="qanda">
<qandaentry>
<question id="dependencies-why-so-many">
<para>Why are there so many dependencies ?</para>
</question>
<answer>
<para>
Making a full-featured media framework is a huge undertaking in itself.
By using the work done by others, we both reduce the amount of redundant work
being done and leave ourselves free to work on the architecture itself
instead of working on the low-level stuff. We would be stupid not to reuse
the code others have written.
</para>
<para>
However, do realize that in no way you are forced to have all dependencies
installed. None of the core developers has all of them installed. GStreamer
has only a few obligate dependencies : GLib 2.0, liborc, and very
common stuff like glibc, a C compiler, and so on. All of the other
dependencies are optional.
</para>
<para>
So, in closing, let's rephrase the question to
<quote>Why are you giving me so many choices and such a rich environment ?
</quote>
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="dependencies-x">
<para>Is GStreamer X independent ?</para>
</question>
<answer>
<para>
Yes, we have no hard X dependency in any of our modules. There are many
GStreamer applications that run fine without any need for X, for example
streaming servers, transcoding applications, or audio applications that
don't output any video. Other applications output video to a framebuffer,
custom-made hardware sinks, or via wayland.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="dependencies-ladspa">
<para>What is GStreamer's position on efforts such as LADSPA ?</para>
</question>
<answer>
<para>
GStreamer actively supports such efforts, and in the case of
<ulink url="http://www.ladspa.org/"><citetitle>LADSPA</citetitle></ulink>,
we already have a wrapper plugin. This wrapper plug-in detects the LADSPA
plugins present on your system at run time.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="dependencies-midi">
<para>Does GStreamer support MIDI ?</para>
</question>
<answer>
<para>
Not yet. The GStreamer architecture should be able to support the needs of
MIDI applications very well however. If you are a developer interested in
adding MIDI support to GStreamer we are very interested in getting in touch
with you.
</para>
<para>
MIDI playback is provided by plugins such as wildmidi and timidity.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="dependencies-gnome">
<para>Does GStreamer depend on GNOME or GTK+ ?</para>
</question>
<answer>
<para>
No. But many of the applications developed for GStreamer do, including some
of our sample applications. Other applications use the Qt toolkit, or are
written for Mac OS/X or Windows. We aim to provide API that is toolkit
agnostic and can be used from any toolkit, desktop environment or operating
system.
</para>
</answer>
</qandaentry>
</qandaset>
</sect1>
<sect1 id="chapter-developing">
<title id="title-developing">Developing applications with GStreamer</title>
<qandaset defaultlabel="qanda">
<qandaentry>
<question id="developing-compile-programs">
<para>How do I compile programs that use GStreamer ?</para>
</question>
<answer>
<para>
GStreamer uses pkg-config to assist applications with compilation and
linking flags.
pkg-config is already used by GTK+, GNOME, SDL, and others; so if you are
familiar with using it for any of those, you're set.
</para>
<para>
If you're not familiar with pkg-config to compile and link a small
one-file program, pass the --cflags and --libs arguments to pkg-config.
For example:
<programlisting>
$ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-&GST_API_VERSION;` -o myprog myprog.c
</programlisting>
would be sufficient for a gstreamer-only program.
If (for example) your app also used GTK+ 2.0, you could use
<programlisting>
$ libtool --mode=link gcc `pkg-config --cflags --libs gstreamer-&GST_API_VERSION; gtk+-2.0` -o myprog myprog.c
</programlisting>
Those are back-ticks (on the same key with the tilde on US keyboards),
not single quotes.
</para>
<para>
For bigger projects, you should integrate pkg-config use in your Makefile,
or integrate with autoconf using the pkg.m4 macro (providing PKG_CONFIG_CHECK).
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="developing-uninstalled-gstreamer">
<para>How do I develop against an uninstalled GStreamer copy ?</para>
</question>
<answer>
<para>
It is possible to develop and compile against an uninstalled copy of
gstreamer and gst-plugins-* (for example, against git checkouts). This
allows you to develop against and test the latest GStreamer version
without having to install it and without interfering with your system-wide
GStreamer setup.
</para>
<para>
The easiest way too create such a setup is the
<ulink url="http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/create-uninstalled-setup.sh">latest version of create-uninstalled-setup.sh</ulink>
</para>
<para>
This setup makes use of the
<ulink url="http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/gst-uninstalled">latest version of gst-uninstalled</ulink>.
Running this script, you'll be in an environment where the uninstalled
tools and plugins will be used by default. Also, pkg-config will detect the
uninstalled copies before (and prefer them to) any installed copies.
</para>
<para>
Multiple uninstalled setups can be used in parallel. Have a look at
<ulink url="http://cgit.freedesktop.org/gstreamer/gstreamer/tree/scripts/gst-uninstalled">gst-uninstalled</ulink>
to see how it determines which environment is used.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="developing-gconf">
<para>How can I use GConf to get the system-wide defaults ?</para>
</question>
<answer>
<para>
For GNOME applications it's a good idea to use GConf to find the default ways
of outputting audio and video. You can do this by using the 'gconfaudiosink'
and 'gconfvideosink' elements for audio and video output. They will take
care of everything GConf-related for you and automatically use the outputs
that the user configured. If you are using gconfaudiosink, your application
should set the 'profile' property.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="developing-libtool-scripts">
<para>
How do I debug these funny shell scripts that libtool makes ?
</para>
</question>
<answer>
<para>
When you link a program against uninstalled GStreamer using libtool,
funny shell scripts are made to modify your shared object search path
and then run your program. For instance, to debug gst-launch, try
<programlisting>
libtool --mode=execute gdb /path/to/gst-launch
</programlisting>.
If this does not work, you're probably using a broken version of libtool.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="developing-mail-gstreamer-devel">
<para>Why is mail traffic so low on gstreamer-devel ?</para>
</question>
<answer>
<para>
Our main arena for coordination and discussion is IRC, not email.
Join us in <ulink url="irc://irc.freenode.net/#gstreamer">#gstreamer on irc.freenode.net</ulink>
For larger picture questions or getting more input from more persons,
a mail to gstreamer-devel is never a bad idea.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="developing-versioning">
<para>What kind of versioning scheme does GStreamer use ?</para>
</question>
<answer>
<para>
For public releases, GStreamer uses a standard MAJOR.MINOR.MICRO version
scheme. If the release consists of mostly bug fixes or incremental changes,
the MICRO version is incremented.
If the release contains big changes, the MINOR version is incremented.
If we're particularly giddy, we might even increase the MAJOR number.
Don't hold your breath for that though.
</para>
<para>
During the development cycle, GStreamer also uses a fourth or NANO number.
If this number is 1, then it's a git development version.
Any tarball or package that has a nano number of 1 is made from git and thus
not supported. Additionally, if you didn't get this package or tarball from
the GStreamer team, don't have high hopes on it doing whatever you want it
to do.
</para>
<para>
If the number is 2 or higher, it's an official pre-release in preparation
of an actual complete release. Your help in testing these tarballs and
packages is very much appreciated.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="developing-coding-style">
<para>What is the coding style for GStreamer code?</para>
</question>
<answer>
<para>
The core and almost all plugin modules are basically coded in K&amp;R with
2-space indenting. Just follow what's already there and you'll be fine.
</para>
<para>
Individual plugins in gst-plugins-* or plugins that you want considered for
addition to one of the gst-plugins-* modules should be coded in the same style.
It's easier if everything is consistent. Consistency is, of course, the goal.
</para>
<para>
Simply run your code (only the *.c files, not the header files) through
<programlisting>
indent \
--braces-on-if-line \
--case-brace-indentation0 \
--case-indentation2 \
--braces-after-struct-decl-line \
--line-length80 \
--no-tabs \
--cuddle-else \
--dont-line-up-parentheses \
--continuation-indentation4 \
--honour-newlines \
--tab-size8 \
--indent-level2
</programlisting>
before submitting a patch. (This is using GNU indent.) There is also a
gst-indent script in the GStreamer core source tree in the tools directory
which wraps this and contains the latest option. The easiest way to get the
indenting right is probably to develop against a git checkout. The local
git commit hook will ensure correct indentation. We only require code files to
be indented, header files may be indented manually for better readability
(however, please use spaces for indenting, not tabs, even in header files).
</para>
<para>
<!-- TODO(ensonic): link is dead, pending question on desktop-devel
As for the code itself, the
<ulink url="http://developer.gnome.org/doc/guides/programming-guidelines/book1.html">GNOME
coding guidelines</ulink> is a good read.
-->
Where possible, we try to adhere to the spirit of GObject and use similar
coding idioms.
</para>
<para>
Patches should be made against git master or the latest release and should be
in 'unified context' format (use diff -u -p). They should be attached to
a bug report (or feature request) in
<ulink url="http://bugzilla.gnome.org">bugzilla</ulink> rather than
sent to the mailing list.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="developing-translations">
<para>I have translated one of the module .po files into a new language. How do I get it included?</para>
</question>
<answer>
<para>GStreamer translations are uniformly managed through the Translation Project (http://translationproject.org). There are some instructions on how to join the Translation Project team and submit new translations at http://translationproject.org/html/translators.html.</para>
<para>New translations submitted via the Translation Project are merged periodically into git by the maintainers by running 'make download-po' in the various modules.</para>
</answer>
</qandaentry>
</qandaset>
</sect1>
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % image-entities SYSTEM "image.entities">
%image-entities;
<!ENTITY % version-entities SYSTEM "version.entities">
%version-entities;
<!ENTITY START SYSTEM "start.xml">
<!ENTITY GENERAL SYSTEM "general.xml">
<!ENTITY DEPENDENCIES SYSTEM "dependencies.xml">
<!ENTITY GETTING SYSTEM "getting.xml">
<!ENTITY USING SYSTEM "using.xml">
<!ENTITY TROUBLESHOOTING SYSTEM "troubleshooting.xml">
<!ENTITY GIT SYSTEM "git.xml">
<!ENTITY DEVELOPING SYSTEM "developing.xml">
<!ENTITY LEGAL SYSTEM "legal.xml">
]>
<article class="faq" id="index">
<articleinfo>
<title>GStreamer FAQ (&GST_VERSION;)</title>
<abstract>
<para>
This is the FAQ for GStreamer, a multimedia framework.
Questions and answers range from general information to
deep-down-and-dirty compilation issues.
</para>
</abstract>
<!--
<revhistory>
<revision>
<revnumber>0.2.1</revnumber>
<date>2006-05-19</date>
<revremark>Some updates for GStreamer-0.10</revremark>
</revision>
<revision>
<revnumber>0.2.0</revnumber>
<date>2006-03-16</date>
<revremark>Review and update whole document.</revremark>
</revision>
<revision>
<revnumber>0.1.1</revnumber>
<date>2003-04-24</date>
<revremark>Added Q&amp;A about developing with uninstalled copy.</revremark>
</revision>
<revision>
<revnumber>0.1.0</revnumber>
<date>2002-10-01</date>
<revremark>Initial conversion from FAQ database.</revremark>
</revision>
</revhistory>
-->
</articleinfo>
&START;
&GENERAL;
&DEPENDENCIES;
&GETTING;
&USING;
&TROUBLESHOOTING;
&GIT;
&DEVELOPING;
&LEGAL;
</article>
<sect1 id="chapter-general">
<title id="title-general">General</title>
<qandaset defaultlabel="qanda">
<qandaentry>
<question id="general-media-player">
<para>Is GStreamer a media player ?</para>
</question>
<answer>
<para>
No, GStreamer is a development framework for creating applications like
media players, video editors, streaming media broadcasters and so on.
That said, very good media players can easily be built on top
of GStreamer especially when using the high-level object called playbin.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="general-why-c">
<para>
Why is GStreamer written in C ? Why not C++/Objective-C/... ?
</para>
</question>
<answer>
<para>
We like C. Aside from "personal preference", there are a number of technical
reasons why C is nice in this project:
<itemizedlist>
<listitem><para>C is extremely portable.</para></listitem>
<listitem><para>C is fast.</para></listitem>
<listitem><para>It is easy to make language bindings for libraries written in C.
</para></listitem>
<listitem><para>The GObject object system provided by GLib implements objects in C,
in a portable, powerful way. This library provides for introspection and
runtime dynamic typing. It is a full OO system, but without the syntactic
sugar. If you want sugar, take a look at
<ulink url="http://live.gnome.org/Vala">Vala</ulink>.</para></listitem>
<listitem><para>Use of C integrates nicely with Gtk+ and GNOME. Some people like
this a lot, but neither Gtk+ nor GNOME are required by GStreamer.</para></listitem>
</itemizedlist>
</para>
<para>
So, in closing, we like C. If you don't, that's fine; if you still want to
help out on GStreamer, we always need more language binding people. And if
not, don't bother us; we're working :-)
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="general-applications">
<para>What applications are available for GStreamer ?</para>
</question>
<answer>
<para>
Many media player applications have chosen GStreamer for their backend.
Also a couple of media format conversion tools have been written using the powers of GStreamer.
With the advent of GStreamer-0.10 several media editing applications have been started.
</para>
<para>
For a list of projects, look at the
<ulink url="http://gstreamer.freedesktop.org/apps/">application list</ulink>
on the GStreamer project website.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="general-format">
<para>Does GStreamer support the format of my media files?</para>
</question>
<answer>
<para>
GStreamer aims to support every format imaginable, but that doesn't mean the
developers have managed to achieve that aim yet. If a GStreamer enabled
application doesn't play back your files, you can help us solve that problem
by <ulink url="http://bugzilla.gnome.org">filing an enhancement request
bug</ulink> for that format. If you have it, please provide:
<itemizedlist>
<listitem><para>links to other players, preferably Open Source and working
on Unix</para></listitem>
<listitem><para>links to explanations of the format.</para></listitem>
<listitem><para>ways to obtain mediafiles in that format to test.
</para></listitem>
</itemizedlist>
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="general-licensing">
<para>
What are the exact licensing terms for GStreamer and its plugins ?
</para>
</question>
<answer>
<para>
All of GStreamer, including our own plugin code, is licensed under the
<ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">GNU LGPL 2.1</ulink> license.
Some of the libraries we use for some of the plugins are however under the
GPL, which means that those plugins can not be used by a non-GPL-compatible
application.
</para>
<para>
As part of the GStreamer source download you find a file called
LICENSE_readme in gst-plugins package. That file contains information in the exact licensing
terms of the libraries we use. As a general rule, GStreamer aims at using
only LGPL or BSD licensed libraries if available and only use GPL or
proprietary libraries where no good LGPL or BSD alternatives are available.
</para>
<para>
From GStreamer 0.4.2 on, we implemented a license field for all of the plugins,
and in the future we might have the application enforce a stricter policy
(much like tainting in the kernel).
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="general-sound-server">
<para>Is GStreamer a sound server ?</para>
</question>
<answer>
<para>
No, GStreamer is not a soundserver. GStreamer does however have plugins
supporting most of the major soundservers available today, including
pulseaudio, ESD, aRTSd, Jack and others.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="general-platforms">
<para>
Will GStreamer be available for platforms other than Unix ?
</para>
</question>
<answer>
<para>
Depends. Our main target is the Unix platform. It also works on Win32 and Mac OS X,
but it may still be a bit challenging to get everything up and running.
That said, interest has been expressed in porting GStreamer to other platforms and the GStreamer core
team will gladly accept patches to accomplish this.
<!-- Please refer to the
<ulink url="http://gstreamer.net/status/?category=7">
platform support status table</ulink> -->
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="general-gnome">
<para>What is GStreamer's relationship with the GNOME community ?</para>
</question>
<answer>
<para>
While GStreamer is operated as an independent project, we do have a close
relationship with the GNOME community. Many of our hackers consider
themselves also to be members of the GNOME community.
GStreamer is officialy bundled with the GNOME desktop, as lots of packages
(like gnome-media, totem and rhythmbox) are using it.
This does not exclude use of GStreamer by other communities at all, of course.
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="general-kde">
<para>What is GStreamer's relationship with the KDE community ?</para>
</question>
<answer>
<para>
The GStreamer community wants to have as good a relationship as possible
with KDE, and we hope that someday KDE decides to adopt GStreamer as their
multimedia API (planned for KDE 4).
There have been contacts from time to time between the GStreamer community
and KDE and we do already have support for the aRTSd sound server used by KDE.
Also, some of the KDE hackers have created Qt bindings of GStreamer,
made a simple video player and using it in some audio players (JuK and AmaroK).
</para>
</answer>
</qandaentry>
<qandaentry>
<question id="general-my-application">
<para>
I'm considering adding GStreamer output to my application...
</para>
</question>
<answer>
<para>
That doesn't really make sense. GStreamer is not a sound server, so you don't
output directly to GStreamer, and it's not an intermediate API between
audio data and different kinds of audio sinks. It is a fundamental design
decision to use GStreamer in your app; there are no easy ways of somehow
'transfering' data from your app to GStreamer. Instead, your app would have
to use or implement a number of GStreamer elements, string them together, and
tell them to run. In that manner the data would all be internal to the
GStreamer pipeline.
</para>
<para>
That said, it is possible to write a plugin specific to your app that can get
at the audio data.
</para>
</answer>
</qandaentry>
</qandaset>
</sect1>
<sect1 id="chapter-getting">
<title id="title-getting">Getting GStreamer</title>
<qandaset defaultlabel="qanda">
<qandaentry>
<question id="getting-gstreamer">
<para>How do I get GStreamer ?</para>
</question>
<answer>
<para>
Generally speaking, you have three options, ranging from easy to hard :
<itemizedlist>
<listitem><para><link linkend="getting-gstreamer-packages">
distribution-specific packages</link></para></listitem>
<listitem><para><link linkend="getting-gstreamer-source">