summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex3/xor/xo-README.txt
blob: 26135c36ebd077a4e8442f8473854cffb1b15435 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
%
% $Id: xo-README.txt,v 1.1 2000/08/11 07:04:34 latex3 Exp $
%
%

INTRODUCTION
============

This directory contains the first prototype implementation of the new
output routine (OR) for LaTeX2e*.

It is not a finished product, thus it is very likely that using it
will result in errors or problems.

Especially error recovery is more or less nil, eg, there  are a lot of
places which simply say \ErrorFooBar (which is undefined). So if this
happens to you, you might have to search in the code to see why this
is supposed to be a user error.

Nevertheless, I hope that playing around with it will give you some
idea about how the finished OR might look like and what it will be
able to do.

Suggestions, comments, ... are welcome, especially on the already
available functionality or on missing functionality.

enjoy
Frank

August 2000





INSTALLATION
============

This set of packages builds on the basic packages

 templates.sty
 ldcsetup.sty
 xparse.sty

so you need to pick those up from the project web site as well.

To unpack the distribution use one of the three distributed .ins
files:

 xo.ins		% unpacks without any tracing code whatsoever
 xoprogress.ins % unpacks with progress information code (recommended)
 xotrace.ins    % unpacks with tracing code (for those who like to see
                % what the algorithm really does)


DOCUMENTATION
=============

The sequence

 pdflatex xoutput.drv
 makeindex -s gind.ist xoutput
 pdflatex xoutput.drv

will produce a pdf file of roughly 150 pages with the (somewhat)
documented code --- there is still a lot to do there.

To produce some overview article on the OR run

 latex xo-pfloat

three times.

There will be a question asked which you can answer with either

 0    % run with normal latex
 1    % run using the new OR


There is also a sample file for you to play with:

 xo-sample.tex

but is is more or less a template file.

There is also the file I used for the examples for my talk at Oxford:

 oxford-trial.tex

This file asks for a "trial" number:

 0-8 shows how the algorithm adds float after float to the page
 9   same as 8 but uses grid layout
 10  manual float control using an .fpc file



IMPLEMENTED FEATURES
====================

Plenty I hope, for important ones see xo-pfloat and of course the
documented code :-)


MISSING FEATURES
================

Plenty I fear. Here are a few important ones.

 - Interface for specifying spanning floats is missing

 - Interface for specifying which areas are allowed for a float

 - Interface for specifying the look and setup of a float page

 - Most of the page layout things like folio, running headers, etc

 - More float placement control (what is wanted, needed)

 - Balancing of columns, what are the appropriate concepts with
   respect to floats?

 - page style concepts: how are page styles changed, how are they
   specified?



KNOWN BUGS
==========

Plenty I fear. Here are a few important ones.

 - There are many footnotes in the code that say CHECK! or FIX! or
   ... they are all places where further work is most likely
   necessary, or known bugs are already documented.

 - Because of the unfinished work in xo-final/xo-new there are two
   hardwired lists \bot@areas and \top@areas. Top areas are mounted
   first on the page, thus entries for list of figures etc, will be
   sort of strangely ordered :-)

 - If a special penalty such as the flush point penalty ends up at the
   top of a column any glue after it isn't properly removed. This
   needs fixing and while the way to proceed is clear it is not yet
   implemented.

 - If we have to relax the float placement conditions due to a flush
   point the current code reverts to tight conditions the moment the
   last affected float has been placed (the idea was to ensure that we
   don't place too many floats on such a page since the relaxed
   conditions do not have a restriction there). But the problem with
   that approach is that in fact in most cases this will result in no
   further floats being allowed at all since typically the already
   placed floats make any further trials fail now. So this needs some
   change, eg only to check columns after the flush point with the
   tight conditions or ... for the moment it has only be partially
   resolved by enabling basically only the restrictions on number of
   floats per column or space available in columns (which are only
   checked for areas under trial)

 - If the design allows strange placements in various areas, then ".lot"
   files etc will as a result always be ordered strangely. There is
   not much you can do about that on this stage (even if the above
   problem is fixed) other than ensuring that at some later stage such
   files get sorted automatically.

 - Float pages are at best strange. what are good concepts to
   construct them in multi-column layouts? Are there any?

 - Size of a here float is not properly calculated when it get
   initialized

 - Grid layout requires that \topskip=\baselineskip (or so it seems
   --- it shouldn't but there is somewhere a bug lurking)

 - Definition of grid layout point commands need one more indirection
   to allow turning them off for a single page setup. Right now, the
   moment they are disabled they are gone.

 - Initialization of the various data structures is not yet properly
   done --- this needs further sorting out. As a result it is likely
   that some setups run into undefined variables.

 - If \readfloatplacements is used (ie float are manually placed) then
   the positioning of the float areas is done incorrectly because I
   forgot to add the necessary code to that part of the processing
   (just found out while finishing the examples for the Oxford talk)


FOUND A BUG?
============

If you think you have found a real bug (not just something that is
simply not yet implemented) I would be glad if you report it using

 latex latexbug

from the standard LaTeX distribution and select option 

 7) expl3:    Experimental packages for TeX programmers. (expl3)

or alternatively by discussing it on LATEX-L (see below)



DISCUSSION OF FEATURES (MISSING OR ELSE)
========================================

Discussion of features, either those implemented or those missing
should be directed to the discussion list

 LATEX-L

so that others can participate in the discussion. You can subscribe to
this list by sending a mail with the line

 SUBSCRIBE LATEX-L Your Name

to listserv@URZ.UNI-HEIDELBERG.DE