summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/magaz/magaz.tex
blob: 6939578f20d35fc92a85eb6b9d5b033e17e730f2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
\documentclass[parskip=half, pagesize=auto, 12pt]{scrartcl}

\usepackage{fixltx2e}
\usepackage{etex}
\usepackage{xspace}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{microtype}
%\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.4, dated~24--Nov--2011.}}
\author{Donald Arseneau,   \texttt{asnd@triumf.ca},  Vancouver, Canada}
\date{24--Nov--2011}


\begin{document}

\maketitle

\begin{quote}
  \small
  This software may be freely used, transmitted, reproduced, or modified
  provided that the copyright notice and this permission is retained.
\end{quote}

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:

\begin{center}
\begin{tabular}{@{}rl@{}}
  Yes & Special formatting for first line of text in a paragraph          \\
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, 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.

\section*{First-Line Formatting}

\noindent \cmd{\FirstLine}"{"\meta{text}"}"

\medskip

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}