response to Joerg Jung's posting

[Jeff Kingston]

Dear Lout listers,

About two months ago, Joerg Jung posted a long list of issues he
came across while writing his PhD thesis in Lout.  I promised to
look into them when I prepared the next release.  I'm preparing
it now, so here is his list with my responses.

At several points where the request is for a new option, I have
responded "Where does it stop?", meaning "This is reasonable and
implementable, but where do we stop with more and more options?".
As I've said before, the answer seems to be for the system to go
part-way to meet its users, and for the users to go part-way to
meet the system.  One person's must-have option is often something
that no-one else cares about.  And adding it is not entirely free;
everyone has to read about it while looking up other options.  The
packages already have many options; we have to stop somewhere.

Jeff Kingston


> @DP and the Option @DisplayGap are really 'overloaded' and used
> in too many places. @DP should especially not used be between
> captions and Figures/Table/Floaters. I think this was already
> mentioned somewhere in the mailing lists archive.

I agree, and if I could go back in time I would work harder on this,
but at this late stage, fixing it is too hard, owing to the messiness
and fragility of the implementation.  Actually it's easy to fix on a
subset of kinds of figures (one-page figures for example), but not on
all kinds of figures.  This is why I have not incorporated the patch
for this from Mark Summerfield.

> When setting @ChapterStartPages { Even } and using the colophon, the
> colophon seems to be broken.

The problem Joerg discovered is that everything comes out but the
Colophon heading is on the second page of the colophon rather than
the first.  I looked at this and decided that fixing it properly
was too hard.  The implementation is very fragile in this area,
and I don't want to change it in case something else breaks.  I've
documented the problem and a workaround:  if it happens, start off
the body of the colophon with @NP.

> @Place does not work from heading definitions in book template 
> (not yet defined/wrong context): Workaround: copy&paste own @Place
> into included 'mydefs'.

Fixed for next release, by moving @Place to the start of file bsf.

> @Place + Landscape does not do what (I) expected (things are kept
> instead of rotated). I guess this is because, @Place is a Lout
> primitive operating on a lower (Postscript) level? This should
> at least be documented or mentioned somewhere.

There is no prospect of coordinating @Place with Landscape, so I've
documented this in the description of @Place in the User's Guide.

> Defintion/Claim/Example/Proposition TitleFormat seems not to be
> used (with book).

That was a bug, now fixed for next release.

> Graph dashlength option(s) seem to be ignored (nothing visible
happens).

I've just done a test and it works for me.  The dashes do not pass
through data points, they start afresh at each data point, so if your
data points are closer together than dashlength, dashlength will have
no effect.  Post an example if you are still having problems with this.

> Diag link pathwidth set to thick + shadowbox + paint will result in
> links crossing inside into the boxes. Suggested fix: move the Links
> 'below' the boxes or do really end on the box border.

Too hard to fix at this late stage.  Boxes are not necessarily painted,
so moving the links to below them won't always fix the problem, even if
it was feasible to move them.

> @Python misses """ comments """, a short look into the code suggests,
> that this is probably simple to fix. 

I rely on the users of these languages to maintain them.  If anyone
wants to post a fix, I'll take it on.

> Overheads: @Lectures @RunningTitle seems to be ignored 

The default values of options @RunningOddTop and @RunningEvenTop in
file slides invoke @MajorTitle but not @MinorTitle.  At the end of
Section 3.4 of the User's Guide, you'll see that the @RunningTitle
option of @Lecture becomes the @MinorTitle of the running header.
So if you want it in your running headers, you need to change
@RunningOddTop and @RunningEvenTop so that they invoke @MinorTitle.

The underlying issue here is that in books there are two places to
print running titles:  at the top of each left-hand page, and at
the top of each right-hand page.  Overheads have only one place.

> Overheads: with @Lectures the default @OverheadNumInDisplays { No }
> seems not to be applied.  

That was a bug, now fixed for next release (thanks Uwe).

> Abbreviations Chapter should really be part of Introduction (resulting
> in Roman Numbers instead of Arabic with the default settings).

I probably agree, but @Abbreviations is part of the issue of what
prefatory sections (Preface, etc.) books ought to have.  Everyone,
notably Mark Summerfield, seems to have their own favourite list.
So this is something to sort out along with that larger issue.

> Captions in Figure/Table/Floater are not left justify-able as centered
> with |0.5rt by default. Workaround: @FigureCaptionFormat { @HExpand ...

Where does it stop?

> Overheads: Content/References title should not be centered by default,
> this makes it impossible to have a Left-Aligned Layout. Workaround:
> ContentWord { @HExpand Outline })

Where does it stop?

> Overheads: I think A4 portrait as default is not very useful.  Something
> like B5 or letter combined with landscape is way better for beamer
> presentations.

When the slides document type was defined, overhead transparencies
were pieces of plastic and A4 Portrait was a reasonable default
value.  I don't want to break old documents by changing it now.

> User Guide: orragged vs outdent example -- no visible difference in the 
> example?

Just chance.

> User Guide: @Overheads, @RunningTitle option as showed in Examples
> is useless, as ignored anyways.

