mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-26 11:41:09 +00:00
collect docs notes
Original commit message from CVS: collect docs notes
This commit is contained in:
Thomas Vander Stichele
parent
420b49905b
commit
d839d3c63c
5 changed files with 140 additions and 318 deletions
|
|
@ -1,3 +1,11 @@
|
|||
2004-01-28 Thomas Vander Stichele <thomas at apestaart dot org>
|
||||
|
||||
* docs/95NonPath:
|
||||
* docs/HACKING:
|
||||
* docs/README:
|
||||
* docs/building-the-docs-on-debian:
|
||||
collect relevant bits of doc info
|
||||
|
||||
2004-01-28 Ronald Bultje <rbultje@ronald.bitfreak.net>
|
||||
|
||||
* docs/pwg/advanced_tagging.xml:
|
||||
|
|
|
|||
187
docs/95NonPath
187
docs/95NonPath
|
|
@ -1,187 +0,0 @@
|
|||
% Part 2: Non-path options.
|
||||
|
||||
% Write .log/.dvi/etc. files here, if the current directory is unwritable.
|
||||
% TEXMFOUTPUT = /tmp
|
||||
|
||||
% If a dynamic file creation fails, log the command to this file, in
|
||||
% either the current directory or TEXMFOUTPUT. Set to the
|
||||
% empty string or 0 to avoid logging.
|
||||
MISSFONT_LOG = missfont.log
|
||||
|
||||
% Set to a colon-separated list of words specifying warnings to suppress.
|
||||
% To suppress everything, use TEX_HUSH = all; this is currently equivalent to
|
||||
% TEX_HUSH = checksum:lostchar:readable:special
|
||||
% To suppress nothing, use TEX_HUSH = none or do not set the variable at all.
|
||||
TEX_HUSH = none
|
||||
|
||||
% Enable system commands via \write18{...}?
|
||||
shell_escape = f
|
||||
|
||||
% Allow TeX \openin, \openout, or \input on filenames starting with `.'
|
||||
% (e.g., .rhosts) or outside the current tree (e.g., /etc/passwd)?
|
||||
% a (any) : any file can be opened.
|
||||
% r (restricted) : disallow opening "dotfiles".
|
||||
% p (paranoid) : as 'r' and disallow going to parent directories, and
|
||||
% restrict absolute paths to be under $TEXMFOUTPUT.
|
||||
openout_any = p
|
||||
openin_any = a
|
||||
|
||||
% Allow TeX, MF, and MP to parse the first line of an input file for
|
||||
% the %&format construct.
|
||||
parse_first_line = t
|
||||
|
||||
% Allow TeX, eTeX, Omega to include `src:' specials in the dvi file.
|
||||
% These specials are used by viewers to jump from the viewer into
|
||||
% the editor at the right page/lineno.
|
||||
% Possible values : none auto cr display hbox math par parend vbox
|
||||
src_specials = none
|
||||
|
||||
% Enable the mktex... scripts by default? These must be set to 0 or 1.
|
||||
% Particular programs can and do override these settings, for example
|
||||
% dvips's -M option. Your first chance to specify whether the scripts
|
||||
% are invoked by default is at configure time.
|
||||
%
|
||||
% These values are ignored if the script names are changed; e.g., if you
|
||||
% set DVIPSMAKEPK to `foo', what counts is the value of the environment
|
||||
% variable/config value `FOO', not the `MKTEXPK' value.
|
||||
%
|
||||
% MKTEXTEX = 0
|
||||
% MKTEXPK = 0
|
||||
% MKTEXMF = 0
|
||||
% MKTEXTFM = 0
|
||||
% MKOCP = 0
|
||||
% MKOFM = 0
|
||||
|
||||
% What MetaPost runs to make MPX files. This is passed an option -troff
|
||||
% if MP is in troff mode. Set to `0' to disable this feature.
|
||||
MPXCOMMAND = makempx
|
||||
|
||||
|
||||
% Part 3: Array and other sizes for TeX (and Metafont and MetaPost).
|
||||
%
|
||||
% If you want to change some of these sizes only for a certain TeX
|
||||
% variant, the usual dot notation works, e.g.,
|
||||
% main_memory.hugetex = 20000000
|
||||
%
|
||||
% If a change here appears to be ignored, try redumping the format file.
|
||||
|
||||
% Memory. Must be less than 8,000,000 total.
|
||||
%
|
||||
% main_memory is relevant only to initex, extra_mem_* only to non-ini.
|
||||
% Thus, have to redump the .fmt file after changing main_memory; to add
|
||||
% to existing fmt files, increase extra_mem_*. (To get an idea of how
|
||||
% much, try \tracingstats=2 in your TeX source file;
|
||||
% web2c/tests/memtest.tex might also be interesting.)
|
||||
%
|
||||
% To increase space for boxes (as might be needed by, e.g., PiCTeX),
|
||||
% increase extra_mem_bot.
|
||||
%
|
||||
% For some xy-pic samples, you may need as much as 700000 words of memory.
|
||||
% For the vast majority of documents, 60000 or less will do.
|
||||
%
|
||||
main_memory.context = 1500000
|
||||
main_memory.mpost = 1000000
|
||||
main_memory = 2500000 % words of inimemory available; also applies to inimf&mp
|
||||
extra_mem_top = 0 % extra high memory for chars, tokens, etc.
|
||||
extra_mem_bot = 0 % extra low memory for boxes, glue, breakpoints, etc.
|
||||
|
||||
obj_tab_size.context = 300000
|
||||
|
||||
% Words of font info for TeX (total size of all TFM files, approximately).
|
||||
font_mem_size = 400000
|
||||
|
||||
% Total number of fonts. Must be >= 50 and <= 2000 (without tex.ch changes).
|
||||
font_max = 1000
|
||||
|
||||
% Extra space for the hash table of control sequences (which allows 10K
|
||||
% names as distributed).
|
||||
hash_extra.context = 40000
|
||||
hash_extra = 50000
|
||||
|
||||
% Max number of characters in all strings, including all error messages,
|
||||
% help texts, font names, control sequences. These values apply to TeX and MP.
|
||||
pool_size.context = 750000
|
||||
pool_size = 500000
|
||||
% Minimum pool space after TeX/MP's own strings; must be at least
|
||||
% 25000 less than pool_size, but doesn't need to be nearly that large.
|
||||
string_vacancies.context = 45000
|
||||
string_vacancies = 45000
|
||||
% Maximum number of strings.
|
||||
max_strings.context = 55000
|
||||
max_strings = 55000
|
||||
% min pool space left after loading .fmt
|
||||
pool_free.context = 47500
|
||||
pool_free = 5000
|
||||
|
||||
% Hyphenation trie. As distributed, the maximum is 65535; this should
|
||||
% work unless `unsigned short' is not supported or is smaller than 16
|
||||
% bits. This value should suffice for UK English, US English, French,
|
||||
% and German (for example). To increase, you must change
|
||||
% `ssup_trie_opcode' and `ssup_trie_size' in tex.ch (and rebuild TeX);
|
||||
% the trie will then consume four bytes per entry, instead of two.
|
||||
%
|
||||
% US English, German, and Portuguese: 30000.
|
||||
% German: 14000.
|
||||
% US English: 10000.
|
||||
%
|
||||
trie_size = 64000
|
||||
|
||||
% Buffer size. TeX uses the buffer to contain input lines, but macro
|
||||
% expansion works by writing material into the buffer and reparsing the
|
||||
% line. As a consequence, certain constructs require the buffer to be
|
||||
% very large. As distributed, the size is 50000; most documents can be
|
||||
% handled within a tenth of this size.
|
||||
buf_size = 200000
|
||||
|
||||
hyph_size = 1000 % number of hyphenation exceptions, >610 and <32767.
|
||||
nest_size.context = 500
|
||||
nest_size = 500 % simultaneous semantic levels (e.g., groups)
|
||||
max_in_open = 15 % simultaneous input files and error insertions
|
||||
param_size.context = 1500
|
||||
param_size = 1500 % simultaneous macro parameters
|
||||
save_size.context = 5000
|
||||
save_size = 10000 % for saving values outside current group
|
||||
stack_size.context = 1500
|
||||
stack_size = 300 % simultaneous input sources
|
||||
|
||||
% These are Omega-specific.
|
||||
ocp_buf_size = 20000 % character buffers for ocp filters.
|
||||
ocp_stack_size = 10000 % stacks for ocp computations.
|
||||
ocp_list_size = 1000 % control for multiple ocps.
|
||||
|
||||
% These work best if they are the same as the I/O buffer size, but it
|
||||
% doesn't matter much. Must be a multiple of 8.
|
||||
dvi_buf_size = 16384 % TeX
|
||||
gf_buf_size = 16384 % MF
|
||||
|
||||
% It's probably inadvisable to change these. At any rate, we must have:
|
||||
% 45 < error_line < 255;
|
||||
% 30 < half_error_line < error_line - 15;
|
||||
% 60 <= max_print_line;
|
||||
% These apply to Metafont and MetaPost as well.
|
||||
error_line = 79
|
||||
half_error_line = 50
|
||||
max_print_line = 79
|
||||
|
||||
% Settings for Debian jadetex
|
||||
hash_extra.jadetex = 32500
|
||||
hash_extra.pdfjadetex = 32500
|
||||
pool_size.jadetex = 500000
|
||||
pool_size.pdfjadetex = 500000
|
||||
string_vacancies.jadetex = 45000
|
||||
string_vacancies.pdfjadetex = 45000
|
||||
max_strings.jadetex = 58500
|
||||
max_strings.pdfjadetex = 58500
|
||||
pool_free.jadetex = 47500
|
||||
pool_free.pdfjadetex = 47500
|
||||
nest_size.jadetex = 500
|
||||
nest_size.pdfjadetex = 500
|
||||
param_size.jadetex = 1500
|
||||
param_size.pdfjadetex = 1500
|
||||
save_size.jadetex = 5000
|
||||
save_size.pdfjadetex = 5000
|
||||
stack_size.jadetex = 1500
|
||||
stack_size.pdfjadetex = 1500
|
||||
extra_mem_bot.jadetex = 85000
|
||||
extra_mem_bot.pdfjadetex = 85000
|
||||
|
||||
98
docs/HACKING
98
docs/HACKING
|
|
@ -1,98 +0,0 @@
|
|||
UPDATING ONLINE DOCS
|
||||
--------------------
|
||||
This is pretty simple.
|
||||
Make sure that you
|
||||
a) have a working freedesktop.org account
|
||||
b) $HOME/.ssh/config set up so that it has the right User for the Host
|
||||
(for example, I have:
|
||||
Host freedesktop.org
|
||||
User thomasvs
|
||||
c) verify this works by doing ssh freedesktop.org and being logged in without
|
||||
a password prompt
|
||||
|
||||
Then, after updating any of the docs, run "make upload" from that directory.
|
||||
Or, run "make upload" from this (docs) directory.
|
||||
|
||||
DOCS NOTES
|
||||
----------
|
||||
|
||||
OK, I've grown so tired of having to coax the docs to build every time I
|
||||
get round to it that I've decided to note down some of the things that
|
||||
are important to know.
|
||||
|
||||
Here goes.
|
||||
|
||||
A) Our documentation should all be Docbook/XML. No SGML.
|
||||
B) The source for the documentation is:
|
||||
- one or more .xml files, with the main one being gstreamer-(whatever).xml
|
||||
- image files
|
||||
- in .fig
|
||||
- in .png (and maybe others)
|
||||
|
||||
C) We want to generate docs in HTML, PS and PDF
|
||||
D) We want to use xmlto to generate these
|
||||
|
||||
THINGS TO DO IN THE SOURCE XML
|
||||
------------------------------
|
||||
|
||||
|
||||
HOW TO HANDLE IMAGES
|
||||
--------------------
|
||||
* the format of images used is:
|
||||
- PNG for html
|
||||
- EPS for ps
|
||||
- PDF for pdf
|
||||
|
||||
* images may need to be converted from their source format to the end format
|
||||
|
||||
* a file called image.entities is generated that provides two entities:
|
||||
ℑ and &IMAGE;
|
||||
ℑ is the file extension (png, ps, pdf)
|
||||
* all generated images will be put in images/
|
||||
|
||||
HOW THE BUILD WORKS
|
||||
-------------------
|
||||
|
||||
1) HTML
|
||||
-------
|
||||
xmlto html gstreamer-whatever.xml should produce the html docs.
|
||||
We do this in the html subdir of the doc builddir.
|
||||
images are copied to (builddir)/html/images
|
||||
PNGS should be set to all of the png's referenced for html, both
|
||||
already there and auto-generated
|
||||
|
||||
2) PS
|
||||
-----
|
||||
images are converted to .ps files in EPS format. Generated images are
|
||||
put in images/
|
||||
xmlto ps gstreamer-whatever.xml generates the ps file
|
||||
|
||||
3) PDF
|
||||
------
|
||||
There are two ways:
|
||||
a) ps2pdf is the easiest
|
||||
b) we specify ps, PS as the image type, but using xmlto the build will fail
|
||||
because it uses ps2pdf internally and it fails to generate the images
|
||||
By hand-generating .pdf images before xmlto we can make the build succeed.
|
||||
(This is why image-pdf has file ext pdf but type EPS; this tricks xmlto in
|
||||
doing the right thing)
|
||||
xmlto pdf gstreamer-whatever.xml generates pdf (but seems to fail on the
|
||||
FAQ, so for now we use ps2pdf)
|
||||
|
||||
HOW WE SET UP OUR BUILD FOR THE DOCS
|
||||
------------------------------------
|
||||
make all should build html, ps, and pdf
|
||||
html is built in a subdir, with the png/ps images copied there
|
||||
ps and pdf are built in the current dir, in one file
|
||||
|
||||
|
||||
|
||||
|
||||
THINGS I'VE LEARNED
|
||||
-------------------
|
||||
a) for clean builddir != srcdir separation, I wanted to use xmlto --searchpath
|
||||
so the source xml could find the built entity file.
|
||||
But xmlto --searchpath is (right now) for TeX input, not xml input.
|
||||
xsltproc has a --path option (that xmlto doesn't use yet), but it
|
||||
resolves single files to $(specified_path)/$(srcdir)/$(file)
|
||||
For now, we need to hack around it by copying xml to the build dir.
|
||||
130
docs/README
130
docs/README
|
|
@ -1,13 +1,105 @@
|
|||
GTK-DOC stuff
|
||||
-------------
|
||||
GStreamer documentation notes
|
||||
|
||||
* starting files in CVS:
|
||||
IMPORTANT
|
||||
=========
|
||||
|
||||
Please make sure you've read and understood everything in this file
|
||||
before you try changing documentation.
|
||||
|
||||
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)
|
||||
|
||||
DOCBOOK NOTES
|
||||
=============
|
||||
|
||||
OK, I've grown so tired of having to coax the docs to build every time I
|
||||
get round to it that I've decided to note down some of the things that
|
||||
are important to know.
|
||||
|
||||
OVERVIEW
|
||||
--------
|
||||
* Our documentation should all be Docbook/XML. No SGML.
|
||||
* The source for the documentation is:
|
||||
- one or more .xml files, with the main one being gstreamer-(whatever).xml
|
||||
- image files
|
||||
- in .fig
|
||||
- in .png (and maybe others)
|
||||
* We want to generate docs in HTML, PS and PDF
|
||||
* We want to use xmlto to generate these
|
||||
|
||||
CONVENTIONS
|
||||
-----------
|
||||
We stick to some simple conventions for writing docbook documentation.
|
||||
* id names:
|
||||
- all id's start with chapter-, part-, section-, or misc-
|
||||
- verify this is the case by looking at the generated file names in html/
|
||||
- sections should also include the chapter name;
|
||||
for example in a chapter called chapter-example, a section would be
|
||||
called section-example-hello-world
|
||||
|
||||
HOW IMAGES ARE HANDLED
|
||||
----------------------
|
||||
* the format of images used is:
|
||||
- PNG for html
|
||||
- EPS for ps
|
||||
- PDF for pdf
|
||||
|
||||
* images may need to be converted from their source format to the end format
|
||||
|
||||
* a file called image.entities is generated that provides two entities:
|
||||
ℑ and &IMAGE;
|
||||
ℑ is the file extension (png, ps, pdf)
|
||||
* all generated images will be put in images/
|
||||
|
||||
HOW THE BUILD WORKS FOR EACH FORMAT
|
||||
-----------------------------------
|
||||
* HTML:
|
||||
- xmlto html gstreamer-whatever.xml should produce the html docs.
|
||||
- We do this in the html subdir of the doc builddir.
|
||||
- images are copied to (builddir)/html/images
|
||||
- PNGS should be set to all of the png's referenced for html, both
|
||||
already there and auto-generated
|
||||
|
||||
* PS :
|
||||
- images are converted to .ps files in EPS format. Generated images are
|
||||
put in images/
|
||||
- xmlto ps gstreamer-whatever.xml generates the ps file
|
||||
|
||||
* PDF :
|
||||
There are two ways:
|
||||
- ps2pdf is the easiest
|
||||
- we specify ps, PS as the image type, but using xmlto the build will fail
|
||||
because it uses ps2pdf internally and it fails to generate the images
|
||||
By hand-generating .pdf images before xmlto we can make the build succeed.
|
||||
(This is why image-pdf has file ext pdf but type EPS; this tricks xmlto in
|
||||
doing the right thing)
|
||||
xmlto pdf gstreamer-whatever.xml generates pdf (but seems to fail on the
|
||||
FAQ, so for now we use ps2pdf)
|
||||
|
||||
HOW THE BUILD SYSTEM IS SET UP
|
||||
------------------------------
|
||||
* make all should build html, ps, and pdf
|
||||
* html is built in a subdir, with the png/ps images copied there
|
||||
* ps and pdf are built in the current dir, in one file
|
||||
|
||||
|
||||
GTK-DOC NOTES
|
||||
=============
|
||||
|
||||
* files under CVS control:
|
||||
- Makefile.am
|
||||
- gstreamer-sections.txt, gstreamer.types.in, gstreamer-docs.sgml
|
||||
- tmpl/
|
||||
(FIXME: describe what each of these files do)
|
||||
|
||||
* what is done in the gst dir ?
|
||||
* checklist:
|
||||
- make sure -sections.txt has a <TITLE> set for each <FILE>
|
||||
|
||||
* what happens during a gtk-doc build ?
|
||||
- headers are scanned based on $(MODULE).types
|
||||
$(MODULE)-scan is created
|
||||
gtkdoc-scan is called with a sourcedir and a module name,
|
||||
|
|
@ -18,6 +110,32 @@ GTK-DOC stuff
|
|||
and .args, .hierarchy and .signals files are created
|
||||
gtkdoc-scan is called
|
||||
|
||||
(FIXME: why is there gstreamer.types.in and gst-plugins.types.in ?)
|
||||
|
||||
* TODO:
|
||||
why is there gstreamer.types.in and gst-plugins.types.in ?
|
||||
|
||||
WBSITE DOCUMENTATION
|
||||
====================
|
||||
|
||||
Updating the online documentation is pretty simple.
|
||||
Make sure that you
|
||||
a) have a working freedesktop.org account
|
||||
b) $HOME/.ssh/config set up so that it has the right User for the Host
|
||||
(for example, I have:
|
||||
Host freedesktop.org
|
||||
User thomasvs
|
||||
c) verify this works by doing ssh freedesktop.org and being logged in without
|
||||
a password prompt
|
||||
d) have verified your changes build documentation locally.
|
||||
|
||||
Then, after updating any of the docs, run "make upload" from that directory.
|
||||
Or, run "make upload" from this (docs) directory.
|
||||
|
||||
RANDOM THINGS I'VE LEARNED
|
||||
==========================
|
||||
|
||||
* for clean builddir != srcdir separation, I wanted to use xmlto --searchpath
|
||||
so the source xml could find the built entity file.
|
||||
But xmlto --searchpath is (right now) for TeX input, not xml input.
|
||||
xsltproc has a --path option (that xmlto doesn't use yet), but it
|
||||
resolves single files to $(specified_path)/$(srcdir)/$(file)
|
||||
For now, we need to hack around it by copying xml to the build dir.
|
||||
|
|
|
|||
|
|
@ -1,19 +0,0 @@
|
|||
OK, so Debian's passivetex and xmltex packages are sucking right now, I think.
|
||||
Here's what I had to do to get the PDF output to work properly.
|
||||
|
||||
# rm -rf /usr/share/texmf/tex/xmltex/contrib/passivetex
|
||||
# cd /usr/share/texmf/tex/latex
|
||||
# wget http://www.tei-c.org.uk/Software/passivetex/passivetex.zip
|
||||
# unzip passivetex.zip
|
||||
# rm passivetex.zip
|
||||
# cd /usr/share/texmf/tex/xmltex/base
|
||||
# wget http://www.tei-c.org.uk/Software/passivetex/xmltex.tex
|
||||
# mktexlsr
|
||||
# cd /var/lib/texmf/web2c
|
||||
# pdftex -ini "&pdflatex" pdfxmtex.ini
|
||||
# cp 95NonPath /etc/texmf/texmf.d
|
||||
# update-texmf
|
||||
|
||||
Sheesh. Don't ask how long that took to figure out.
|
||||
|
||||
-- Andy Wingo, 11 July 2002
|
||||
Loading…
Reference in a new issue