magaz 0.4 (29nov11)

git-svn-id: svn://tug.org/texlive/trunk@24694 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 110 insertions, 32 deletions

diff --git a/Master/texmf-dist/tex/latex/magaz/magaz.sty b/Master/texmf-dist/tex/latex/magaz/magaz.sty
index e1a33ec3bf3..b6ba7f74ca8 100644
--- a/Master/texmf-dist/tex/latex/magaz/magaz.sty
+++ b/Master/texmf-dist/tex/latex/magaz/magaz.sty
@@ -1,4 +1,4 @@
-% magaz.sty  Ver 0.3   22-Nov-2011  "Magazine style"
+% magaz.sty  Ver 0.4   24-Nov-2011  "Magazine style"
 % Copyright 1999-2011, Donald Arseneau,   asnd@triumf.ca,  Vancouver, Canada
 % This software may be freely used, transmitted, reproduced, or modified
 % provided that the copyright notice and this permission is retained.
@@ -9,79 +9,142 @@
 %
 % Features:
 % Yes Special formatting for first line of text in a paragraph
-% No  Special formatting for for first n lines (allow each different)
-% No  Also for first character (drop caps) (working together)
-% No  "Continued on"/"continued from" markers (like fwlw)
+% Not Special formatting for for first n lines (allow each different)
+% Not Also for first character (drop caps) (working together)
+% No  "Continued on"/"continued from" markers (like varioref marks)
 % No  wrapfig spanning columns
 % No  wrapfig placed at fixed location on page
-% NO! Piecing together fragments of gallies to fit page (maybe flowfram)
+% No Piecing together fragments of gallies to fit page (maybe flowfram)
 %
 % Instructions:
 %
+% \FirstLine{<text>}
+%
 % The "\FirstLine" command takes one argument: Some text.
 % 
-% The first line of this text will be formatted according to
-% "\FirstLineFont"; but if the text occupies less than a line, all 
-% that text (and no more) will be affected by "\FirstLineFont".  
-% The argument should be ordinary text, not lists and displayed 
-% equations. Such things will give you a `Bad text' error.
+% The "\FirstLine" command is placed at the beginning of a paragraph, 
+% and takes one argument: Some text. The first line of this text will 
+% be formatted according to "\FirstLineFont"; but if the text occupies 
+% less than a full line of the paragraph, all that text (and no more) 
+% will be affected by "\FirstLineFont".
+% 
+% You should define "\FirstLineFont" appropriately as either a switch 
+% or a text-command; as in "\renewcommand\FirstLineFont{\MakeUppercase}".
+% The defult definition performed in \pkg{magaz.sty} is 
+% "\providecommand\FirstLineFont{\scshape}".
+% 
+% The parameter for "\FirstLine" should be ordinary text, not containing
+% lists or displayed equations -- such things will give you a ``Bad text''
+% error. If the parameter text ends with a space, that space will be 
+% removed. A line break may sometimes be permitted after the parameter 
+% text even if the ensuing text prohibits one (using "~"). Furthermore, 
+% the text should be constant, or else the successive measurements made 
+% internally will not be consistent, and the output may be corrupted
+% (with words missing or duplicated). Some subtle sources of inconstant 
+% text are:
+%  -  Incrementing a counter (and printing the value).              
+%  -  "\everypar" that executes once and is cleared. (This occurs after
+%     section heads and inside list/quotation/center/etc. environments,
+%     but those cases are handled, somewhat.)
+%  -  A "\FirstLineFont" that affects hyphenation (as "\texttt" or a
+%     language setting will).
+%  -  Changing paragraph-layout parameters in "\FirstLineFont".
 % 
-% This command is intended to be used in a replacement for a normal 
-% sectioning command in a document class; "\paragraph" would be 
+% Other deviations from simple text can give poor formatting. Here are some
+% `advanced' tips:
+%  -  Using "\FirstLine" in the middle of a paragraph will make a mess.
+%     (It should be used to start a paragraph, or placed at the beginning
+%     of one started with "\noindent".  Using it after "\\" should also
+%     work.)
+%  -  Multiple "\vspace" or "\\*" or "\\[]" will cause failure;
+%     a single "\vspace" will be ignored.
+%  -  Although there is no corruption if used immediately after a
+%     "\section" command (or similar) that suppresses indentation,
+%     the paragraph will likely be indented anyway.  The fix for
+%     this (and similar problems) is to begin the paragraph with
+%     "\noindent" before "\FirstLine".
+%  -  Using an inflexible "\parfillskip" might cause some highlighted
+%     first-line text to be dragged down to the second line. (Providing
+%     more text in the argument will usually solve this.) (If you 
+%     don't know about "\parfillskip" you probably don't have to worry.)
+%  -  A large font for "\FirstLineFont" may be too crowded with the
+%     second line, and inserting "\vspace" will not help (this should
+%     be improved) so you may need to resort to a "\strut", as with
+%     "\renewcommand\FirstLineFont{\large\strut\MakeUppercase}"
+%
+% The "\FirstLine" system is intended to be used in a replacement for 
+% a normal sectioning command in a document class; "\paragraph" would be 
 % appropriate.  In particular, this "\paragraph" (or whatever) should 
 % insert vertical space and penalties etc., and probably "\noindent"
 % at the start of the argument.  The document class should also define 
 % "\FirstLineFont" appropriately as either a switch or a text-command; 
