summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Master/texmf-dist/doc/latex/magaz/magaz.pdfbin163321 -> 244266 bytes
-rw-r--r--Master/texmf-dist/doc/latex/magaz/magaz.tex123
-rw-r--r--Master/texmf-dist/tex/latex/magaz/magaz.sty142
3 files changed, 202 insertions, 63 deletions
diff --git a/Master/texmf-dist/doc/latex/magaz/magaz.pdf b/Master/texmf-dist/doc/latex/magaz/magaz.pdf
index 1a4fc6f6bca..61ae96222cd 100644
--- a/Master/texmf-dist/doc/latex/magaz/magaz.pdf
+++ b/Master/texmf-dist/doc/latex/magaz/magaz.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/magaz/magaz.tex b/Master/texmf-dist/doc/latex/magaz/magaz.tex
index 8cae98006a8..6939578f20d 100644
--- a/Master/texmf-dist/doc/latex/magaz/magaz.tex
+++ b/Master/texmf-dist/doc/latex/magaz/magaz.tex
@@ -1,4 +1,4 @@
-\documentclass[parskip=half, pagesize=auto]{scrartcl}
+\documentclass[parskip=half, pagesize=auto, 12pt]{scrartcl}
\usepackage{fixltx2e}
\usepackage{etex}
@@ -7,21 +7,27 @@
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{microtype}
-\usepackage{hyperref}
+%\usepackage{hyperref}
+\usepackage{shortvrb}
\newcommand*{\mail}[1]{\href{mailto:#1}{\texttt{#1}}}
\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\cs}[1]{\texttt{\textbackslash#1}}
+\newcommand*{\meta}[1]{\ensuremath{\langle}\textsl{#1}\ensuremath{\rangle}}
\makeatletter
\newcommand*{\cmd}[1]{\cs{\expandafter\@gobble\string#1}}
+\g@addto@macro\@listI{\itemsep\z@skip}
\makeatother
\addtokomafont{title}{\rmfamily}
+\MakeShortVerb"
+\frenchspacing
+
\sloppy
-\title{The \pkg{magaz} package\thanks{This manual corresponds to \pkg{magaz}~v0.3, dated~22--Nov--2011.}}
-\author{Donald Arseneau, \mail{asnd@triumf.ca}, Vancouver, Canada}
-\date{22--Nov--2011}
+\title{The \pkg{magaz} package\thanks{This manual corresponds to \pkg{magaz}~v0.4, dated~24--Nov--2011.}}
+\author{Donald Arseneau, \texttt{asnd@triumf.ca}, Vancouver, Canada}
+\date{24--Nov--2011}
\begin{document}
@@ -34,42 +40,97 @@
provided that the copyright notice and this permission is retained.
\end{quote}
-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 \texttt{comp.text.tex}.
+This package was intended to eventually be a collection of tools to aid
+magazine-style document formatting, but this version is just a single
+tool I first wrote in 1999 in response to a request on \texttt{comp.text.tex}:
+How to apply a formatting choice (font) the the first line of a paragraph.
+The full list of features is:
-\medskip
-\noindent Features:\\[4pt]
+\begin{center}
\begin{tabular}{@{}rl@{}}
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) \\
+Maybe & Special formatting for for first $n$ lines (allow each different) \\
+Maybe & 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 & Integration with shapepar \\
- NO! & Piecing together fragments of gallies to fit page (maybe flowfram)
+ No & Integration with shapepar, especially cutouts \\
+ No & Piecing together fragments of gallies to fit page (maybe flowfram)
\end{tabular}
+\end{center}
+Most of those features are very unlikely to ever be added to this package.
-\minisec{Instructions:}
+\section*{First-Line Formatting}
-The \cmd{\FirstLine} command takes one argument: Some text.
+\noindent \cmd{\FirstLine}"{"\meta{text}"}"
-The first line of this text will be formatted according to
-\cmd{\FirstLineFont}; but if the text occupies less than a line, all
-that text (and no more) will be affected by \cmd{\FirstLineFont}.
-The argument should be ordinary text, not lists and displayed
-equations. Such things will give you a `Bad text' error.
+\medskip
-This command is intended to be used in a replacement for a normal
-sectioning command in a document class; \cmd{\paragraph} would be
-appropriate. In particular, this \cmd{\paragraph} (or whatever) should
-insert vertical space and penalties etc.,\ and probably \cmd{\noindent}
-at the start of the argument. The document class should also define
-\cmd{\FirstLineFont} appropriately as either a switch or a text-command;
-as in \verb+\renewcommand\FirstLineFont{\MakeUppercase}+. The defult
-definition performed in \pkg{magaz.sty} is
-\verb+\providecommand\FirstLineFont{\scshape}+.
+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:
+\begin{itemize}
+\item Incrementing a counter (and printing the value).
+\item "\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.)
+\item A "\FirstLineFont" that affects hyphenation (as "\texttt" or a
+ language setting will).
+\item Changing paragraph-layout parameters in "\FirstLineFont".
+\end{itemize}
+Other deviations from simple text can give poor formatting. Here are some
+`advanced' tips:
+\begin{itemize}
+ \item 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.)
+ \item Multiple "\vspace" or "\\*" or "\\[]" will cause failure;
+ a single "\vspace" will be ignored.
+ \item 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".
+ \item 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.)
+ \item 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}"
+ \end{itemize}
+
+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}".
+
+\section*{All Other Features}
+
+Not implemented.
\end{document}
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
}