Document structure and headlines/Headlines formatting

From Wiki
Jump to navigation Jump to search

Formatting Titles with \setuphead

For numbering see Section numbering.

The following parameters to \setuphead change the style of the headlines.

Text Number Both
textstyle numberstyle style
textcommand numbercommand command
deeptextcommand deepnumbercommand

Quite obviously, the number commands work on the chapter/section/etc. number, their text counterparts change the text itself. However, there are differences between style, command and deepcommand.

  • The style variants accept a style (bold, cap, etc.) or a font switch (\em, \tfx, etc).
  • textstyle prepends the text with the associated style.
  • textcommand is a command name which is given the text (with all markup) as a parameter.
  • deeptextcommand is similar to textcommand but it acts only on the text (not on the markup).

So, if we have \title{A story}, the different parameters have the following results:

textstyle=\em => \em A story
textstyle=\em, textcommand=\uppercase => \uppercase{\em A story} => \em A STORY
textstyle=\em, deeptextcommand=\uppercase => \em\uppercase{A story} => \em A STORY
  • \setuppapersize[A8,landscape]
    
    \starttext
    \setuphead[section]
      [textstyle=\em]
    \startsection
      [title={A story}]
    \stopsection
    
    \setuphead[section]
      [textstyle=\em, 
       textcommand=\uppercase]
    \startsection
      [title={A story}]
    \stopsection
    
    \setuphead[section]
      [textstyle=\em, 
       deeptextcommand=\uppercase]
    \startsection
      [title={A story}]
    \stopsection
    \stoptext
    

What is the difference between textcommand and deeptextcommand, then? With this example there is very little difference, as uppercase knows how to handle markup. Sometimes this is not the case. For example, an almost similar command WORD is not compatible with textcommand, because it wreaks havoc with markup:

textstyle=\em, textcommand=\WORD => \WORD{\em A story} => \EM A STORY
textstyle=\em, deeptextcommand=\WORD => \em\WORD{A story} => \em A STORY
  • \setuppapersize[A8,landscape]
    
    \starttext
    \setuphead[section]
      [textstyle=\em]
    \startsection
      [title={A story}]
    \stopsection
    
    \setuphead[section]
      [textstyle=\em, 
       textcommand=\WORD]
    \startsection
      [title={A story}]
    \stopsection
    
    \setuphead[section]
      [textstyle=\em, 
       deeptextcommand=\WORD]
    \startsection
      [title={A story}]
    \stopsection
    \stoptext
    

In this case using deeptextcommand is the correct solution for capitalizing headers. (Using \uppercase works in this specific case, but only if you stick to Latin 1 or Anglo-Saxon characters. Other languages will suffer from lowercase accented characters, like CAFé.)

Headline text alignment and hyphenation

Headlines should often be left aligned without hyphenation. Try this:

  • \setuppapersize[A8,landscape]
    
    \starttext
    \startsection
      [title={Headline with long words alignment hyphenation}]
    \stopsection
    \stoptext
    
  • \setuppapersize[A8,landscape]
    \setuphead
      [section]
      [align={flushleft, nothyphenated, verytolerant}]
    
    \starttext
    \startsection
      [title={Headline with long words alignment hyphenation}]
    \stopsection
    \stoptext
    
  • \setuppapersize[A8]
    
    \setuphead
      [section]
      [numberstyle=bold,
       textstyle=cap,
       before=\hairline\blank,
       after=\nowhitespace\hairline,
       align={flushleft, nothyphenated, verytolerant}]
    \starttext
    \startsection
      [title={Hasselt makes headlines},
       reference=hasselt-ref]
    Text.
    \stopsection
    \stoptext
    

Empty the headers of pages preceding a new chapter

Using \setuppagenumbering[alternative=doublesided] makes the chapters start on the right page. However, the blank page is not truly empty, it contains headers and footers.

  • \definepapersize[sheet][width=156mm,height=148mm]
    \setuppapersize[A8][sheet]
    \setuppaper[nx=3,ny=2]
    \setuparranging[XY]
    \showframe[edge]
    \setuphead [align={flushleft, nothyphenated, verytolerant}]
    \setupalign[tolerant]
    \setupbodyfont[6pt]
    \setuppagenumbering [alternative=doublesided]
    
    \setupheadertexts[{\sc\getmarking[chapter]}]
    \setupfootertexts [{rightpage}]  [pagenumber] [pagenumber] [{leftpage}]
    
    \starttext
    \startchapter[title={Chapter A}]
    \dorecurse{3}{\input tufte}
    \stopchapter
    \startchapter[title={Chapter B}]
    \dorecurse{3}{\input tufte}
    \stopchapter
    \stoptext 
    

