Embed in own Applications

Besides running degrotesque on the command line, you may as well embed degrotesque within your own applications. There are two ways to do this:

• Functional by calling the prettify function from the module;
• Using a Degrotesque instance and use it's prettify method.

When degrotesque shall be called only once, the first method is more convenient. The second should be used when processing multiple files of the same type.

Functional

Assuming you have a text snippet, just apply the prettify method on it:

import degrotesque
ugly_str = "Well - that's not what I had expected."
nice_str = degrotesque.prettify(ugly_str)

The function is defined as:

prettify(document, marker=None, actions=None, 
         replacement_format='text', to_skip=None)

with the following parameters:

• document: the original document;
• marker: Either a string that names which marker to use or the marker object to use; the following names are known:
  • ‘sgml’: used for processing XML/HTML documents;
  • ‘text’: used for processing plain text files;
  • ‘md’: used for processing Markdown documents;
  • ‘doxygen’: used for processing files documents using the Doxygen syntax;
  • ‘python’: used for processing Python files;
  • ‘rst’: used for processing restructuredText documents.
• replacement_format: How the inserted character shall be represented with:
  • ‘unicode’: uses numeric entities (e.g. ‘–’ for an ‘—’);
  • ‘html’: uses HTML entities (e.g. ‘—’ for an ‘—’);
  • ‘char’: uses plain (utf-8) characters (e.g. ‘—’ for an ‘—’).
• to_skip: a list of names of the elements that contents shall be skipped; works only when processing SGML/XML/HTML-documents; when None is given, the default elements to skip are used, see [Appendix C)[./appendixC.md).

prettify returns the converted document contents.

Using a Degrotesque object

When processing multiple documents the same way, using an instance with pre-set options should be faster. An basic example is:

import degrotesque
# build the degrotesque instance with default values
my_prettifyier = degrotesque.Degrotesque()
# apply degroteque
ugly_str = "Well - that's not what I had expected."
nice_str = my_prettifyier.prettify(ugly_str)

The default values can be replaced using some of the class' interfaces (methods):

# change the actions to apply (by naming them)
# here: apply french quotes and math symbols
degrotesque.setActions("quotes.french,math")
# change the elements which contents shall be skipped
# here: skip the contents of "code",
#  "script", and "style" elements
degrotesque.setToSkip("code,script,style")

Further information

You may consult the degrotesque pydoc code documentation.