collect docs notes

Original commit message from CVS:
collect docs notes
This commit is contained in:
Thomas Vander Stichele 2004-01-28 15:37:33 +00:00
parent 420b49905b
commit d839d3c63c
5 changed files with 140 additions and 318 deletions

View file

@ -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> 2004-01-28 Ronald Bultje <rbultje@ronald.bitfreak.net>
* docs/pwg/advanced_tagging.xml: * docs/pwg/advanced_tagging.xml:

View file

@ -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

View file

@ -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:
&image; and &IMAGE;
&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.

View file

@ -1,23 +1,141 @@
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:
&image; and &IMAGE;
&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 - Makefile.am
- gstreamer-sections.txt, gstreamer.types.in, gstreamer-docs.sgml - gstreamer-sections.txt, gstreamer.types.in, gstreamer-docs.sgml
- tmpl/ - 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>
- headers are scanned based on $(MODULE).types * what happens during a gtk-doc build ?
$(MODULE)-scan is created - headers are scanned based on $(MODULE).types
gtkdoc-scan is called with a sourcedir and a module name, $(MODULE)-scan is created
where the module name is $(MODULE) gtkdoc-scan is called with a sourcedir and a module name,
$(MODULE)-sections.txt is created if it doesn't exist yet (it should), where the module name is $(MODULE)
as well as $(MODULE)-decl.txt and $(MODULE)-decl-list.txt $(MODULE)-sections.txt is created if it doesn't exist yet (it should),
as well as $(MODULE)-decl.txt and $(MODULE)-decl-list.txt
and .args, .hierarchy and .signals files are created and .args, .hierarchy and .signals files are created
gtkdoc-scan is called gtkdoc-scan is called
(FIXME: why is there gstreamer.types.in and gst-plugins.types.in ?)
* TODO: WBSITE DOCUMENTATION
why is there gstreamer.types.in and gst-plugins.types.in ? ====================
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.

View file

@ -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