Node:chap 10, Next:, Previous:chap 9, Up:Top


Conditional and literal back-end code

Texinfo has a special handling capability to select code depending on the final typesetting. Things like these can be done with SGML using marked sections, but it is not exactly the same thing. Sgmltexi includes some special elements to implement the conditional code insertion used inside Texinfo, and allow to insert also some peace of literal code.

Element Attribute Content Description or Texinfo equivalence
ifinfo in-line @ifinfo ... @end ifinfo
ifinfoblock block @ifinfo ... @end ifinfo
iftex in-line @iftex ... @end iftex
iftexblock block @iftex ... @end iftex
ifhtml in-line @ifhtml ... @end ifhtml
ifhtmlblock block @ifhtml ... @end ifhtml
ifnotinfo in-line @ifnotinfo ... @end ifnotinfo
ifnotinfoblock block @ifnotinfo ... @end ifnotinfo
ifnottex in-line @ifnottex ... @end ifnottex
ifnottexblock block @ifnottex ... @end ifnottex
ifnothtml in-line @ifnothtml ... @end ifnothtml
ifnothtmlblock block @ifnothtml ... @end ifnothtml
tex parsed character data @tex ... @end tex
html parsed character data @html ... @end html
texinfo parsed character data Raw Texinfo code.

Please note that ifinfo, iftex, ifhtml, ifnotinfo, ifnottex and ifnothtml, are in-line elements that contain in-line text. On the other side, ifinfoblock, iftexblock, ifhtmlblock, ifnotinfoblock, ifnottexblock and ifnothtmlblock, are block elements that contain block text.

The distinction between if... and if...block is necessary to avoid trouble with the SGML document type declaration.

The in-line elements tex, html and texinfo, are made to contain in-line literal text, usually enclosed inside <![CDATA[ and ]]>.

The element texinfo has no equivalence inside Texinfo, as it represent just raw Texinfo code. See the following example: 

<p>The letter <texinfo>@ubaraccent{o}</texinfo> is a special...</p>

It may be necessary to force literal reading, as for SGML. In this case, the element content can be enclosed like this: 

<p>The letter <texinfo><![CDATA[@ubaraccent{o}]]></texinfo> is a...

The example doesn't show any real reason to put the text inside a CDATA environment, but there are other situations where it will be necessary.

It follows another example on the use of literal back-end code. The intention is to show a simple mathematical expression: 123 + 10^(-1). 

    <p><tex><![CDATA[$123+10^{-1}$]]></tex>
    <html><![CDATA[123+10<sup>-1</sup>]]></html>
    <ifinfo>123+10^-1</ifinfo>
    = 12.3</p>

As current typesetting is made for HTML the result is as it follows:

123+10-1 = 12.3

Troubles

Texinfo, like TeX and *roff, distinguishes blocks because these are separated from one or more lines. This way, the distinction between blocks and in-lines is only a matter of vertical space. For example, the following peace of Texinfo source shows three environments @iftypesetting, which are part of the same block of text (the same paragraph). That is: in-line. 

Current typesetting is
@iftex
TeX
@end iftex
@ifhtml
HTML
@end ifhtml
@ifinfo
Info
@end ifinfo
and you can see that...

But in a different situation, these environments can became isolated block of text, like this: 

Current typesetting is:

@iftex
TeX
@end iftex

@ifhtml
HTML
@end ifhtml

@ifinfo
Info
@end ifinfo

You can see that...

With SGML this is not desirable, and difficult to implement. This is the reason why Sgmltexi distinguishes from @iftypesetting or @ifnottypesetting, and @iftypesettingblock or @ifnottypesettingblock.

Sgmltexi try to preserve line breaks inside the SGML source, but in this case, there is a consequence on the use of such conditional in-line environments. This happens because Texinfo requires these commands to lay alone on a single line. That is, if we would like to write something like this: 

<p>Current typesetting
is <iftex>TeX</iftex><ifhtml>HTML</ifhtml><ifinfo>Info</ifinfo>, so
you know what I mean.</p>

we expect that opening and closing tags will introduce proper line breaks. But if it were so, the result would be the following, transforming original in-line into undesired final block: 

Current typesetting is
@iftex
TeX
@end iftex

@ifhtml
HTML
@end ifhtml

@ifinfo
Info
@end ifinfo
, so you know what I mean.

To resolve this problem, these in-line conditional tags don't introduce any initial and final line break: it is up to the author to think about this problem. This way, Sgmltexi must be used in the following way, considering that there is no way to put the comma after the typesetting name: 

<p>Current typesetting is
<iftex>TeX</iftex>
<ifhtml>HTML</ifhtml>
<ifinfo>Info</ifinfo>
so you know what I mean.</p>

The same problem happens with tex and html elements, but in this case there is no need to distinguish the content, that is meant to be always in-line. 

<p>
<tex>
$$ \chi^2 = \sum_{i=1}^N
          \left (y_i - (a + b x_i)
          \over \sigma_i\right)^2 $$
</tex>
</p>

When using SGML, inserting literal back-end code is just a last resort that breaks standardization. In other words, if it is necessary to use such expedient, maybe the SGML is the wrong choice for writing documentation.