% 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.
%
% This version is just a single tool from a larger body of tools I am 
% unlikely to implement.  I wrote this in 1999 in response to a request
% on comp.text.tex.
%
% Features:
% Yes Special formatting for first line of text in a paragraph
% 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)
%
% Instructions:
%
% \FirstLine{<text>}
%
% The "\FirstLine" command takes one argument: Some text.
% 
% 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".
% 
% 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{\scshape\textcolor{blue}}".  The 
% defult definition is "\providecommand\FirstLineFont{\scshape}".

\ProvidesPackage{magaz}[2011/11/24 v0.4]

\newcommand\FirstLine[1]{%
 \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
 \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@
   %\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\unskip\unpenalty \unskip\unkern\unskip\unpenalty
     \ifnum\prevgraf<\tw@ % All text fits on first line
       \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\unskip\unpenalty \unskip\unkern\unskip\unpenalty
         \global\setbox\mz@firstbox\lastbox % grab first line
         % 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 "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\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. }%
         \advance\@tempcnta\@ne % number of segs in 1st line plus 1
         \edef\@tempa{\the\@tempcnta\space}% 3) Collect "other segments"
         \@whilenum \@tempcnta>\@ne\do{% build \parshape lines
           \edef\@tempa{\@tempa \z@\z@}%
           \advance\@tempcnta\m@ne
         }%
         %\message{Parshape: \@tempa \z@\maxdimen}%
         \parshape \@tempa \z@\maxdimen
         #1\@@par
         \unskip\unkern\unskip\unpenalty \unskip\unkern\unskip\unpenalty
         \global\setbox\mz@remains\lastbox 
       \fi
     \fi
   \fi
 }% end vbox "2)"
 \endgroup
 \ifvoid\mz@firstbox
   #1% Error case: just output the text
 \else
   {\everypar{}\noindent}\nobreak % everypar was captured in firstbox
   \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
}

\newbox\mz@firstbox
\newbox\mz@remains

\providecommand\FirstLineFont{\scshape}

% In the future, I might allow some non-text material by using \vsplit
% as a fallback method of grabbing lines, and I might allow more or
% unusual text in the `remainders' by skipping the step of setting two
% lines (instead setting one first line plus many tiny lines all together).
% The following macro would then handle those cases with a secondary
% algorithm as an error recovery mechanism.  Right now it just gives an 
% error message and dumps out the text.

\def\mz@handlebad{\mz@error}
\def\mz@error#1{%
 \PackageError{magaz}{Bad text for \string\FirstLine\space ending\on@line}{}%
 \global\setbox\mz@remains\box\mz@firstbox % void first box
}
 
\endinput

Test file integrity:  ASCII 32-57, 58-126:  !"#$%&'()*+,-./0123456789
:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~