Discussed above.

> List of Figures, List of Tables, List of Floaters: an InContents { no }
> option is missing.

The main table of contents contains a miscellany of things:  chapters,
sections, appendices, etc.  There is a @MakeContents option saying
whether to have a table of contents at all, and for each kind of thing
that goes in it there is an InContents option saying whether things of
that kind are wanted in it.  There is no option for saying whether an
individual chapter or section etc. should go into it.

But the list of figures contains only figures, the list of tables
contains only tables, and so on.  So once you have said (using
@MakeFigureContents) that you want a table of figures, there is
no point in having an InContents option to say whether you want
figures to go in that table of contents.  If you set such an
option to No, the table of figures would be empty and pointless.

> With @ChapterStartPages { Even } it would be nice to override this
> option, especially for Preface to avoid empty pages. Workaround: I
> moved content from preface to @AfterTitlePage.

Where does it stop?

> There is no VERTICAL RULE, why??? I implemented my own based on some list
> archive suggestions:
> import @BasicSetup
> def @TVLine { @TGray { "0 0 moveto 0 ysize lineto stroke" @Graphic {} } }

I refrained from defining a vertical rule symbol because the amount of
vertical space to occupy is not always clear.  You can see the issues
by pondering the difference between @LocalWidthRule and @FullWidthRule.
I suppose a @LocalHeightRule would be harmless, but the way Lout works
you can't define a @FullHeightRule, because in most contexts it would
be infinitely long.

> No abbreviation macros :( I ended up in implementing my own poor man macro:
> import @BasicSetup
> def @TAc right a { a @CrossLink { @S a } }
> And later using it like this: @TAc AAD in the Text, with a List in the
> Appendix:
> @VeryWideTaggedList
> @TagItem { @S AAD @PageMark AAD } { Average Absolute Deviation }
> @EndList

Nothing wrong with implementing your own defs.  They are the best
way to get something closely tailored to what you want.  In this
case, you seem to be doing something like the @Glossary symbols do.

> No (auto) @Sym carriagereturn in listings on line breaks. Workaround:
> manually possible with Lout code in comments of listings.

Not sure what this is about.  If you need something, tell us more.

> Shell/logfile and plain listing style is missing. Workaround: I re-used 
> Haskell.

Or just "@F @Verbatim" is often a good fallback.

> Colors: Specification in RGB Hex ala HTML/CSS would be nice.  Workaround: 
> pre-calc or { bc -l } @Pipe :)

Where does it stop?

> @*NumberedDisplay number format: left side numbers are not possible :(

Where does it stop?

Uwe says something about a cut and paste error, but from what I can see,
all variants of @NumberedDisplay put the number at the right; they vary
in where they put the display, not in where they put the number.

> Would be nice to have a Bibtex to Lout converter. I was to lazy to write
> one, but I guess with some Perl/String/Regex foo this is done in a short
> time and may motivate other users to switch to Lout :)

I once wrote a Lout to BibTeX converter.  I think the code might still
be out there somewhere.

> I personally think the Plain and PDF export is useless and can be dropped.
> Both work only very limited and there are tools available to convert from PS
> to PDF to TXT and back.
> For me ps2pdf works fine, once I figured out that
> I need to set some options correctly:
> ps2pdf -sFONTPATH=fonts/ -sPAPERSIZE=isob5 thesis.ps

I have found lout -p useful at times.  It's a pity that -PDF doesn't
do the full job, but it never will, because it's too hard.

> IsoB5 vs Louts JisB5 -> Workaround: use customized 'other' page
> size in Lout.

How the Lout B4 and B5 sizes came to follow the JIS standard I have
no idea.  They were set up a very long time ago.  Anyway, I've added
and documented ISOB4, ISOB5, JISB4, and JISB5 paper sizes for the
next release.  The existing B4 and B5 sizes are still there, equal to
their old values, JISB4 and JISB5 (it's too risky to change them),
but deprecated in the documentation.

> Diag Links really miss a color option. Workaround: colorize manually.

My workaround:  green @Colour @Link ...  But this doesn't scale well
when there are many green links.  This is the same issue as discussed
immediately below for the font option of @Graph.  Another user asked
for this as well, so I've added outlinecolour and pathcolour options
to @Diag for the next release.

> @Graph definitely misses an option to set fonts (workaround is set
> whole graph).

This isn't a workaround, it's the usual way to change the font of
something.  A font option is only needed when it is applied to lots
of related things.  I have now added one, because it now can apply
to lots of things, in the @GraphSetup symbol (see next point).

> Furthermore, why no 'copy and local include template' for inheritance
> of default options similar to book, tbl and diag, etc.?  

I think the reason why @Graph has no setup file options is that it is
very old (1993).  Even poor little @Pie has setup file options, but
it's more recent.  Anyway I've added setup file options to @Graph for
the next release.  They are backward compatible, luckily.

> @Graph axes width is not configurable. Would be nice to have an axis
> line width option (for bigger axis than data lines). 

Where do we stop?

> A CrossLink to the line numbers of @CP would be nice to have, to be
> able to reference listing lines in text.

Not sure how this could be implemented.