Texinfo::Convert::TexinfoMarkup
*******************************

Texinfo::Convert::TexinfoMarkup NAME
====================================

Texinfo::Convert::TexinfoMarkup - Convert Texinfo tree to element and attribute markup

Texinfo::Convert::TexinfoMarkup SYNOPSIS
========================================

  package Texinfo::Convert::TexinfoMyMarkup;

  use Texinfo::Convert::TexinfoMarkup;

  @ISA = qw(Texinfo::Convert::TexinfoMarkup);

  sub converter_defaults ($$) {
    return %myconverter_defaults;
  }

  sub txi_markup_protect_text($$)
  {
    my $self = shift;
    ....
  }

Texinfo::Convert::TexinfoMarkup NOTES
=====================================

The Texinfo Perl module main purpose is to be used in texi2any to convert Texinfo to other formats.  There is no promise of API stability.

Texinfo::Convert::TexinfoMarkup DESCRIPTION
===========================================

Texinfo::Convert::TexinfoMarkup converts a Texinfo tree to the Texinfo Markup Language which is based on nested elements with attributes, similar to XML.  All the information present in the Texinfo tree, after expansion of @macro, @value and inclusion of include files is kept.  Texinfo::Convert::TexinfoMarkup is an abstract class, to be used as a super class for modules implementing specific markup formatting functions called by Texinfo::Convert::TexinfoMarkup.

The Texinfo Markup Language elements and attributes are not documented, but the Texinfo XML output by the Texinfo::Convert::TexinfoXML subclass (Texinfo::Convert::TexinfoXML) is a straightforward formatting as XML, and is described by the texinfo DTD.  Therefore the texinfo DTD can be used as a description of the structure of both Texinfo XML and of the more abstract Texinfo Markup Language.

Texinfo::Convert::TexinfoMarkup METHODS
=======================================

Markup formatting methods defined by subclasses
-----------------------------------------------

The following methods should be implemented by the modules inheriting from Texinfo::Convert::TexinfoMarkup:

$result = $converter->txi_markup_atom($atom)

     Format the $atom symbol string in a simpler way than with an element.  For example in XML the formatting of the symbol is achieved with an entity.

$result = $converter->txi_markup_comment($comment_string)

     Format $comment_string as a comment.

$result = $converter->txi_markup_convert_text($element)

     Called to format the Texinfo tree $element text, which is a reference on a hash.  The $element text is in the text key. The type key value may also be set to distinguish the type of text (Texinfo::Parser Types for text elements). Texinfo tree elements are described in details in Texinfo::Parser TEXINFO TREE.

$result = $converter->txi_markup_element($format_element, $attributes)

$result = $converter->txi_markup_open_element($format_element, $attributes)

$result = $converter->txi_markup_close_element($format_element, $attributes)

     txi_markup_element is called for the formatting of empty elements.  Otherwise, txi_markup_open_element is called when an element is opened, and txi_markup_close_element is called when an element is closed. $format_element is the element name, $attributes is a reference on an array containing references on arrays of pairs, one pair for each attribute, with the attribute name as the first item of the pair and the attribute text as the second item of the pair.

$result = $converter->txi_markup_header()

     Called to format a header at the beginning of output files.

$result = $converter->txi_markup_protect_text($string)

     Protect special character in text for text fragments out of text texinfo tree elements.  For example, for spaces at end of line that are ignorable in most output formats, for @set or @macro arguments.

Formatting state information
----------------------------

A method is available for subclasses to gather information on the formatting state:

$converter->in_monospace()

     Return 1 if in a context where spacing should be kept and --- or '' left as is, for example in @code, @example.

Texinfo::Convert::TexinfoMarkup AUTHOR
======================================

Patrice Dumas, <pertusus@free.fr>

Texinfo::Convert::TexinfoMarkup SEE ALSO
========================================

Texinfo::Convert::Converter. Texinfo::Convert::TexinfoXML.  The Texinfo::Convert::TexinfoSXML is another subclass, which outputs SXML.  It is not much documented.

Texinfo::Convert::TexinfoMarkup COPYRIGHT AND LICENSE
=====================================================

Copyright 2010- Free Software Foundation, Inc.  See the source file for all copyright years.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.