Mime-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Message-ID:  <6087583906706202.WA.kellysmith12.21gmail.com@listserv.uni-heidelberg.de>
Date:         Sat, 17 Nov 2018 08:37:58 +0100
Reply-To:     Mailing list for the LaTeX3 project
              <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
Sender:       Mailing list for the LaTeX3 project <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
From:         Kelly Smith <kellysmith12.21@GMAIL.COM>
Subject: Re: Offer to Write an xskips Package
To:           LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
Precedence: list
Envelope-To: <rainer.schoepf@gmx.net>
Content-Transfer-Encoding: 8bit
Status: R

Hello,

Thank-you for the response, it gave me much to think about.

> that's a good question what harmonizes with L3 design-level interface.

xcoffins is listed as part of the design level, but it involves programming.
Although, it isn’t any more complicated than the tools designers use to make
graphics and fonts…

> So what is the purpose for example of \VerticalSpace? would it have a 
> natural place to live and if so why?

My thought was for spacing between document elements, but if the only part that
the designer should be concerned with is the values of the spaces, and the
programmer should worry about the commands that create spacing, then commands
like \VerticalSpace are unnecessary.

> I guess our ask here would be use cases for the commands you proposed to 
> get a feeling whether they should and if so in what form they should be 
> provided but not embark on making a copy of the expl3 code interfaces 
> 1-2-1 into CamelCase unless we all agree on seeing a good reason for it.

Providing simple duplicates of expl3 doesn’t help with much… If anything, that
just adds bulk to the L3 tools. I should have realized that.

> There are of course boundary cases, eg
> 
> a function for setting length parameters should naturally support 
> evaluations of its value argument (which right now \newlength doesn't 
> offer (unless you load calc.

A comment here. I suggested that an argument processor to verify user input
would be useful. Even if they are free of programmatic commands, I do think
that such checks are a good idea for author and designer interfaces, given
that errors can sometimes be tricky to discover in 2e. But it seems reasonable
that programmers should be expected to check (and double check) their inputs,
or face low-level errors at their own risk.

> But already the distinction between skips and dimens (that exist on the 
> programming level but not on the 2e user level in the setters) is 
> something to ponder. An I would be interested to see examples why the 
> distinction os sensible on the designer level (I'm not convinced it is)
> I mean, why shouldn't there be a single set of design-level setters.

My concern for not having a distinction would be that a stretch or shrink
expression could be passed to something that expects a fixed length. Then
again, 2e’s \newlength uses skips internally, and there doesn’t seem to have
been trouble caused by that. Of course, some machinery can be put in place to
prevent such errors.

It’s my understanding that in TeX, dimens are for the widths and heights of
objects &c, while skips are for spaces. However, I suppose there’s nothing to
stop one from creating a higher-level data type that say, works like a box but
can stretch or shrink to accommodate surrounding content. (Like boxes in CSS?)

If the plan is to define a high-level interface, then there’s no reason why
the underlying primitives should be constrained to their traditional roles.

> As for allocation, to what extend are they needed on the design level? 
> Aren't they only needed when you are actually asking for some programmed 
> code?

That’s true. Designers shouldn’t have to worry about things like allocation and
scope (especially given TeX’s explicit grouping).

>> I have attached the raw .sty code which contains what I think are appropriate
>> tools for the designer level. Of course, this would become a proper .dtx file
>> with documentation and examples.
> 
> So rather than documenting that suggestion, I would ask for convincing 
> examples for each of the proposed functions that are design tasks that 
> should live in a class file rather than programming tasks that should 
> live in package/modules that offer building blocks for titles building 
> blocks for headings etc etc.

The interface provided by xcoffins is nice because it simplifies working with
coffins by abstracting over the expl3, by doing convenient calculations, and by
providing default values. It reduces the complexity involved. My proposed skips
package, however, doesn’t provide such useful abstractions, so it wouldn’t have
the same sort of utility.

Since the designer interface is meant to be very declarative, the tools should
eschew raw, low-level typesetting instructions. As such, I can’t say that the
imperative interface I suggested fits those ideas.

> I'm not saying none of them are, maybe some are the right choice for the 
> design level, but instead of embarking on providing stuff that we later 
> regret, let us first better understand the needs. So if you have the 
> time I would very much look forward in seeing how you intend to use each 
> and every of these functions.

As I mentioned above, I was still thinking in terms of low-level spacing issues
when I proposed the package. The commands would have uses that are more-or-less
the same as we see with \hspace, \vspace, &c.

Final adjustments to a document require some manual intervention by a designer,
but defining the tools for doing that will probably be among the final
adjustments to L3 itself.

In short, I can’t really justify the package as I presented it. But I will
continue to think about what is necessary at this level.

—Kelly


> ps while we are at it, uses of \parbox and friends (or coffins) would be 
> also very much of interest. where do you use them and how ...

While working on the pagestyle module, I tried using coffins to typeset headers
and footers. However, I discovered that the \baselineskip is set to strange
values in the header and footer, so I would need to create a group and manually
set it. Instead, using a \parbox provided the correct baselineskip without any
manual intervention. I still use coffins to place the header/footer rules so
I can easily place them exactly where I want, relative to the other content.

I’ve included the function I currently use to typeset both headers and footers.
(I’ve gone through a few iterations.) This has been tested, and I think the
results are pretty good. Though, I realize it’s probably a poor implementation.

% Values are received from pagestyle template variables.
% #1 = above rule width
% #2 = below rule width
% #3 = left content
% #4 = center content
% #5 = right content
\cs_new:Nn \__soranus_typeset_headfoot:NNNNN
  {
    % Put the body of the header/footer into a coffin.
    \SetHorizontalCoffin \l__soranus_tmpa_coffin
      {
        % The \textwidth is guaranteed to be the appropriate
        % width for headers/footers. I may, later, allow the
        % header/footer to extend over the marginpar, too.
        \hbox_to_wd:nn { \textwidth }
          {
            % \parbox makes alignment of the “cells” simple.
            % Each cell contains, at least, a \strut.
            \parbox [ t ] { 0.3\textwidth }
              { \raggedright \tl_use:N #3 \strut }

            \skip_horizontal:n { 0pt plus 1fill }

            \parbox [ t ] { 0.3\textwidth }
              { \centering \tl_use:N #4 \strut }

            \skip_horizontal:n { 0pt plus 1fill }

            \parbox [ t ] { 0.3\textwidth }
              { \raggedleft \tl_use:N #5 \strut }
          }
      }

    \dim_compare:nNnF { #1 } = { \c_zero_dim }
      {
        \SetHorizontalCoffin \l__soranus_tmpc_coffin
          { \rule { \textwidth } { #1 } }

        % The above rule needs to be raised slightly.
        \JoinCoffins
          \l__soranus_tmpa_coffin [ l, t ]
          \l__soranus_tmpc_coffin [ l, b ]
          ( 0pt, 3pt )
      }

    \dim_compare:nNnF { #2 } = { \c_zero_dim }
      {
        \SetHorizontalCoffin \l__soranus_tmpc_coffin
          { \rule { \textwidth } { #2 } }

        % The below rule doesn’t need to be lowered as much.
        \JoinCoffins
          \l__soranus_tmpa_coffin [ l, b ]
          \l__soranus_tmpc_coffin [ l, t ]
          ( 0pt, -2pt )
      }

    % Raise the header/footer slightly.
    \TypesetCoffin \l__soranus_tmpa_coffin ( 0pt, 2.5pt )
  }