-% as in "\renewcommand\FirstLineFont{\MakeUppercase}".  The defult 
-% definition is "\providecommand\FirstLineFont{\scshape}".
+% as in "\renewcommand\FirstLineFont{\scshape\textcolor{blue}}".  The 
+% defult definition is "\providecommand\FirstLineFont{\scshape}".
 
-\ProvidesPackage{magaz}[2011/11/22 v0.3]
+\ProvidesPackage{magaz}[2011/11/24 v0.4]
 
 \newcommand\FirstLine[1]{%
- \relax\if@inlabel\noindent\fi % produce a pending list item first
+ \relax\if@inlabel\noindent\fi % produce any pending list item label
  \begingroup
  % typeset text 3 times: 1) using all breaks to count segments; 2) with
  % a full first line and \FirstLineFont to get first line and remaining
  % segments; 3) Using current font, keeping only `remaining segments'
  % on a single line. 
  \setbox\z@\box\mz@firstbox \setbox\z@\box\mz@remains % void the global boxes
- \hbadness\maxdimen \hfuzz\maxdimen
  \setbox\@tempboxa\vbox{% 1) use all breaks
+   \hbadness\maxdimen \hfuzz\maxdimen
    \hsize\z@ \leftskip\z@skip \rightskip\z@skip \parfillskip\fill
    \parshape\z@ \pretolerance\m@ne \tolerance\@ne 
    \doublehyphendemerits\z@ \finalhyphendemerits\z@
    #1\global\mathchardef\mz@spf\spacefactor\@@par
    \global\mathchardef\mz@numl\prevgraf
+   %{\message{^^J^^J^^JText has \number\mz@numl\space segments:}\showhyphens{#1\unskip\unskip}}%
  }% end vbox "1)"
  \setbox\@tempboxa\vbox{% 2) first line, plus other segments
    \parshape \tw@ \z@\linewidth \z@\maxdimen 
    \doublehyphendemerits\z@ \finalhyphendemerits\z@
-   \sloppy \pretolerance\m@ne \parfillskip\fill
+   %\linepenalty\z@
+   % note no \hbadness\maxdimen \hfuzz\maxdimen at this stage
+   \pretolerance\m@ne \parfillskip\fill
    {\FirstLineFont{#1}\@@par}%
    \ifnum\prevgraf>\tw@ % Bad argument: not simple text or too much text
      \mz@handlebad{#1}%
    \else
-     \unskip\unkern\unpenalty \unskip\unkern\unpenalty
+     \unskip\unkern\unskip\unpenalty \unskip\unkern\unskip\unpenalty
      \ifnum\prevgraf<\tw@ % All text fits on first line
-       \setbox\z@\lastbox % Grab that line
-       \global\setbox\mz@firstbox\hbox{\unhbox\z@\unskip}%
-       %{\message{Entire text fits: }\showhyphens{\unhcopy\mz@firstbox}}%
-       \global\setbox\mz@remains\hbox{}%
+       \global\setbox\mz@firstbox\lastbox % Grab that line
+       %{\message{Entire text fits: }\showhyphens{\unhcopy\mz@firstbox\unskip\unskip\unpenalty}}%
+       \setbox\z@\hbox{\unhcopy\mz@firstbox}%
+       \begingroup
+       \advance\linewidth-0.4em\relax
+       \expandafter\endgroup
+       \ifdim\wd\z@>0.97\linewidth
+         %\message{^^JHandle wide first line: \the\wd\z@\space vs \the\linewidth. }%
+         \global\setbox\mz@firstbox\hbox to\wd\mz@firstbox{%
+             \unhcopy\mz@firstbox\unskip\unskip\unpenalty}% remove \parfillskip
+         \global\setbox\mz@remains\hbox{}% Trigger keeping of full wide line
+       \fi        % else \mz@remains remains void
      \else % 2 lines: text fills first line with some left over
        \setbox\z@\lastbox % remainders to \z@
        \ifvoid\z@ % could not grab last line 
          \mz@handlebad{#1}%
        \else 
-         \unskip\unkern\unpenalty \unskip\unkern\unpenalty
+         \unskip\unkern\unskip\unpenalty \unskip\unkern\unskip\unpenalty
          \global\setbox\mz@firstbox\lastbox % grab first line
-         %{\message{First line is: }\showhyphens{\unhcopy\mz@firstbox\unskip\unskip}}%
+         % Note: counting segments in this first line will be wrong if the line
+         % ended with a hyphenation.  It could be possible to detect and adjust
+         % for the resulting extra segment if it is deemed desirable to count the
+         % first line directly.
+         %{\message{First line is: }\showhyphens{\unhcopy\mz@firstbox\unskip}}%
          %{\message{Remaining segments are: }\showhyphens{\unhcopy\z@\unskip\unskip}}%
-         % 2a) break up "other segments":
-         \hsize\z@ \leftskip\z@skip \rightskip\z@skip \parfillskip\fill
+         %
+         % 2a) break up "remaining segments":
+         \hsize\z@ \hbadness\maxdimen \hfuzz\maxdimen
+         \leftskip\z@skip \rightskip\z@skip \parfillskip\fill
          \parshape\z@ \pretolerance\m@ne \tolerance\@ne 
          {\everypar{}\noindent}% mid-par so no \everypar or \parindent
          \nobreak % \nobreak because leftskip adds breakpoint
-         \unhbox\z@\unskip\@@par % gives number of "extra segments"
+         \unhbox\z@\unskip\unskip\unpenalty\@@par % gives number of "extra segments"
          %\message{There are \number\mz@numl\space segments in total and \the\prevgraf\space "remaining segments". }%
          \@tempcnta\mz@numl \advance\@tempcnta-\prevgraf 
          %\message{Number of segs in 1st line: \the\@tempcnta. }%
@@ -94,8 +157,8 @@
          %\message{Parshape: \@tempa \z@\maxdimen}%
          \parshape \@tempa \z@\maxdimen
          #1\@@par
-         \unskip\unkern\unpenalty \unskip\unkern\unpenalty
-         \global\setbox\mz@remains\lastbox
+         \unskip\unkern\unskip\unpenalty \unskip\unkern\unskip\unpenalty
+         \global\setbox\mz@remains\lastbox 
        \fi
      \fi
    \fi
@@ -105,8 +168,23 @@
    #1% Error case: just output the text
  \else
    {\everypar{}\noindent}\nobreak % everypar was captured in firstbox
-   \unhbox\mz@firstbox\unskip\unskip\unpenalty\break
-   \unhbox\mz@remains\unskip\unskip\unpenalty \spacefactor\mz@spf
+   \ifvoid\mz@remains % partial line only
+     % Unbox the partial line. This allows equal stretching of spaces across
+     % the line, but admits a slight chance that some \FirstLineFont may
+     % carry over to the second line.
+     \unhbox\mz@firstbox 
+     \unskip\unskip\unpenalty % remove \rightskip \parfillskip \nobreak
+     \allowbreak % allow a break rather than get dragged to next line (??)
+   \else % full first line 
+     % Output whole box to prevent unexpected linebreaks, especially for
+     % an overfull line and at the bogus discretionary that TeX leaves before
+     % a final (used) hyphen.
+     \box\mz@firstbox\break 
+     \unhbox\mz@remains
+     \unskip\unskip\unpenalty % remove \rightskip \parfillskip \nobreak
+     % (or remove forced \break for empty remains)
+   \fi
+   \spacefactor\mz@spf
  \fi
 }