yagdoc.docbook

Package yagdoc :: Module docbook

[show private | hide private]

Module yagdoc.docbook

Writing DocBook XML.

Classes
`Section`	One reference documentation section.

Exceptions
`DocBookException`	Base class for DocBook writer exceptions
`TooFewSignalArguments`	Signal documentation has less arguments than the signal
`TooManySignalArguments`	Signal documentation has more arguments than the signal

Function Summary
	`adapt_docbook_version(xmlfile)` Set DocBook version from DOCTYPE of a file.
	`column_widths(rows, n)` Calculate column widths.
	`dashize(name)` Convert underscores to dashes (for canonical signal and property names).
`str`.	`escape_entities(text)` Escape `&`, `<` and `>`.
`str`.	`escape_entities_smart(text)` Escape `&`, `<` and `>` if they do not look like part of XML.
	`expand(lines)`
	`expand_attribute(text)`
`str`	`expand_code(text)` Escape `<`, `>` amd `&` that do not look like XML in text and return it.
	`expand_constant(text)`
	`expand_function(text)`
`str`	`expand_nothing(text)` Perform no transform of text and return it.
	`expand_parameter(text)`
`str`	`expand_text(text)` Expand abbreviations, escape `<`, `>` amd `&` that do not look like XML in text and return it.
	`expand_type(text)`
	`join(lines)` Join a sequence of strings with spaces.
	`join_lines(lines)` Join a sequence of strings with newlines.
	`join_with_and(items)` Join a sequence of strings with commas, using `'and'` for the last two, as a human would do.
	`linkify(linktext, symbol)`
	`make_gtkdoc_sgml_id(name)` Change string to a valid case-insensitive SGML id.
	`make_sgml_id(name)` Change string to a valid case-insensitive SGML id.
	`update(dest, key, source, transforms, srckey)` Update an item in a dictionary from another dictionary, with possible transform.

Function Details

adapt_docbook_version(xmlfile)

Set DocBook version from DOCTYPE of a file.

Parameters:: xmlfile - A XML DocBook book file, normally the driver document.
(type=file or other iterable of str)

column_widths(rows, n=0)

Calculate column widths.

Parameters:: rows - Rows, each consisting of the same number of columns.
(type=sequence of sequence of str); n - Fallback number of columns. It is used to determined the returned length of zero-filled list if rows is empty.
(type=int)

dashize(name)

Convert underscores to dashes (for canonical signal and property names).

escape_entities(text)

Escape &, < and >.

Parameters:: text - Text to escape entities in.
(type=str.)

Returns:: Escaped text.
(type=str.)

escape_entities_smart(text)

Escape &, < and > if they do not look like part of XML.

Mimics gtk-doc behaviour if there is no compelling reason to do otherwise as it's just a bloody heuristics. We additionally recognize 〹 and <?processing instructions?> though.

FIXME: Describe properly what it does then.

Parameters:: text - Text to escape entities in.
(type=str.)

Returns:: Escaped text.
(type=str.)

expand_code(text)

Escape <, > amd & that do not look like XML in text and return it.

This expander is applied on code listings.

Parameters:: text - Text to expand.
(type=str)

Returns:: Expanded (XML-ized) text.
(type=str)

expand_nothing(text)

Perform no transform of text and return it.

This expander is applied on CDATA section content.

Parameters:: text - Text to expand.
(type=str)

Returns:: Expanded (XML-ized) text.
(type=str)

expand_text(text)

Expand abbreviations, escape <, > amd & that do not look like XML in text and return it.

This expander is applied on normal content.

Parameters:: text - Text to expand.
(type=str)

Returns:: Expanded (XML-ized) text.
(type=str)

join(lines)

Join a sequence of strings with spaces.

join_lines(lines)

Join a sequence of strings with newlines.

join_with_and(items)

Join a sequence of strings with commas, using 'and' for the last two, as a human would do.

make_gtkdoc_sgml_id(name)

Change string to a valid case-insensitive SGML id.

This function attempts to mimics the gtk-doc's one to obtain the same ids for the same symbols. Use it for external references.

make_sgml_id(name)

Change string to a valid case-insensitive SGML id.

This function assumes underscores are allowed and therefore avoids most of the transofmrs. SGML DocBook explicitly declares underscores and XML explicitly permits them.

update(dest, key, source, transforms=[], srckey=None)

Update an item in a dictionary from another dictionary, with possible transform.

Parameters:: dest - Dictionary to update.
(type=dict); key - Key in dest to update, also key in source to take value from if srckey is not given.
(type=hashable); source - Dictionary to take value from, if it is not present there, dest is not updated.
(type=dict); transforms - Sequence of transforms to apply on the value before putting it into dest. Transforms are expected to be single-parameter functions, retuning whatever the next transform can consume (or should end up in dest).
(type=list of callable); srckey - Key to use instead of key in source.
(type=hashable)

Generated by Epydoc 2.1 on Fri Oct 5 00:36:53 2007

http://epydoc.sf.net