To get truly empty pages, use \definepagebreak and \setuphead with the option page=. See the following:

  • \definepapersize[sheet][width=156mm,height=148mm]
    \setuppapersize[A8][sheet]
    \setuppaper[nx=3,ny=2]
    \setuparranging[XY]
    \showframe[edge]
    \setuphead [align={flushleft, nothyphenated, verytolerant}]
    \setupalign[tolerant]
    \setupbodyfont[6pt]
    \setuppagenumbering [alternative=doublesided]
    
    \definepagebreak                 % HERE /!\
      [mychapterpagebreak]
      [yes,header,right]
    
    \setuphead
      [chapter]
      [page=mychapterpagebreak]      % AND HERE /!\
    
    \setupheadertexts[{\sc\getmarking[chapter]}]
    \setupfootertexts [{rightpage}]  [pagenumber] [pagenumber] [{leftpage}]
    
    \starttext
    \startchapter[title={Chapter A}]
    \dorecurse{3}{\input tufte}
    \stopchapter
    \startchapter[title={Chapter B}]
    \dorecurse{3}{\input tufte}
    \stopchapter
    \stoptext 
    

Explanation

  • You define a new pagebreak rule. It has the name mychapterpagebreak. The options set read as: pagebreak=yes, placeheader, use a right page.
  • You set options for the header of type chapter and use for the option page the afore defined new pagebreak.
  • You might want to experiment with the commented lines and see what happens. For example, the \setupsectionblock commands will give a truly blank page (if needed) after the specified stop*part command.

When using macro divisions (front, body, back matters and appendices)

When using *frontmatter, *bodymatter, *backmatter and *appendices, you need to remove the page they create to get the page before a new chapter or part with no headers and footers.

\setupsectionblock [frontpart] [page=]
\setupsectionblock [bodypart] [page=]
\setupsectionblock [backpart] [page=]
\setupsectionblock [appendix] [page=]

\definepagebreak [firstpagebreak] [yes,header,footer,right]  % HERE
\setuphead [chapter] [page=firstpagebreak]

\setuppagenumbering[alternative=doublesided]
\starttext
\startfrontmatter
\chapter{front}
\stopfrontmatter
\startbodymatter
\chapter{body}
\stopbodymatter
\startappendices
\chapter{appendix}
\stopappendices
\startbackmatter
\chapter{back}
\stopbackmatter
\stoptext

Flushing headline data without typesetting them in the text

The following is probably a very special case. Hoever suppose you need to place section information like the title e.g. in the topspace area. You want that the section is still displayed in the TOC, but you do not want that at the spot where \startsection[title=...,list=...] resides there is any trace of it. The command to be used to hide the section title is:

\setuphead
   [section]
   [placehead=hidden] 

Be aware that with this setting indeed the section title is not shown and no white space is inserted. However in this way also the list entry for the TOC is gone. What you can do in such cases is to use the following command in connection with the above mentioned setting:

\setuptexttexts[{\placerawheaddata[section]} 

What happens is that the information in the \startsection[title=...,list=...] command is passed to the texttexts, which are flushed at every page. In order to see when it is flushed you might place e.g. !!! in front of the \placerawheaddata[section].

The result is a complete TOC without any trace of the section heading in the text.

Demo:

  • \definepapersize[sheet][width=104mm,height=148mm]
    \setuppapersize[A8][sheet]
    \setuppaper[nx=2,ny=2]
    \setuparranging[XY]
    \showframe[edge]
    
    \setuphead
       [section]
       [placehead=hidden,
        page=yes]
    
    \setuphead
       [subsection]
       [placehead=yes,
        page=yes,
        continue=yes,
        style=\it]
    
    \setuptexttexts[{\placerawheaddata[section]}]
    
    \starttext
    
    \placelist[section,subsection] 
    
    \blank[line]\hrule\blank[line]
    
    \startsection[title=First section]
    
       \startsubsection[title=First subsection]
          Lorem ipsum \dots
       \stopsubsection
    
       \startsubsection[title=Second subsection]
          Lorem ipsum \dots
       \stopsubsection
    
    \stopsection
    
    \startsection[title=Second section]
    
       \startsubsection[title=First subsection]
          Lorem ipsum \dots
       \stopsubsection
    
    \stopsection
    
    \stoptext
    

Use the margin

Number in the margin

This very simple example shows how to start a title within the margin, rather than at the text’s edge

  • \setuppapersize[A8,landscape]
    \showframe
    \setuphead[section][alternative=margin]
    
    \starttext
    \startsection[title={Sample chapter}]
    Number is in margin, not at text edge.
    \stopsection
    \stoptext
    

Headline in the margin

Source on tex.stackexchange

The margintext alternative is mentioned in the command reference [1]).

