+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:
+++ /dev/null
-% \f 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
-
-
-% \f 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
-
+++ /dev/null
-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.
-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>
-- headers are scanned based on $(MODULE).types
- $(MODULE)-scan is created
- gtkdoc-scan is called with a sourcedir and a module name,
- where the module name is $(MODULE)
- $(MODULE)-sections.txt is created if it doesn't exist yet (it should),
- as well as $(MODULE)-decl.txt and $(MODULE)-decl-list.txt
+* 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,
+ where the module name is $(MODULE)
+ $(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
- gtkdoc-scan is called
+ and .args, .hierarchy and .signals files are created
+ gtkdoc-scan is called
+
+ (FIXME: 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
+==========================
-* TODO:
- why is there gstreamer.types.in and gst-plugins.types.in ?
+* 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.
+++ /dev/null
-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
\ No newline at end of file
projects / platform / upstream / gstreamer.git / commitdiff