From d839d3c63c47bc32d878d6f4c41ba1f4982243a7 Mon Sep 17 00:00:00 2001 From: Thomas Vander Stichele Date: Wed, 28 Jan 2004 15:37:33 +0000 Subject: [PATCH] collect docs notes Original commit message from CVS: collect docs notes --- ChangeLog | 8 ++ docs/95NonPath | 187 --------------------------------------- docs/HACKING | 98 -------------------- docs/README | 146 +++++++++++++++++++++++++++--- docs/building-the-docs-on-debian | 19 ---- 5 files changed, 140 insertions(+), 318 deletions(-) delete mode 100644 docs/95NonPath delete mode 100644 docs/HACKING delete mode 100644 docs/building-the-docs-on-debian diff --git a/ChangeLog b/ChangeLog index b8d7d1a..66f03e4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2004-01-28 Thomas Vander Stichele + + * docs/95NonPath: + * docs/HACKING: + * docs/README: + * docs/building-the-docs-on-debian: + collect relevant bits of doc info + 2004-01-28 Ronald Bultje * docs/pwg/advanced_tagging.xml: diff --git a/docs/95NonPath b/docs/95NonPath deleted file mode 100644 index 19d9ce1..0000000 --- a/docs/95NonPath +++ /dev/null @@ -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 - diff --git a/docs/HACKING b/docs/HACKING deleted file mode 100644 index 7a6bf5d..0000000 --- a/docs/HACKING +++ /dev/null @@ -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. diff --git a/docs/README b/docs/README index e7f008d..7b6e5dc 100644 --- a/docs/README +++ b/docs/README @@ -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: + ℑ 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 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. diff --git a/docs/building-the-docs-on-debian b/docs/building-the-docs-on-debian deleted file mode 100644 index 288f3cd..0000000 --- a/docs/building-the-docs-on-debian +++ /dev/null @@ -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 \ No newline at end of file -- 2.7.4