To raise the position of the first line of the margin text you can use the dy key for \setupmargindata (\setupmargindata[margintext:section][dy=-2pt]). – Wolfgang Schuster - Commented Feb 14, 2018


  • \setuppapersize[A7]
    \setuplayout
      [leftmargin=1.5cm,
       backspace=1.75cm,
       width=5cm]
    \showframe[text] [leftmargin,text]
    \setupmargindata
      [margintext:section]
      [align={flushleft,nothyphenated,verytolerant}]
    
    \setuphead
      [section]
      [alternative=margintext,
       style=\sc]
    
    \starttext
    \startsection[title={First\\Subject}]
    \input ward
    \stopsection
    \startsection[title={Second\\Subject}]
    \input ward
    \stopsection
    \stoptext
    

Headline in the margin (2003)

It is sometimes wanted to place the title of a section/subject etc in the margin next to the section text (instead of above it). This is achieved by the following setup:

  • \setuppapersize[A7]
    \setuplayout
      [leftmargin=1.5cm,
       backspace=1.75cm,
       width=5cm]
    \showframe[text] [leftmargin,text]
    
    \define[2]\MyHead{\inmargin{#1 #2}}
    \setuphead
      [section]
      [alternative=text,
       style=\sc,
       distance=0pt,
       command=\MyHead,]
    
    \starttext
    \startsection[title={First\\Subject}]
    \input ward
    \stopsection
    \startsection[title={Second\\Subject}]
    \input ward
    \stopsection
    \stoptext
    

See the mailing list thread (2003) for more on this.

Numbering and text on separate lines

To have the chapter title simply in a new line, a new command needs to be defined that takes care of this. It needs to be wrapped in \framed.

  • \setuppapersize[A8,landscape]
    
    \setuplabeltext [en] [section=Section~]
    
    \define[2]\MySection{%
    \framed
      [frame=off,
       width=broad,
       align=flushleft]
      {#1\\#2}}
    
    \setuphead
      [section] 
      [command=\MySection]
    
    \starttext
    \startsection[title={Foo Bar}]
    \stopsection
    \stoptext
    

Section label in the headline

This example illustrates expanded chapter titles with \headtext. You need to define the text with \setupheadtext or \setuplabeltext as above.

  • \setuppapersize[A8,landscape]
    
    \define[2]\MySection{%
    \framed
      [frame=off,
       bottomframe=on,
       topframe=on]
    {\vbox{#1\blank#2}}}
    
    \setuphead
      [section] 
      [command=\MySection,
       style={\ss\bfa}]
    
    \starttext
    \startsection[title={Foo Bar}]
    \stopsection
    \stoptext
    
  • \setuppapersize[A8,landscape]
    
    \define[2]\MySection{%
    \framed
      [frame=off,
       bottomframe=on,
       topframe=on]
    {\vbox{\headtext{section} #1    % HERE 
    \blank#2}}}
    
    \setuphead
      [section] 
      [command=\MySection,
       style={\ss\bfa}]
    
    \setupheadtext[section=Section] % HERE
    \starttext
    \startsection[title={Foo Bar}]
    \stopsection
    \stoptext
    

Headline with an enlarged shadow

This is an example of chapter headings with an enlarged shadow behind them, based on a solution by Hans (2004).

  • \setuppapersize[A8,landscape]
    \mainlanguage[fr]
    
    \setupcolors[state=start]
    
    \definefont
      [BigFontOne]  
      [Regular sa 3]      %RegularSlanted sa 3(ori)
                          %Sans sa 3:don't work (pb accents)
    \definefont
      [BigFontTwo]
      [RegularBold sa 2]  %RegularSlanted
    
    \definecolor
      [BigColorOne]
      [r=.86,g=.850,b=.54]
    \definecolor
      [BigColorTwo]
      [r=.43,g=.425,b=.27]
    
    \setuphead
       [chapter]
       [textcommand=\MyChapterText,
        color=BigColorTwo,
        style=\BigFontTwo]
    
    \def\MyChapterText#1{%
    \rlap{\BigFontOne\BigColorOne#1}\kern15pt#1}
    
    \starttext
    
    \startchapter
      [title={Question},
       reference={chap:ques}]
    \stopchapter
    \stoptext
    

Completely replace the text and chapter number with an image

This example shows how to completely replace the chapter text and number by an image:

  • \setuppapersize[A7]
    
    \useexternalfigure
      [section-1]
      [cow]
      [width=5cm,height=1cm]
    \useexternalfigure
      [section-2]
      [mill.png]
      [width=5cm,height=1cm]
    
    \setuphead
       [section]
       [command=\MySectionCommand]
    \setuphead 
       [subsection]
       [command=]   % to prevent inheritance from section 
    
    \define[2]\MySectionCommand%
       {\externalfigure[section-\namedheadnumber{section}]}
    
    \starttext
    Text.
    \startsection[title={One}]
      \startsubsection
        [title={First subsection of Section One}]
      \stopsubsection
    \stopsection
    
    \startsection[title={Two}]
    \stopsection
    
    \stoptext
    

There are a few snags though. MkII "forgets" to put the chapter in the TOC. So you have to set the deeptextcommand and deepnumbercommand separately instead (thus retaining the command that puts the chapter in the TOC), rather than setting the overall command, if you need a complete TOC.

\setuphead
    [chapter]
    [deeptextcommand=\MyChapterTextCommand,
     deepnumbercommand=\gobbleoneargument]      % hide chapter number

\def\MyChapterTextCommand#1%
    {\externalfigure[chapter-\currentheadnumber][height=5cm]}

archive.contextgarden.net (2005)

Users of MkIV can safely rely on command and don't have to bother with the deep...command variants. However, \currentheadnumber does not seem to return anything but 0. Thus, the following code is required to define \MyChapterCommand when using MkIV:

\def\MyChapterCommand#1#2%
   {\externalfigure[chapter-\namedheadnumber{chapter}][height=5cm]}

archive.contextgarden.net (2010)

More elaborate headline composition


TODO: a more attractive example using similar features (See: To-Do List)


  •    \setuppapersize[A7]
       \setupcolors[state=start]
       \startuseMPgraphic{HeaderDeco}
               numeric w, h, repeats;
               path p[];
               w := OverlayWidth ; h := OverlayHeight ;
               repeats := abs(TextWidth/BodyFontSize);
               p[1] := unitsquare xscaled w yscaled h ;
               draw p[1] withcolor white;
               p[2] := fullcircle scaled BodyFontSize;
               p[3] := fullcircle scaled .25BodyFontSize;
               draw p[2] shifted (.5BodyFontSize,0);
               for i = 1 upto repeats:
                   if odd i :
                       filldraw p[3] shifted (i*BodyFontSize+.5BodyFontSize,0);
                   else :
                       draw p[2] shifted (i*BodyFontSize+.5BodyFontSize,0);
               fi;
              endfor;
       \stopuseMPgraphic
    
       \setuphead[chapter][command=\Myheader]
       \setupheadtext
             [chapter=Chapitre]
       \defineoverlay[HeaderDeco][\uniqueMPgraphic{HeaderDeco}]
    
       \define[2]\Myheader{%
           \framedtext
               [width= \overlaywidth,
               height=6\bodyfontsize,
               background={foreground,HeaderDeco},
               offset=0pt,
               strut=no,
               frame=off,
               align=middle]{%
                   \headtext{chapter} #1
                   \blank[small]
                   #2}}
    
    \starttext
       \chapter{Here we go!}
    \stoptext
    

Title page with special background

If you want the title page of every chapter to have a special background (different from the background of normal pages), here’s a very effective trick that Hans has provided on the mailing list. In addition, this will give every chapter its own color scheme:

  • \definepapersize[sheet][width=104mm,height=148mm]
    \setuppapersize[A8][sheet]
    \setuppaper[nx=2,ny=2]
    \setuparranging[XY]
    \showframe[edge]
    
    \startMPinclusions
        numeric MyTitlePageDone[] ;
    \stopMPinclusions
    
    \startuseMPgraphic{background:normal}
      StartPage ;
        fill (topboundary Page -- cycle) enlarged(0,5mm) 
        shifted (0,-5mm) withcolor darkred ;
      StopPage ;
    \stopuseMPgraphic
    
    \defineoverlay
      [background:normal]
      [\useMPgraphic{background:normal}]
    
    \startuseMPgraphic{background:title}
      if unknown MyTitlePageDone.\namedstructureuservariable{chapter}{mycolor} :
        StartPage ;
           fill ((topboundary Page --cycle) enlarged(0,5mm)) shifted (0,-20mm)
                withcolor \MPcolor{color:title:\namedstructureuservariable{chapter}{mycolor}} ;
        StopPage ;
        MyTitlePageDone.\namedstructureuservariable{chapter}{mycolor} := 1 ;
      fi ;
    \stopuseMPgraphic
    
    \defineoverlay
      [background:title]
      [\useMPgraphic{background:title}]
    
    \setupbackgrounds
      [page]
      [background={background:normal,background:title}]
    
    \definecolor [color:title:one] [middlecyan]
    \definecolor [color:title:two] [middleyellow]
    
    \starttext
    
    \startchapter[title=One][mycolor=one]
     \input ward \page 
     \input knuth
    \stopchapter
    \startchapter[title=Two][mycolor=two]
     \input tufte
     \page 
     \input knuth 
    \stopchapter
    
    \stoptext
    
    

Chapter head with absolute positioning of following text

No matter how many lines the chapter head runs to, the text will always start, e.g. 4cm below the top of the heading:

  • \setuppapersize[A7]
    \setupbodyfont[8pt]
    
    \define[2]\MyChapterCommand{%
    \vbox to 4cm\bgroup
    {#1\hskip.75em #2}
    \vss\egroup}
    
    \setuphead[chapter]
      [header=nomarking, 
       command=\MyChapterCommand]
    
    \starttext
    
    \startchapter[title={test}]
    \input tufte
    \stopchapter
    
    \stoptext
    

Underlining to the width of last line of the headline

A style called for section headings to be followed by a rule which extends only the width of the text. More tricky was the need to make sure that if the text ran onto another line, it was the length of the last line that was to be followed.

Hans came up with this cleverness, showing two alternate ways of doing it:

  • \setuppapersize[A7]
    
    % ---- First solution ----
    
    \define[2]\FirstSolution%
      {\vbox\bgroup
       \setbox0\hbox{#1}
       \hsize.4\textwidth
       \beginshapebox#2\endshapebox
       \gdef\SetLastLineWidth{\xdef\LastLineWidth{\the\wd\scratchbox}}%
       \reshapebox
         {\setbox\scratchbox\hbox{\unhbox\shapebox}%
          \SetLastLineWidth
          \globallet\SetLastLineWidth\relax
          \box\scratchbox}%
       \scratchdimen\dimexpr\wd0+.25em+\LastLineWidth\relax
    % \setbox2\ruledvbox   {\innerflushshapebox} 
    % why is correction needed
       \setbox2\vbox        {\vskip-\lineskip\innerflushshapebox}
       \setbox0\vbox to \ht2{\box0}
       \hbox{\box0\hskip.25em\box2}
       \offinterlineskip
       \vskip.25ex
       \blackrule[width=\scratchdimen,height=1pt]
       \egroup}
    
    % ---- Second solution ----
    
    \doglobal\newcounter\NextLinePos
    
    \define[2]\SecondSolution%
      {\vbox\bgroup
       \hsize.4\textwidth
       \doglobal\increment\NextLinePos
       \setbox\scratchbox\hbox{#1}
       \hbox{\vtop{\copy\scratchbox}\hskip.25em\vtop{#2}}%
       \offinterlineskip
       \scratchdimen\dimexpr\wd\scratchbox+.25em+
         \MPx{e:npl:\NextLinePos}-\MPx{b:npl:\NextLinePos}\relax
       \vskip.25ex
       \blackrule[width=\scratchdimen,height=1pt]
       \egroup}
    
    \def\DoSecondSolution#1%
      {\bpos{npl:\NextLinePos}#1\epos{npl:\NextLinePos}}
    
    % ---- Trying it out solution ----
    
    % \showstruts
    
    \starttext
    \setuphead[section][command=\FirstSolution]
        \section{is this nice or not}
        \section{is this nice or not nice, that's the question}
    
    \setuphead[section][command=\SecondSolution,deeptextcommand=\DoSecondSolution]
        \section{is this nice or not}
        \section{is this nice or not nice, that's the question}
    \stoptext
    

As if that wasn't enough, Taco pointed out that \lastlinewidth is the easy route to finding the width of the last line. Use something like:

\optimizedisplayspacingtrue\setlastlinewidth % core-mat macro
\global\advance\lastlinewidth-\hangindent\par % adjust
\blackrule[width=\lastlinewidth,height=1pt]

Headline including bold math

When a section title is formatted in boldface text, this doesn't automatically typeset embedded math in bold. This is probably a good thing, as many math fonts do not include all characters in boldface, and often authors use boldface to distinguish between different meanings (for instance, scalar and vector variables). However, in some cases, it is desirable to format the math in the section titles in boldface.

Here a very simple example:

  • \setuppapersize[A8,landscape]
    \definetypeface
      [boldmath] [mm]
      [boldmath] [latin-modern]
      [default]
    \setuphead[section][style=\boldmath\rm\bfa]
    
    \starttext
    \section{Bold $a^2+b^2=c^2$ {\em bla}}
    text: not bold $a^2+b^2=c^2$ {\em bla}
    \stoptext