Difference between revisions of "Command/setuphead"

<cd:commandgroup name="setuphead" xmlns:cd="http://wiki.contextgarden.net/commanddoc/20200807"> <cd:shortdesc>\setuphead is used to configure headings and titles. Being structuring elements of any document, the possibilities are quite extensive. </cd:shortdesc> <cd:variants> <cd:command category="structure" file="strc-sec.mkiv" interfacedate="2020-06-19T13:41" interfacefile="i-section.xml" level="style" name="setuphead" variantnumber="1">

  <cd:arguments>
   <cd:keywords list="yes" optional="yes" ordinal="1">
    <cd:keywordsdoc></cd:keywordsdoc>
    <cd:constant type="cd:section"></cd:constant>
   </cd:keywords>
   <cd:assignments list="yes" ordinal="2">
    <cd:assignmentsdoc></cd:assignmentsdoc>
    <cd:parameter name="frontpartlabel">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="bodypartlabel">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="appendixlabel">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="backpartlabel">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="expansion">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="yes">expands the xml reference to actual content for title and bookmark

\xmlatt {xml:name::4}{title} → First section, see TUC file.

To expand userdata also use \normalexpanded{\startsection[title=\xmlatt{#1}{title}]} instead of expansion=yes.

\normalexpanded{} and are not in conflict, so you can use both.</cd:constant>

     <cd:constant default="yes" type="no">no expansion, xml reference is used</cd:constant>
     <cd:constant type="xml"> ?</cd:constant>
    </cd:parameter>
    <cd:parameter name="catcodes">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="sectionresetset">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="sectionseparatorset">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="sectionconversionset">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="conversion">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="sectionstarter">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:command"></cd:constant>
     <cd:constant method="apply" prefix="cd:processor" type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="sectionstopper">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:command"></cd:constant>
     <cd:constant method="apply" prefix="cd:processor" type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="sectionset">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="sectionsegments">
     <cd:paramdoc>which level(s) should be included, e. g. when head is numbered. Note, ":" specifies a range (e. g. "chapter:subsubsection")</cd:paramdoc>
     <cd:constant type="cd:number"></cd:constant>
     <cd:constant method="range" prefix="cd:number" type="cd:number"></cd:constant>
     <cd:constant method="range" prefix="cd:number" type="*"></cd:constant>
     <cd:constant method="range" prefix="cd:number" type="all"></cd:constant>
     <cd:constant type="cd:section"></cd:constant>
     <cd:constant method="range" prefix="cd:section" type="cd:section"></cd:constant>
     <cd:constant method="range" prefix="cd:section" type="*"></cd:constant>
     <cd:constant method="range" prefix="cd:section" type="all"></cd:constant>
     <cd:constant type="current"></cd:constant>
    </cd:parameter>
    <cd:parameter name="referenceprefix">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="+"></cd:constant>
     <cd:constant type="-"></cd:constant>
     <cd:constant type="cd:text"></cd:constant>
    </cd:parameter>
    <cd:parameter name="style">
     <cd:paramdoc>See manual Context: an excursion" section 33, Fonts and font switches, e.g. for large, bold, sans serif section headers use style=\tfa\bf\ss.</cd:paramdoc>
     <cd:constant type="cd:style"></cd:constant>
     <cd:constant type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="color">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:color"></cd:constant>
    </cd:parameter>
    <cd:parameter name="textstyle">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:style"></cd:constant>
     <cd:constant type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="textcolor">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:color"></cd:constant>
    </cd:parameter>
    <cd:parameter name="numberstyle">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:style"></cd:constant>
     <cd:constant type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="numbercolor">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:color"></cd:constant>
    </cd:parameter>
    <cd:parameter name="coupling">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:section"></cd:constant>
    </cd:parameter>
    <cd:parameter name="ownnumber">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="yes"></cd:constant>
     <cd:constant default="yes" type="no"></cd:constant>
    </cd:parameter>
    <cd:parameter name="beforesection">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="aftersection">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="insidesection">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="incrementnumber">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant default="yes" type="yes"></cd:constant>
     <cd:constant type="no"></cd:constant>
     <cd:constant type="list"></cd:constant>
     <cd:constant type="empty"></cd:constant>
    </cd:parameter>
    <cd:parameter name="placehead">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant default="yes" type="yes"></cd:constant>
     <cd:constant type="no"></cd:constant>
     <cd:constant type="hidden"></cd:constant>
     <cd:constant type="empty"></cd:constant>
     <cd:constant type="section"></cd:constant>
    </cd:parameter>
    <cd:parameter name="number">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant default="yes" type="yes">Include number before chapter/section title</cd:constant>
     <cd:constant type="no">Do not include number before chapter/section title</cd:constant>
    </cd:parameter>
    <cd:parameter name="page">
     <cd:paramdoc>- yes: The section header must be on the top of a new page

- left: The section header must be on the top of an even page - right: The section header must be on the top of an odd page</cd:paramdoc>

     <cd:inherit name="page"></cd:inherit>
    </cd:parameter>
    <cd:parameter name="marking">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="page"></cd:constant>
     <cd:constant type="reset"></cd:constant>
    </cd:parameter>
    <cd:parameter name="header">
     <cd:paramdoc>Set a particular header style, see \setupheader.</cd:paramdoc>
     <cd:constant type="start"></cd:constant>
     <cd:constant type="stop"></cd:constant>
     <cd:constant type="high"></cd:constant>
     <cd:constant type="none"></cd:constant>
     <cd:constant type="normal"></cd:constant>
     <cd:constant type="empty"></cd:constant>
     <cd:constant type="nomarking"></cd:constant>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="text">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="start"></cd:constant>
     <cd:constant type="stop"></cd:constant>
     <cd:constant type="high"></cd:constant>
     <cd:constant type="none"></cd:constant>
     <cd:constant type="normal"></cd:constant>
     <cd:constant type="empty"></cd:constant>
     <cd:constant type="nomarking"></cd:constant>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="footer">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="start"></cd:constant>
     <cd:constant type="stop"></cd:constant>
     <cd:constant type="high"></cd:constant>
     <cd:constant type="none"></cd:constant>
     <cd:constant type="normal"></cd:constant>
     <cd:constant type="empty"></cd:constant>
     <cd:constant type="nomarking"></cd:constant>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="before">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="after">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="inbetween">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="continue">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant default="yes" type="yes">If the section immediately follows a chapter it will be on the same page even though page=yes.</cd:constant>
     <cd:constant type="no">If the section immediately follows a chapter it will start on a new page.</cd:constant>
    </cd:parameter>
    <cd:parameter name="aligntitle">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="yes">use the current local hsize; flush side float first</cd:constant>
     <cd:constant default="yes" type="no">use the current global hsize</cd:constant>
     <cd:constant type="float">use the current local hsize; do not flush side floats</cd:constant>
    </cd:parameter>
    <cd:parameter name="interlinespace">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="interaction">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="list"></cd:constant>
     <cd:constant type="reference"></cd:constant>
    </cd:parameter>
    <cd:parameter name="internalgrid">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="grid">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="normal"></cd:constant>
     <cd:constant type="standard"></cd:constant>
     <cd:constant type="yes"></cd:constant>
     <cd:constant type="strict"></cd:constant>
     <cd:constant type="tolerant"></cd:constant>
     <cd:constant type="top"></cd:constant>
     <cd:constant type="bottom"></cd:constant>
     <cd:constant type="both"></cd:constant>
     <cd:constant type="broad"></cd:constant>
     <cd:constant type="fit"></cd:constant>
     <cd:constant type="first"></cd:constant>
     <cd:constant type="last"></cd:constant>
     <cd:constant type="high"></cd:constant>
     <cd:constant type="one"></cd:constant>
     <cd:constant type="low"></cd:constant>
     <cd:constant type="none"></cd:constant>
     <cd:constant type="line"></cd:constant>
     <cd:constant type="strut"></cd:constant>
     <cd:constant type="box"></cd:constant>
     <cd:constant type="min"></cd:constant>
     <cd:constant type="max"></cd:constant>
     <cd:constant type="middle"></cd:constant>
     <cd:constant type="math"></cd:constant>
     <cd:constant method="range" prefix="math" type="line"></cd:constant>
     <cd:constant method="range" prefix="math" type="halfline"></cd:constant>
     <cd:constant method="range" prefix="math" type="-line"></cd:constant>
     <cd:constant method="range" prefix="math" type="-halfline"></cd:constant>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="align">
     <cd:paramdoc></cd:paramdoc>
     <cd:inherit name="setupalign"></cd:inherit>
    </cd:parameter>
    <cd:parameter name="tolerance">
     <cd:paramdoc></cd:paramdoc>
     <cd:inherit name="setuptolerance"></cd:inherit>
    </cd:parameter>
    <cd:parameter name="strut">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant default="yes" type="yes"></cd:constant>
     <cd:constant type="no"></cd:constant>
    </cd:parameter>
    <cd:parameter name="hang">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="line"></cd:constant>
     <cd:constant type="broad"></cd:constant>
     <cd:constant type="fit"></cd:constant>
     <cd:constant default="yes" type="none"></cd:constant>
     <cd:constant type="cd:number"></cd:constant>
    </cd:parameter>
    <cd:parameter name="margin">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:dimension"></cd:constant>
    </cd:parameter>
    <cd:parameter name="indentnext">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="yes"></cd:constant>
     <cd:constant type="no"></cd:constant>
     <cd:constant type="auto"></cd:constant>
    </cd:parameter>
    <cd:parameter name="alternative">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="text"></cd:constant>
     <cd:constant type="paragraph"></cd:constant>
     <cd:constant default="yes" type="normal"></cd:constant>
     <cd:constant type="margin"></cd:constant>
     <cd:constant type="inmargin"></cd:constant>
     <cd:constant type="top"></cd:constant>
     <cd:constant type="middle"></cd:constant>
     <cd:constant type="bottom"></cd:constant>
     <cd:constant type="reverse"></cd:constant>
     <cd:constant type="margintext"></cd:constant>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="width">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:dimension"></cd:constant>
    </cd:parameter>
    <cd:parameter name="numberwidth">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:dimension"></cd:constant>
    </cd:parameter>
    <cd:parameter name="textwidth">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:dimension"></cd:constant>
    </cd:parameter>
    <cd:parameter name="distance">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:dimension"></cd:constant>
    </cd:parameter>
    <cd:parameter name="textdistance">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:dimension"></cd:constant>
    </cd:parameter>
    <cd:parameter name="commandbefore">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="commandafter">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:command"></cd:constant>
    </cd:parameter>
    <cd:parameter name="command">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:twoarguments"></cd:constant>
    </cd:parameter>
    <cd:parameter name="textcommand">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:oneargument"></cd:constant>
    </cd:parameter>
    <cd:parameter name="deeptextcommand">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:oneargument"></cd:constant>
    </cd:parameter>
    <cd:parameter name="numbercommand">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:oneargument"></cd:constant>
    </cd:parameter>
    <cd:parameter name="deepnumbercommand">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:oneargument"></cd:constant>
    </cd:parameter>
    <cd:parameter name="location">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="cd:name"></cd:constant>
    </cd:parameter>
    <cd:parameter name="criterium">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="strict"></cd:constant>
     <cd:constant type="positive"></cd:constant>
     <cd:constant type="all"></cd:constant>
    </cd:parameter>
    <cd:parameter name="hidenumber">
     <cd:paramdoc></cd:paramdoc>
     <cd:constant type="yes"></cd:constant>
     <cd:constant default="yes" type="no"></cd:constant>
    </cd:parameter>
   </cd:assignments>
  </cd:arguments>
 </cd:command>

</cd:variants> <cd:description>To headings is associated the text, i.e. the content of the heading, but can also be associated numbers.

These data can be processed for typesetting :

• add a dot between the text and the number,
• add a generic text before the "pure text"
• appearance can be different for the text if we use it in the headers / footers, or in the Table of Content.
• add vertical spaces before or after the text
• add rules before or after the whole section under the heading
• select if the title should appear on a right or a left page.

</cd:description>

<cd:examples><cd:example title="First example">

\setuppapersize[A5]
\setuplabeltext[chapter=CHAPTER~]

\setuphead[chapter][
	header=empty,
	alternative=middle,
	style=bold,
	numbercommand=\groupedcommand{}{\blank[2cm]},
	after={\blank[3cm]},
	]

\starttext

\chapter{Title of chapter}

The first paragraph begins 3 cm below the title. In this chapter, we will discuss...

\stoptext

produces

</cd:example><cd:example title="Big space before a smaller space behind the heading">

\setuphead
  [subject]
  [before={\blank[2*big]},
   after={\blank[big]},
   style=bold]

\starttext

\subject{Headline 1}
text text text text text text text text text text text text text text text vtext text text text text text text text text text text text text\par
\subject{Headline 2}
text text text text text text text text text text text text text text text vtext text text text text text text text text text text text text\par

\stoptext

produces

</cd:example><cd:example title="Setting label of a new section head">

\definehead[mychapter][chapter][bodypartlabel=mychapter]

\setuplabeltext[en][mychapter=My Chapter~]

\starttext
\mychapter{Animals}
\stoptext

produces

</cd:example><cd:example title="Inline headings similar to LaTeX &squo;s \paragraph{}">Modified from (https://tex.stackexchange.com/questions/375922/paragraph-title-in-context-similar-to-latex-paragraph).

\definehead[paragraph][subsubsubsubject]
\setuphead [paragraph]
           [
             textdistance=0pt,
             commandafter={.},
             alternative=text,
             style=sc,
          ]

\startparagraph[title=Knuth quote]
  \input knuth
\stopparagraph

produces

</cd:example><cd:example title="Setting label of a part">In MkIV, if you want parts to be labeled as "Part 1" etc., the following isn't sufficient (but works in MkII):

\setuphead[part][placehead=yes]

\starttext
\part{A part}

\stoptext

because it produces

For MkIV, add bodypartlabel=part to the setuphead:

\setuphead[part][placehead=yes, bodypartlabel=part]

\starttext
\part{A part}

\stoptext

(Thanks to Wolfgang Schuster on the mailing list for this information.)

</cd:example><cd:example title="Example of hidden sections">

\setupheadnumber[section]      [8]
\setupheadnumber[subsection]   [3]
\setupheadnumber[subsubsection][5]

\setuphead[section,subsection][placehead=hidden]
\setuphead[subsubsection]     [placehead=yes]

\starttext

\section{} % hidden 8th section

\subsection{} % hidden 3rd section

\subsubsection{This is complete numbering of subsubsection} % view 9.4.6 subsubsection

\stoptext

produces

</cd:example><cd:example title="Modifying the page before a chapter">Here is an example which shows how you can change the background color of an empty page before the chapter title.

% next five lines just to show the effect on this wiki
\setuppapersize[A8][A5,landscape]
\setuppaper[nx=4, ny=2]
\setuplayout[page][location=middle, marking=on]
\setuparranging [XY]
\setupbodyfont[6pt]

% actual example starts here
\setuppagenumbering
  [alternative=doublesided]

\startsetups [chapter:before]
  \doifoddpageelse
    {}
    {\pushbackground[page]
     \setupbackgrounds[page][background=color,backgroundcolor=gray]
     \page[right]
     \popbackground}
\stopsetups

\setuphead
  [chapter]
  [page=yes,
   before=\directsetup{chapter:before}]

\starttext

\startchapter[title={Knuth}]
\dorecurse{2}{\samplefile{knuth}}
\stopchapter

\startchapter[title={Ward}]
\dorecurse{1}{\samplefile{ward}}
\stopchapter

\startchapter[title={Zapf}]
\dorecurse{2}{\samplefile{zapf}}
\stopchapter


\stoptext

produces

The command \pushbackground stores the values of the background which is modified. After the execution of \page[right] the old values of background are restored by \popbackground. </cd:example><cd:example title="Special facing pages for chapters">On March 7, 2022, Julian asked on the mailing list about some method to place an image on the facing page of each chapter in a (double-sided) book. Chapters might also end on an even (equivalently, left) page, in which case, an empty right (odd) page should be introduced after so that the next chapter still has its image on its facing (left) page. (https://www.mail-archive.com/ntg-context@ntg.nl/msg101455.html)

In the discussion that ensued, Wolfgang posted the following elegant solution using \definepageinjection [slightly re-formatted from (https://www.mail-archive.com/ntg-context@ntg.nl/msg101462.html)] —

% next five lines just to show the effect on this wiki
\setuppapersize[A8][A5,landscape]
\setuppaper[nx=4, ny=2]
\setuplayout[page][location=middle, marking=on]
\setuparranging [XY]
\setupbodyfont[6pt]

% actual example starts here
\setupexternalfigures
   [location=default]

\setuppagenumbering
   [alternative=doublesided]

\definepageinjection
   [chapter:start]
   [empty]
   [page=left]

\definepageinjection
   [chapter:insert]
   [previouspage]
   [pagestate=stop,width=\paperwidth]

\setuphead
   [chapter]
   [beforesection={\pageinjection[chapter:start]},
    insidesection={\pageinjection[chapter:insert][name=\structureuservariable{image}]}]

\starttext

\startchapter [title={Mill}] [image=cow]
\dorecurse{2}{\samplefile{lorem}}
\stopchapter

\startchapter [title={Mill}] [image=hacker]
\dorecurse{3}{\samplefile{lorem}}
\stopchapter

\startchapter [title={Mill}] [image=mill]
\dorecurse{2}{\samplefile{lorem}}
\stopchapter
\stoptext

which produces

</cd:example></cd:examples> <cd:notes></cd:notes> <cd:seealso> <cd:commandref name="definehead" originator="system"></cd:commandref> <cd:commandref name="page" originator="system"></cd:commandref> <cd:commandref name="setupalign" originator="system"></cd:commandref> <cd:commandref name="setuptolerance" originator="system"></cd:commandref> <cd:source file="strc-sec.mkiv" originator="system"></cd:source> <cd:wikipage originator="system" page="Category:Structure"></cd:wikipage></cd:seealso> </cd:commandgroup>