groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Groff] Re: tag tidying up..


From: Werner LEMBERG
Subject: [Groff] Re: tag tidying up..
Date: Thu, 16 Dec 2004 14:59:58 +0100 (CET)

> here is a patch which (tidies up some of the tag handling - or at
> least removes some of the ugliness :-).

Applied, thanks!

>  *  documentation in groff/src/devices/grohtml/grohtml_tags.man
>     to correct with the code. Still not finished behaviour within
>     diversions though.

Since I want to merge this with another man page, I haven't added it
to the CVS repository yet.  Attached is a new, revised version which
uses standard man macros.

Please format it with -Thtml, then look at the section `TROFF TAG
STATE'.  As can be seen, after the second .TP item the spacing is
increased unpleasantly (look at the `ce' label) ...

Additionally, before the first .TP in a series of .TP macros a blank
line is missing (as can be seen in the same section with the `eol'
entry).  This is especially important for man pages because .TP
doesn't use indentation for the label.

>  *  categorised the `.HTML', `.HTML-NS' and `.HTML</p> macros in
>     groff/src/devices/grohtml/grohtml_tags.man as grohtml pseudo tag
>     requests. They are all HTML specific and deal with different ways
>     of emitting raw HTML commands so I think it makes sense to
>     leave them as implemented by a special.

Sorry for being dumb again -- why do we need to have .HTML and
.HTML-NS?  Isn't .HTML-NS sufficient?  Looking at the code, .HTML is
simply `\&<tag>\&', and I wonder why this can't be simply `<tag>'...

Apparently I'm missing something.


    Werner
'\" e
.\" The above line should force the use of eqn as a preprocessor
.ig
grohtml_tags.5

Last update: 15 Dec 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 .\|.\|.\&\"
.
.
.de TQ
.  br
.  ns
.  TP \\$1
..
.
.
.\" --------------------------------------------------------------------
.\" 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 (@MAN1EXT@).
These tags are currently only used by
.BR grohtml (@MAN1EXT@)
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 \fC-Tdoc\fP device which
translates troff source into an OpenOffice format.
.
.\" --------------------------------------------------------------------
.SH "TROFF TAG REQUESTS"
.\" --------------------------------------------------------------------
.
GNU
.B 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 primarily designed to allow macro sets authors to improve
their behaviour with
.BR grohtml .
Nevertheless these tag requests are device independent and result
in tags being issued to the device driver.
However, currently only
.B grohtml
uses them.
.
.PP
There are two different kinds of tag requests which
.B troff
can accept:
.
.TP
.BI .tag\  foo
This emits
.I foo
as a special without a trailing space.
It is equivalent to:
.
.RS
.IP
\fC.nop \eX^\e\edevtag:\fIfoo\fC^\ec\fR
.RE
.
.IP
So for example:
.
.RS
.IP
.nf
.ft C
a
\&.tag b
c
.ft P
.fi
.RE
.
.IP
produces the following ditroff output:
.
.RS
.IP
.nf
.ft C
ta
wh24
x X devtag:b
tc
.ft P
.fi
.RE
.
.TP
.BI .taga\  foo
Emit the tag
.I foo
when the troff tag state next changes.
See the section
.BR "TROFF TAG STATE" .
So for example:
.
.RS
.IP
.nf
.ft C
a
\&.taga b
\&.sp
c
.ft P
.fi
.RE
.
.IP
produces the following ditroff output:
.
.RS
.IP
.nf
.ft C
ta
wh24
n40 0
V320
H0
x X devtag:.sp 1
x X devtag:.br
x X b
V320
H0
tc
.ft P
.fi
.RE
.
.
.\" --------------------------------------------------------------------
.SH "GROHTML SPECIFIC PSEUDO TAG REQUESTS"
.\" --------------------------------------------------------------------
.
This section documents the pseudo tag requests which are specific
to
.BR grohtml .
These tags only result in specials appearing in
.BR troff 's
ditroff output provided the
.B -Thtml
switch was issued to
.BR troff .
The macro definitions which map onto specials inside
.B www.tmac
are:
.
.TP
.BI HTML\  tagname
Emit an HTML
.IR tagname .
So for example:
.
.RS
.IP
.nf
.ft C
a
\&.HTML b
c
.ft P
.fi
.RE
.
.IP
yields the following ditroff output:
.
.RS
.IP
.nf
.ft C
ta
wh24
x X html:b
wh24
tc
.ft P
.fi
.RE
.
.TP
.BI HTML-NS\  tagname
Emit a tagname without a trailing space.
For example:
.
.RS
.IP
.nf
.ft C
a
\&.HTML-NS b
c
.ft P
.fi
.RE
.
.IP
yields the following ditroff output:
.
.RS
.IP
.nf
.ft C
ta
wh24
x X html:b
tc
.ft P
.fi
.RE
.
.TP
.BI HTML</p>\  tagname
Emit an HTML
.I tagname
after shutting down a (possibly open) paragraph.
.
.
.\" --------------------------------------------------------------------
.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.
.
.PP
The troff tag state consists of the following boolean entities which
maybe set during the processing of
.B troff
requests or input text.
.
.TP
.B eol
Set whenever the end of a source input line is seen.
.
.TP
.B br
Set whenever a
.B troff
request causes a line break to occur in the output text.
.
.PP
The troff tag state also consists of the following integer
valued entities:
.
.TP
.B fi
0 for no fill and 1 for fill on.
.
.TP
.B rj
The number of lines which should be right adjusted.
Currently not used by
.BR grohtml .
.
.TP
.B ce
The number of lines which should be centered.
.
.PP
and it also includes the following unit based entities:
.
.TP
.B in
The current indentation.
.
.TP
.B ll
The current line length.
.
.TP
.B po
The current page offset.
.
.TP
.B ti
The current temporary indentation.
.
.PP
The
.BI .ta\  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.
.
.PP
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 section documents the tag literals, however it is advised
that macro set programmers examine \fCdevtag.tmac\fP for macro
definitions which can be used to generate these literals
at the appropriate time.
.
.PP
The following tags are emitted when
.B troff
processes macro set definitions:
.
.TP
.BI .SH\  n
.TQ
.BI .NH\  n
Indicate that all the text up to the next
.B .eo.h
tag forms a section heading.
The value of\~\c
.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.
.
.TP
.B .eo.h
Mark the end of a section heading.
.
.TP
.B .tl
Indicate that the text for a title follows this tag.
.
.TP
.B .eo.tl
Mark the end of a title.
.
.TP
.B .mc
Currently unimplemented.
.
.TP
.BI .col\  n
Determine which column this text should be placed into.
Macro authors should use values of\~\c
.I n
starting at\~1.
The device driver then creates a transparent table and places 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:
.
.RS
.IP \[bu]
when a glyph spans across a column boundary.
.
.IP \[bu]
when a
.B .ce
tag is seen.
.
.IP \[bu]
whenever the tab positions are redeclared and they are incompatible
with the column positions.
.RE
.
.
.PP
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:
.
.RS
.PP
.nf
fi
rj
sp
in
ll
po
ta
ti
ce
eol
br
.fi
any
.B .tag
values encountered when processing macro sets.
.RE
.
.
.\" --------------------------------------------------------------------
.SH "BEHAVIOUR OF TAGS WITHIN DIVERSIONS"
.\" --------------------------------------------------------------------
.
Still to do \*[Ellipsis]

reply via email to

[Prev in Thread] Current Thread [Next in Thread]