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

docs: remove more docbook build cruft that's no longer needed

parent 41cb6439
......@@ -1075,8 +1075,6 @@ docs/gst/Makefile
docs/gst/gstreamer.types
docs/libs/Makefile
docs/plugins/Makefile
docs/slides/Makefile
docs/xsl/Makefile
docs/version.entities
m4/Makefile
pkgconfig/Makefile
......
......@@ -11,11 +11,9 @@ endif
BUILT_SOURCES = version.entities
SUBDIRS = design gst libs $(PLUGIN_DOCS_DIRS)
DIST_SUBDIRS = design gst libs plugins slides xsl
DIST_SUBDIRS = design gst libs plugins
EXTRA_DIST = \
manuals.mak htmlinstall.mak \
image-png image-pdf image-eps url.entities version.entities.in list-ulink.xsl
EXTRA_DIST = version.entities.in list-ulink.xsl
upload:
@if test "x$(SUBDIRS)" != x; then for a in $(SUBDIRS); do cd $$a; make upload; cd ..; done; fi
......
# this file adds rules for installing html subtrees
# I really don't like this hack, but automake doesn't seem to want to
# install directory trees :(
if DOC_HTML
install-data-local: html
$(mkinstalldirs) $(DESTDIR)$(docdir)/$(DOC)
cp -pr $(HTML_DAT) $(DESTDIR)$(docdir)/$(DOC)
uninstall-local:
for part in $(HTML_DAT); do rm -rf $(DESTDIR)$(docdir)/$(DOC)/$$part; done
else
install-data-local:
uninstall-local:
endif
<!ENTITY image "ps">
<!ENTITY IMAGE "EPS">
<!ENTITY image "pdf">
<!ENTITY IMAGE "EPS">
<!ENTITY image "png">
<!ENTITY IMAGE "PNG">
### These are all generic; we set all the variables we need
# intermediary build path
BUILDDIR = build
# same for images
BUILDIMAGESDIR = $(BUILDDIR)/images
# images
# right now, we only allow .png and .fig as source
# we might add more later if we feel the need
# PNG's can be source or built from .fig
PNG = $(strip $(PNG_SRC) $(FIG_SRC:.fig=.png))
# EPS .ps files can be built from .png or .fig
EPS = $(strip $(FIG_SRC:.fig=.ps) $(PNG_SRC:.png=.ps))
# PDF .pdf files can be built from .png or .fig
PDF = $(strip $(FIG_SRC:.fig=.pdf) $(PNG_SRC:.png=.pdf))
# where we expect to find images during building, whether by copying
# or by generating them
PNG_BUILT = $(foreach file, $(PNG), $(BUILDIMAGESDIR)/$(file))
EPS_BUILT = $(foreach file, $(EPS), $(BUILDIMAGESDIR)/$(file))
PDF_BUILT = $(foreach file, $(PDF), $(BUILDIMAGESDIR)/$(file))
SRC = $(XML) $(PNG_SRC) $(FIG_SRC) $(CSS) $(EXTRA_SRC)
# generate A4 docs
PAPER_LOCALE = nl_NL
### generate all documentation by default
# hook in html generation
all-local: html
# can we generate HTML ?
if DOC_HTML
HTML_DAT = html
HTML_TARGET = html/index.html
else #!DOC_HTML
HTML_DAT =
HTML_TARGET =
endif #DOC_HTML
html: $(HTML_TARGET)
# can we generate PS ?
if DOC_PS
PS_DAT = $(DOC).ps
else #!DOC_PS
PS_DAT =
endif #DOC_PS
ps: $(PS_DAT)
# can we generate PDF ?
if DOC_PDF
PDF_DAT = $(DOC).pdf
else #!DOC_PDF
PDF_DAT =
endif #DOC_PDF
pdf: $(PDF_DAT)
debug:
@echo "outputting some useful debug information"
@echo "Source XML:"
@echo "XML: '$(XML)'"
@echo "CSS: '$(CSS)'"
@echo "Source image files:"
@echo "PNG_SRC: '$(PNG_SRC)'"
@echo "FIG_SRC: '$(FIG_SRC)'"
@echo "All used image files:"
@echo "PNG: '$(PNG)'"
@echo "EPS: '$(EPS)'"
@echo "PDF: '$(PDF)'"
@echo "All used image files in their built path:"
@echo "PNG_BUILT: '$(PNG_BUILT)'"
@echo "EPS_BUILT: '$(EPS_BUILT)'"
@echo "PDF_BUILT: '$(PDF_BUILT)'"
@echo "End result products:"
@echo "HTML_DAT: '$(HTML_DAT)'"
@echo "PS_DAT: '$(PS_DAT)'"
@echo "PDF_DAT: '$(PDF_DAT)'"
# a rule to copy all of the source for docs into $(builddir)/build
$(BUILDDIR)/$(MAIN): $(XML) $(CSS) $(EXTRA_SRC)
@-mkdir -p $(BUILDDIR); \
if test "x$(EXTRA_SRC)" != "x"; then for a in $(EXTRA_SRC); do cp $(srcdir)/$$a $(BUILDDIR); done; fi ; \
for a in $(XML); do cp $(srcdir)/$$a $(BUILDDIR); done ; \
for a in $(CSS); do cp $(srcdir)/$$a $(BUILDDIR); done ; \
cp ../version.entities $(BUILDDIR) ; \
cp $(top_srcdir)/docs/url.entities $(BUILDDIR)
html/index.html: $(BUILDDIR)/$(MAIN) $(PNG_BUILT) $(FIG_SRC)
@$(MAKE) check-local
@echo "*** Generating HTML output ***"
@-mkdir -p html
@cp -f $(srcdir)/../image-png $(BUILDDIR)/image.entities
@cd $(BUILDDIR) && $(XSLTPROC) -o ../html/ --stringparam chunker.output.encoding UTF-8 --stringparam use.id.as.filename 1 $(XSLTPROC_FLAGS) "http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl" $(MAIN)
@test "x$(CSS)" != "x" && \
echo "Copying .css files: $(CSS)" && \
cp $(srcdir)/$(CSS) html
@test "x$(PNG)" != "x" && \
echo "Copying .png images: $(PNG_BUILT)" && \
mkdir -p html/images && \
cp $(PNG_BUILT) html/images || true
$(DOC).ps: $(BUILDDIR)/$(MAIN) $(EPS_BUILT) $(PNG_SRC) $(FIG_SRC)
@$(MAKE) check-local
@echo "*** Generating PS output ***"
@cp -f $(srcdir)/../image-eps $(BUILDDIR)/image.entities
cd $(BUILDDIR) && SP_ENCODING="UTF-8" docbook2ps -o .. $(MAIN)
# export LC_PAPER=$(PAPER_LOCALE) && cd $(BUILDDIR) && xmlto ps -o .. $(MAIN)
$(DOC).pdf: $(DOC).ps
@$(MAKE) check-local
@echo "*** Generating PDF output ***"
@ps2pdf $(DOC).ps
#$(DOC).pdf: $(MAIN) $(PDF) $(FIG_SRC)
# @echo "*** Generating PDF output ***"
# @cp -f $(srcdir)/../image-pdf image.entities
# @export LC_PAPER=$(PAPER_LOCALE) && xmlto pdf $(MAIN)
# @rm image.entities
clean-local:
-$(RM) -r $(BUILDDIR)
-$(RM) -r html
-$(RM) $(DOC).ps
-$(RM) $(DOC).pdf
-$(RM) -r www
### image generation
# copy png from source dir png
$(BUILDIMAGESDIR)/%.png: $(srcdir)/%.png
@echo "Copying $< to $@"
@mkdir -p $(BUILDIMAGESDIR)
@cp $< $@
# make png from fig
$(BUILDIMAGESDIR)/%.png: %.fig
@echo "Generating $@ from $<"
@mkdir -p $(BUILDIMAGESDIR)
@fig2dev -Lpng $< $@
# make ps(EPS) from fig
$(BUILDIMAGESDIR)/%.ps: %.fig
@echo "Generating $@ from $<"
@mkdir -p $(BUILDIMAGESDIR)
@fig2dev -Leps $< $@
# make pdf from fig
$(BUILDIMAGESDIR)/%.pdf: %.fig
@echo "Generating $@ from $<"
@mkdir -p $(BUILDIMAGESDIR)
@fig2dev -Lpdf $< $@
# make pdf from png
$(BUILDIMAGESDIR)/%.pdf: %.png
@echo "Generating $@ from $<"
@mkdir -p $(BUILDIMAGESDIR)
@cat $< | pngtopnm | pnmtops -noturn 2> /dev/null | epstopdf --filter --outfile $@ 2> /dev/null
# make ps(EPS) from png
$(BUILDIMAGESDIR)/%.ps: %.png
@echo "Generating $@ from $<"
@mkdir -p $(BUILDIMAGESDIR)
@cat $< | pngtopnm | pnmtops -noturn > $@ 2> /dev/null
# make sure xml validates properly
check-local: $(BUILDDIR)/$(MAIN)
@cp -f $(srcdir)/../image-png $(BUILDDIR)/image.entities
@cd $(BUILDDIR) && xmllint -noout -valid $(MAIN)
@cd $(BUILDDIR) && \
if [ `which curl` ]; then \
links=`$(XSLTPROC) $(XSLTPROC_FLAGS) --xinclude $(abs_top_srcdir)/docs/list-ulink.xsl $(MAIN) | egrep '^http' | sort | uniq` && \
have_error=0 && \
for link in $$links; do \
code=`curl -s -m20 -o /dev/null -I -w "%{http_code}" $$link`; \
if [ \( $$? -ne 0 \) -o \( $$code -gt 399 \) ]; then \
echo "exit_status=$$?, http_code=$$code: $$link"; \
grep -Hnr "$$link" .; \
have_error=1; \
fi; \
done \
fi
# avoid 'cp: cannot create regular file `build/image.entities': File exists'
# errors during 'make distcheck' by disabling parallel builds
.NOTPARALLEL:
EXTRA_DIST = abstract abstract.save outline README slides
These are notes for slides to be presented at the OGI DISC Cookie Talk,
Oct 22, 1999. Outline will be text, probably written up in PowerPoint for
ease of presentation, and converted to .ps, .pdf, and .html once the talk
has been given.
Intro to GStreamer
GStreamer is a media-streaming architecture that I've been developing at
home for about 4 months now. It's designed to overcome some of the
problems I've seen in both the OGI Pipeline and in reading through
DirectShow docs. After an overview of the existing OGI Pipeline, I'll
cover GStreamer's existing and planned architecture, and list what remains
to be done. GStreamer is mostly frozen right now, as it is to be released
as 0.1.0 on Oct 31. Major thaw will occur in a few weeks.
Intro to GStreamer
GStreamer is a media-streaming architecture that I've been developing at
home for about 4 months now. It's designed to overcome some of the
problems I've seen in both the OGI Pipeline and in reading through
DirectShow docs. After an overview of the existing OGI Pipeline, I'll
cover GStreamer's existing and planned architecture, and list what remains
to be done. GStreamer is mostly frozen right now, as it is to be released
as 0.1.0 on Oct 31. Major thaw will occur in a few weeks.
Introduction (1)
(sorry, no cool logo/graphic yet, ideas?)
GStreamer is a library and set of tools to build arbitrary,
reconfigurable filter graphs. It derives from the OGI Pipeline
and DirectShow (docs, no experience), and is in its second
generation (first was completed/abandoned *in* Atlanta on the
way to the Linux Expo).
0.1.0 release is scheduled for Oct 31, 1999.
Will cover Background, Goals, Design, and Futures
Why do we need this?
launch reads the command line to create the graph, from .so's
Connections (queues) are made by launcher, lots of switchout code
Argument handling is messy, at start-time only
...thus there is basically only one state: running
There is no real master process capable of seeing the whole
pipeline as a graph, so wiring A->B->C with some backchannel
(parameter, not data stream) from C to A is hard
Channels try to do IPC, file, and network I/O, excess abstraction
Goals (1)
Provide a clean way to both build graphs and write new elements
Make things easier by providing auto-connect, stock sub-graphs
Include tools sorely lacking in OGI pipeline, like editor, saves
Enable Linux to catch up with M$'s world, allowing commercial
plugins to a stable API (as of 1.0) so we don't end up with N
wheels from N-M different people (multiple projects)
Overview (1)
Object hierarchy capable of run-time discovery, based on GtkObject
Deeply nested parent-child relationships enable threads, blackboxes
Buffers can point to anything, are typed, and can carry metadata
Plugins can be loaded at any point, and registry reduces loads
Symbiotic editor lets you design/run/save graphs visually
What are filter graphs? (1)
Filters take data in and spit data out, doing something to it
Filters have N>=0 inputs and M>=0 outputs
Filter graphs are many filters connected together, like a circuit
The goal is typically to move data from 'left' to 'right', towards
some kind of user-visible conclusion, i.e. audio or video
Architecture (3?)
- Graphs of Elements
(here lies screen-grab from editor)
Element is core Object, Bins hold (and are) Elements
Pads are fundamental to an Element, are cross-wired with pointers
Since Bins hold Elements, and Bins are Elements, Bins hold Bins
'Ghostpads' provide interfaces for Bins without native interfaces
# Threads are type of Bin that actually run in separate threads
- States
(table of states, invariants, and descriptions)
COMPLETE Element has all needed information
RUNNING Element has acquired resources, ready to go
DISCOVERY ... (unimplemented)
PREROLL ... (unimplemented)
PLAYING Element is actively trading data
PAUSED Special state where things just don't run (?..)
States are used to keep elements in check
- Buffers
Buffers designed to be versatile, with arbitrary typing/metadata
Has pointer to data, length, so can point to someone else's data
Type system (crude so far) ensures buffers don't go stray
Metadata can be attached, such as the audio parameters
Ref-counting and copy-on-write avoids most copies, not complete
Sub-buffers can be created from bigger buffer, limitting copies
Gtk+ Object System (2)
- Pros
C-language object system, well tested (Gtk+, Gnome...)
Arguments of any fundamental type, read/write, built-in hooks
Signals used for hooks into object events, overridable
Run-time discovery of args, signals (quarks)
- Cons
No multiple-inheritance, though I haven't *needed* it
There are some holes (can't attach quarks to *eveything*)
- Design
Classes, instances are structs; 1st item is parent class
Type system allows clean casting, ^^^^^^
Arguments are set/get by string, use functions to do the work,
thus setting an arg might trigger a redraw of the GUI
Signals are strings, use marshallers, various firing methods
Basic GStreamer objects (1)
- Elements
(show class,instance structs)
Very simple, just provides a means to handle pads, state
- Bins
(show class,instance structs)
Supports children, handles group state transitions
Pads (1)
Pad list type, direction, and chaining function ptr
When creating a sink pad (!src) you set the chaining function
gst_pad_connect() sets the peers, and copies chain function to src
Passing buffer to a src pad transparently calls the chain function
(graph goes here...)
Sources (1)
Source provides functions to push data
Regular push() function just takes next N bytes and sends them
Async push_region() grabs N bytes at offset O and sends them
EOF signal [will] reset the state from PLAYING down to !RUNNING
"location" argument is global by convention, for filenames...URIs
Connections (1)
Special type of Filter that
Threads (1)
Special case of Bin that actually creates a thread transparently
When RUNNING, thread exists, mutex/cond used to go [!]PLAYING
Automatically determines how to start sub-graph
Looks for both Sources and Elements wired to Connection
Will cooperate with Pipelines when threading is not available
Typing and Metadata (1)
- Types
Based on MIME types, set up as quarks, and dealt with as int
Usable entirely at run-time, since they're registerable by plugins
- Metadata
Also registered as an int, but must be compile time due to structs
Have refcounts and CoW semantics, since they travel with buffers
Plugins (1)
Plugin architecture designed around class system
Arguments and signals provide interface over standard base class
Each Element defined by ElementFactory, which is queried by name
At plugin load, any number of ElementFactories and Types registered
Element registers against Type as source or sink
Editor (2+?)
(show filter graph snapshot, a different one, more complex)
Built as a parallel object hierarchy on top of GNOME Canvas
Every object in filter graph has equivalent in editor, plus some
Canvas is designed with groups and signal-propagation, so...
Why not build the whole thing as subclasses of CanvasGroup?
...because updates get messy/recursive (the way I *was* doing it)
Solution is to modify objects so they own Group rather than being
Relatively trivial modification, but requires lots of repointering
Still a genealogical mess of parents and children...
XML
The goal is to use XML heavily, with an eye towards DOM
Used for both saving and providing pre-build components
Both graph and editor will have namespace, they'll interleave
A generic save function will exist for Elements, with hooks
Saving an EditorElement will also save Element
Also used for a plugin registry, to avoid loading all plugins
leaky bucket is trivial
applications - generic conferencing tool (repluggable codecs), mixing
environment (data flow graphs)
Introduction
Why do we need this?
Goals
Overview
What are filter graphs?
Gtk+ Object System
Architecture - Elements
Pads
Architecture - Buffers
Typing and Metadata
Sources
Threads and Connections
Architecture - States
Plugins
Editor
XML
Futures
<!-- These entities could be overridden for installed docs -->
<!ENTITY URLAPI "http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/">
XSL=$(wildcard *.xsl)
EXTRA_DIST = $(XSL)
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version='1.0'>
<!-- Turn on admonition graphics. -->
<xsl:param name="admon.graphics" select="'1'"/>
<xsl:param name="admon.graphics.path" select="'stylesheet-images/'"/>
</xsl:stylesheet>
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version='1.0'>
<!-- Use an HTML CSS stylesheet. -->
<xsl:param name="html.stylesheet" select="'base.css'"/>
</xsl:stylesheet>
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version='1.0'>
<!-- This sets the extension for HTML files to ".html". -->
<!-- (The stylesheet's default for XHTML files is ".xhtm".) -->
<xsl:param name="html.ext" select="'.html'"/>
</xsl:stylesheet>
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'
xmlns="http://www.w3.org/TR/xhtml1/transitional"
exclude-result-prefixes="#default">
<!-- This file is for customizing the default XSL stylesheets. -->
<!-- We include them here (this one is for print output): -->
<xsl:import
href="http://docbook.sourceforge.net/release/xsl/1.50.0/fo/docbook.xsl"/>
<!-- .. and customize them here: -->
<xsl:include href="ulink.xsl"/>
<xsl:include href="keycombo.xsl"/>
<xsl:param name="body.font.family" select="'serif'"/>
<xsl:param name="sans.font.family" select="'sans-serif'"/>
<xsl:param name="title.font.family" select="'sans-serif'"/>
</xsl:stylesheet>
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'
xmlns="http://www.w3.org/TR/xhtml1/transitional"
exclude-result-prefixes="#default">
<!-- This file is for customizing the default XSL stylesheets. -->
<!-- We include them here (this one is for HTML output): -->
<xsl:import
href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
<!-- .. and customize them here: -->
<xsl:include href="fileext.xsl"/>
<xsl:include href="keycombo.xsl"/>
<!-- <xsl:include href="admon.xsl"/> -->
<xsl:include href="css.xsl"/>
<xsl:param name="generate.component.toc" select="0"/>
</xsl:stylesheet>
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version='1.0'>
<!-- There is a bug in docbook-xsl-1.45; work around it here. -->
<!-- Also change it slightly for emacs key descriptions. -->
<xsl:template match="keycombo">
<xsl:variable name="action" select="@action"/>
<xsl:variable name="joinchar">
<xsl:choose>
<xsl:when test="$action='seq'"><xsl:text> </xsl:text></xsl:when>
<xsl:when test="$action='simul'">-</xsl:when>
<xsl:otherwise>-</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:for-each select="./*">
<xsl:if test="position()>1">
<xsl:value-of select="$joinchar"/>
</xsl:if>
<xsl:apply-templates select="."/>
</xsl:for-each>
</xsl:template>
</xsl:stylesheet>
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
version='1.0'>
<!-- This alters the rendering of URLs. Let's follow RFC 2396 -->
<!-- guidelines. -->
<xsl:template match="ulink">
<fo:basic-link external-destination="{@url}"
xsl:use-attribute-sets="xref.properties">
<xsl:choose>
<xsl:when test="count(child::node())=0">
<xsl:text>&lt;</xsl:text>
<xsl:value-of select="@url"/>
<xsl:text>&gt;</xsl:text>
</xsl:when>
<xsl:otherwise>
<xsl:apply-templates/>
</xsl:otherwise>
</xsl:choose>
</fo:basic-link>
<xsl:if test="count(child::node()) != 0">
<fo:inline hyphenate="false">
<xsl:text> at &lt;</xsl:text>
<xsl:value-of select="@url"/>
<xsl:text>&gt;</xsl:text>
</fo:inline>
</xsl:if>
</xsl:template>
</xsl:stylesheet>
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment