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
| |
ifplaintext | in-line | @ifplaintext ... @end ifplaintext
| |
ifplaintextblock | block | @ifplaintext ... @end ifplaintext
| |
ifxml | in-line | @ifxml ... @end ifxml
| |
ifxmlblock | block | @ifxml ... @end ifxml
| |
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
| |
ifnotplaintext | in-line | @ifnotplaintext ... @end ifnotplaintext
| |
ifnotplaintextblock | block | @ifnotplaintext ... @end ifnotplaintext
| |
ifnotxml | in-line | @ifnotxml ... @end ifnotxml
| |
ifnotxmlblock | block | @ifnotxml ... @end ifnotxml
| |
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
, ifplaintext
, ifxml
,
ifnotinfo
, ifnottex
, ifnothtml
,
ifnotplaintext
and ifnotxml
, are in-line
elements that contain in-line text. On the other side,
ifinfoblock
, iftexblock
,
ifhtmlblock
, ifplaintextblock
,
ifxmlblock
, ifnotinfoblock
,
ifnottexblock
, ifnothtmlblock
,
ifnotplaintextblock
and ifnotxmlblock
, 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
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
@if
typesetting, 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
@if
typesetting or
@ifnot
typesetting, and
@if
typesettingblock
or
@ifnot
typesettingblock
.
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.