[Groff] Re: Description of grohtml tags needed

[Gaius Mulley]

Werner LEMBERG <address@hidden> writes:

> > > it seems to me that it would be a good time right now to add a
> > > description of all grohtml tags to the man page.  Can you provide
> > > this?

Hi Werner, Larry and Dean,

here is a first stab at documenting the tags troff emits to
post-grohtml. It could do with more polishing and finishing (the
diversion section is empty). But I thought it better to push it out as
the previous sections might be useful for Larry and Dean?

I thought it might reside in groff/src/devices/grohtml/grohtml_tag.man
but thats only a suggestion and there might be a better location,
maybe..

Anyway here it is:

enjoy,
Gaius

------------- cut here ------------- cut here ------------- cut h//
'\" e
.\" The above line should force the use of eqn as a preprocessor
.ig
grohtml_tags.5

Last update: 8 December 2004

This file is part of groff, the GNU roff type-setting system.

Copyright (C) 2004 Free Software Foundation, Inc.
written by Gaius Mulley <address@hidden>

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being this .ig-section and AUTHORS, with no
Front-Cover Texts, and with no Back-Cover Texts.

A copy of the Free Documentation License is included as a file called
FDL in the main directory of the groff source package.
..
.
. ie '\*[.T]'ps' .ds Ellipsis \[u2026]
. el .ds Ellipsis .\|.\|.\&\"
.
.\" --------------------------------------------------------------------
.\" Title
.\" --------------------------------------------------------------------
.
.mso www.tmac
.
.TH TROFF_TAGS @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
.
.SH NAME
troff_tags \- troff tags and their meaning
.
.\" --------------------------------------------------------------------
.SH DESCRIPTION
.\" --------------------------------------------------------------------
.
This manual page describes the formatting tags generated by GNU
.BR troff (@MAN7EXT@) .
These tags are currently only used by grohtml but they could be used
by future devices which require translation of formatting commands
rather than absolute glyph positioning on a piece of paper.  For
example they would be suitable for a future, -Tdoc, device which
translates troff source into an OpenOffice format.
.
.\" --------------------------------------------------------------------
.SH "TROFF TAG REQUESTS"
.\" --------------------------------------------------------------------
.
Troff has the ability to issue formatting tags inside the ditroff
output. Normally users would not need to know about these requests and
they are preliminary designed to allow macro sets authors to improve
their behaviour with
.BR grohtml .
.P
There are four different kinds of tag requests which troff can
accept:
.
.ULS
.LI
.BR .tag
.I foo
this emits
.I foo
as a special. It inserts a space between the previous glyph and
.IR foo .
[Note that this is currently under construction. Actually the groff cvs
source uses \fC.nop \e&\eX^html:\e\e$*^\fP].
.FE
.
.LI
.BR .tag1
.I foo
this emits
.I foo
as a special without a preceding or trailing space.
[Again this is under construction - the cvs source uses
\fC.tag "html:\e\e$*\fP].
.
.LI
.BR .tag2
.I foo
this emits a tag which indicates that firstly the current paragraph
must be finished and secondly that a tag
.I foo
should be emitted.
[Again this is under construction - the cvs source uses
\fC.nop \e&\eX^html</p>:\e\e$*^\fP].
.FE
.
.LI
.BR .taga
.I foo
emits the tag
.I foo
when the troff tag state next changes. See the section on troff tag state.
.ULE
.
.\" --------------------------------------------------------------------
.SH "TROFF TAG STATE"
.\" --------------------------------------------------------------------
.
This section describes the troff tag state. In essence the troff tag
state is a subset of the troff state machine, but enough of the state
machine to accurately represent basic formatting issues. For example,
indentation, line centering, no fill, spaces, and line breaks.
.
.P
The troff tag state consists of the following boolean entities which
maybe set during the processing of
.BR troff
requests or input text.
.ULS
.LI
.BR eol
is set whenever the end of a source input line is seen.
.LI
.BR br
is set whenever a
.BR troff
request causes a line break to occur in the output text.
.ULE
.P
The troff tag state also consists of the following integer
valued entities:
.ULS
.LI
.B fi
contains a value 0 for no fill and 1 for fill on.
.LI
.B rj
contains a value indicating how many lines should be right adjusted.
Currently not used by
.BR grohtml .
.LI
.B ce
contains an integer determining the number of input lines which should
be centered.
.ULE
.P
and it also includes the following unit based entities:
.ULS
.LI
.B in
the current indentation.
.LI
.B ll
the current line length.
.LI
.B po
the current page offset.
.LI
.B ti
the current temporary indent.
.ULE
.P
The
.B .ta
.I s
tag is also emitted whenever the value of the tabs changes. This tag
uses a string argument which is a list of all tab positions up until
the end of the line length.
.P
These values are recorded inside the program
.B troff 
and whenever the state changes a tag is emitted to the ditroff output.
.
.\" --------------------------------------------------------------------
.SH "DEVICE DRIVER TAGS"
.\" --------------------------------------------------------------------
.
This section describes the tags which are emitted to inform the
device driver about the meaning of following text.
The following tags are emitted when
.B troff
processes macro set definitions:
.ULS
.LI
.B .SH
.I n
indicates that all the text up to the next
.B .eo.h
tag forms a section heading.
The value of
.I n
describes the section level. Section level 1 is the outer most level.
.LI
.B .NH
.I n
indicates that all the text up to the next
.B .eo.h
tag forms a section heading.
The value of
.I n
describes the section level. Section level 1 is the outer most level.
There is no difference between the
.B .SH
and
.B .NH 
tags.
.LI
.B .eo.h
marks the end of a section heading.
.LI
.B .tl
indicates that the text for a title follows this tag.
.LI
.B .eo.tl
marks the end of a title.
.LI
.B ".mc"
currently unimplemented.
.LI
.B ".col"
.I n
determines which column this text should be placed into. Macro authors
should use values of
.I n
starting at 1.
The device driver will then create a transparent table and place the
associated text in the appropriate column.
Within
.B grohtml
indentation is handled in a similar way and is internally mapped into
column 0.  A transparent table is terminated either:
.ULS
.LI
when a glyph spans across a column boundary.
.LI
when a
.B .ce
tag is seen.
.LI
whenever the tab positions are redeclared and they are incompatible
with the column positions.
.ULE
.ULE
.P
During the processing of titles and section headings the following tags
are honoured by
.BR grohtml :
.IR in ,
.IR ti ,
.IR po ,
.IR ce ,
.IR ll ,
.IR fi .
.
.\" --------------------------------------------------------------------
.SH "TAG ORDER"
.\" --------------------------------------------------------------------
.
This section documents the ordering of emitted tags. Whenever the troff
state is altered
.B troff
remembers the state changes and when a glyph is about to be written to
the ditroff output the state changes are flushed. Of course if a number
of state variables have changed in-between the last glyph and the current
glyph then troff will emit a sequence of tags. This section documents
the ordering:
.ULS
.LI
fi
.LI
rj
.LI
sp
.LI
in
.LI
ll
.LI
po
.LI
ta
.LI
ti
.LI
ce
.LI
eol
.LI
br
.LI
any
.B .tag
values encountered when processing macro sets.
.ULE
.
.\" --------------------------------------------------------------------
.SH "BEHAVIOUR OF TAGS WITHIN DIVERSIONS"
.\" --------------------------------------------------------------------
.
Still to do \*[Ellipsis]