Re: response to Joerg Jung's posting

[Joerg Jung]

Hi,

Am 24.06.2013 um 08:25 schrieb Jeff Kingston <address@hidden>:

> 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.

Thanks for looking into them!

> 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.  

That perfectly makes sense to me. Not everything should be
added. IMHO sometimes a sentence in the user guide about a 
(missing) feature or a workaround is good enough.

> 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.

ACK. Several of the options I mentioned below are "nice to have" not
"must have" options.

>> @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.

I understand, that a generic/clean final fixing for @DP is not possible 
due to several (historic) reasons. But, I think the unpredictable @DP between 
Captions and Figures/Tables/Floaters (depending on the chosen Location)
should be replaced by // for consistency reasons.

>> 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.

I think having it documented and the @NP workaround available is 
perfectly fine. Thanks!

>> @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.

Great, thanks! So I can remove my local hacks soon :)

>> @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.

Fair enough, thanks!

>> Defintion/Claim/Example/Proposition TitleFormat seems not to be
>> used (with book).
> 
> That was a bug, now fixed for next release.

Thanks!

>> 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.

I think this was my fault, I mixed up dashlength and (x|y)ticklength and
expected the ticks to change with the dashlength. Sorry for the 
inconvenience.

>> 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.

I understand, but IMHO this should be documented and as workaround 
could be suggested: playing with the painted and shadow options or the
@N|@S|@W... options.

>> @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.

Fair enough.

>> 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.

IMHO this should be documented in the user guide.

>> Overheads: with @Lectures the default @OverheadNumInDisplays { No }
>> seems not to be applied.  
> 
> That was a bug, now fixed for next release (thanks Uwe).

Thanks!

>> 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.

There is the memoir class design guide which lists the book parts
(including frontmatter) in a very detailed manner in Chapter 2:
http://mirrors.ctan.org/info/memdesign/memdesign.pdf

I think this is a good reference, which includes some historical 
background as well. 

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

I think this one is not really a new feature, but instead just a more sane 
default.
Not hardcoding the caption with 0.5rt by default gives better flexibility later.
It is easily change-able, just remove the 0.5rt and add @CC to 
@*CaptionFormat, should not have any side-effects, right? 
Otherwise, the workaround using @HExpand could be documented.

>> 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?

This one is probably harder then the one above, so maybe just document 
the @HExpand workaround?

>> 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.

That is what I expected. Fair enough.

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

Sorry, I do not understand this?

>> 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.

I meant something different here: I  have no option to have the 
List of Figure, List of Table and List of Floaters itself in the main table 
of contents. I expected up to three entries/lines for the List of Figures, 
List of Tables  and List of Floaters in the table of contents -- right after 
the preface line and before the Introduction/Abbreviations line.
Sorry for not being clear enough here.  

>> 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?

This probably belongs to the larger: "what belongs to preface/frontmatter"
discussion mentioned above.

>> 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.

Fair enough, but should be documented somewhere (probably in the expert guide?).

>> 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.

Supposed you have program listing e.g. a c-program and you have very 
long lines which break in the PS output -- then AFAIK in modern magazines
and books it is considered good style to add a carriagereturn (or similar 
symbol) at the breaking point to suggest the reader: "Here we break the 
line manually, because we have limited width of (e.g. A4) paper -- but 
if you type the line into a terminal you need to keep it in one long line."
The LaTeX listings package provides prebreak and postbreak option
to achieve this, as e.g. discussed here: 
http://stackoverflow.com/questions/1965702/how-to-mark-line-breaking-of-long-lines

This is just a "nice to have" feature. I think most people can live with the 
workaround of adding the breaking symbol manually through Lout code 
in comments.

>> Shell/logfile and plain listing style is missing. Workaround: I re-used 
>> Haskell.
> 
> Or just "@F @Verbatim" is often a good fallback.

But Verbatim does not provide Line numbers. I want that all my listings 
look similar and that I can reference line numbers in the text description.
Anyway, maybe someone comes up with a shell for prg2lout diff at 
some day.

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

Probably here,  just nice to have. Probably easy to implement in mydef's using 
Pipe :)

>> @*NumberedDisplay number format: left side numbers are not possible :(
> 
> Where does it stop?

Probably here :)

>> 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.

Took me a while, but I found it :) 
You may want to add to the lout release tarball (in a contrib/ folder or 
something).

>> 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.

So, why not zap the -PDF? I'm pretty sure this will reduce and simplify
code in several places :)

>> 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.  

Thanks for taking care of this!

>> 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.

Great! Thanks!

>> @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).

Great! Thanks!

>> 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.  

This poor little @Pie is not so poor... IMHO it is simple and good. 
Not even gnuplot can handle Pie's nowadays!

> Anyway I've added setup file options to @Graph for
> the next release.  They are backward compatible, luckily.

Great! Thanks!

>> @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?

Probably here :) 
Just a minor feature request, which I thought is probably easy to implement.

>> 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.

Yes, looks to complicated, so probably stop here as well.

Thanks,
Regards,
Joerg