From: deat@jhunix.hcf.jhu.edu (Arun Thomas)
Subject: Re: LaTeX: putting stuff in margins.
Followup-To: comp.text.tex 
Summary: Macro from TeX and TUG News
Organization: HAC - Johns Hopkins University, Baltimore
Distribution: na
Date: Wed, 18 Nov 1992 15:35:22 GMT

In article <1992Nov17.184721.22491@news.stolaf.edu> johnsonm@amcl12.math.stolaf.edu (Michael K Johnson) writes:
>
>I would like some help with a LaTeX macro, if someone would be so
>kind.  I need to put $\Diamond$ in the left margin of my text, with
>the right edge of the diamond .25 in from the left edge of the text.
>I would like it to be called like this:
>
>\blackdiamond This is a paragraph with a $\Diamond$ off the left side.

This is from TeX and TUG News Vol. 1, No. 3, Nov. 1992
(TeX and TUG News is published 4 times a year by TeX Users Group and us a 
newsletter for TeX and LaTeX users. For more info write TeX Users Group, 685
North Main Street, P.O. Box 9506, Providence, RI 02940-9506, or e-mail at
tug@math.ams.org, or phone (401)751-7760, or fax (401)751-1071.)

Making lines in the Margin

Peter Schmitt, University of Vienna
a8131dal@awiuni11.EDVZ.UniVie.ac.at

Putting some material into the margin is a standard procedure. Usually each
margin note is handled seperately, but sometimes this may be inconvenient, as 
proven by the following question which was recently raised on the German TeX 
list:

    Is there a convenient way to mark a number of lines by asterisks
    placed in the margin?

One possible solution is provided by the definitions of \marginmarkson and
\marginmarksoff, shown below (of course, shorter control sequence names could
be used!).

  \long\def\readword#1 {\strut\putmark#1 \next\relax}
  \def\margmark{$\ast\hskip10pt$}
  \def\putmark{%
      \vadjust{\vbox to 0pt{\vss\noindent
                            \llap{\strut\margmark}\vskip0pt}}%
      }
  \def\marginmarkson{\global\let\next=\readword\next}
  \def\marginmarksoff{\global\let\next=\relax}

The basic idea is to read the text word by word (or, more precisely, from
space to space) and - with each step - to use \vadjust to put an asterisk
into the margin. This feature is turned on by \marginmarkson and turned 
off by \marginmarksoff. The command \readword reads the material to the 
next space, sets the vadjust (using \putmark), reinserts the material 
(including the space) and finally iterates the process. Since \vadjust is 
inserted for the first time with the word following \marginmarkson, the 
first asterisk is put into the margin opposite the line that contains this 
word. The last line marked will be the line that contains the last word 
before \marginmarksoff.

These macros can be used independently of groups formed by \bgroup or 
\begingroup and allows (short) groups between braces (long groups may 
cause a missing margin mark).

In the definition of \readword, the \strut serves two purposes: it allows 
the use of \maqrginmarkson at the beginning of a paragraph since it 
guarantees that TeX will be in horizontal mode when the first \vadjust is 
inserted. And it protects against the (unlikely) case where a line does 
not contain letters which reach below the baseline since otherwise - in 
this case - the marginmark would be positioned higher than usual.

The \relax prevents the braces enclosing some group from disappearing 
when \readword reads its argument.

Remarks:

 o  Clearly, the asterisk used is just an example. It can easily be replaced
    by giving \margmark another meaning, as in the following examples which
    yield various types of changebars:

    \def\rule{\rule\strut\hskip5pt}
    \def\bar{\vrule height8.5pt depth 4.5pt width1.pt\hskip10pt}
    \def\dbar{\vrule height8.5pt depth 4.5pt width1.pt\hskip5pt%
              \vrule height8.5pt depth 4.5pt width1.pt\hskip10pt}

    The mark can be changed by \let\margmark\\bar even in the middle of
    a marked paragraph, provided one accepts that the line where the 
    change takes place shows both marks (as shown at the left). If 
    applicable, the definition of \margmark should use explicit fonts. 
    Otherwise a font change in the text may influence the appearence of 
    the mark.

 o  This definition might fail in situations using complicated constructions
    that interfere with \vadjust, but it works with ordinary text, both in
    TeX and LaTeX.

    Another source os problems may be the use of catcode changes in marked 
    text. One has to take care that the control sequence executing the change
    is read by \putmark before the argument; that is, one has to write

               read by\verb| \putmark| before

    instead of

               read by \verb|\putmark| before

    to obtain the phrase used above [see Editor's Note, next page].

 o  Of course, the algorithm used is not very efficient, since it puts one 
    mark into the margin for every word (space) in the line. But this does 
    not matter since these marks are all put into exactly the same location.
    And it works since usually each line will contain at least one space.


Editors Note:

This problem came to light as I was preparing Peter's article for TTN. I use
LaTeX \verb construction with vertical bars as delimiters, and wanted to 
demonstrate the maacros in the actual text. This however, resulted in some
rather severe interference:the text in the in-line verbatim construction 
disappeared! Peter wrote: "This first puzzled me - but the reason is quite 
clear. It is due to the (well-known) fact that taking an argument fixes the 
catcodes. Since \putmark reads a word (up to and including the space right 
after it), it takes up the \verb|\let\margmark=\bar| (for instance) and the 
control sequences are stored away before \verb takes action: the assignment 
gets executed instead of printed."

As well, he warns: "There is another problem inherent in the method used 
here: if the lineskip is not constant, then the marginmarks will be 
distributed irregularly or, in the case of bars, there may be holes 
(e.g. with math). But, in my opinion, there is a place for quick and not 
completely general macros ... As far as I know a general solution would 
require more complicated code."

We thought this additional note on some problems related to the marginmarks
macro would be instructive and useful: items offered in this column do not 
pretend to be the definitive solutions to situations which arise - I've said
so from the beginning. They're quick solutions, and in the general case, do 
work. But as this example shows, interference is always a possibility - and
not just with hacks. Users should be prepared to wrestle occasionally with 
someone else's code - this doesn't invalidate the code, nor does it mean 
that borrowing macros should be discouraged. It's just that one can't be
totally blind, or jump up and down when things work. Be happy when they 
do - be philosophical when they don't. Life's too short to get exercised 
about the occasional problem.

----------------------

This article is reproduced as it asspeared in TeX and TUG News (TTN) and all
issues are public domain. The source file for the entrire newsletter is 
placed in the aston, shsu, stuttgart, heidelberg, labrea, and ymir archives.

-Arun Thomas
 deat@jhunix.hcf.jhu.edu
 Homewood Academic Computing
 The Johns Hopkins University
 Baltimore, MD 21218