Difference between revisions of "Command/ section"

From Wiki
Jump to navigation Jump to search
(Created page with "Documentation for \<i>section</i>")
 
(combined all the separate pages)
 
Line 4: Line 4:
 
<cd:shortdesc>
 
<cd:shortdesc>
 
<!-- a short command summary goes here -->
 
<!-- a short command summary goes here -->
−
The instances of  <tt>\<i>section</i></tt> are used for ...
+
The instances of  <tt>\<i>section</i></tt> produce a sectioning title.
 
</cd:shortdesc>
 
</cd:shortdesc>
 
<cd:sequence>
 
<cd:sequence>
Line 10: Line 10:
 
   </cd:sequence>
 
   </cd:sequence>
 
<cd:instances>
 
<cd:instances>
−
     <cd:constant value="part"></cd:constant>
+
     <cd:constant value="part">highest level of sectioning</cd:constant>
−
     <cd:constant value="chapter"></cd:constant>
+
     <cd:constant value="chapter">level 2</cd:constant>
−
     <cd:constant value="section"></cd:constant>
+
     <cd:constant value="section">level 3</cd:constant>
−
     <cd:constant value="subsection"></cd:constant>
+
     <cd:constant value="subsection">level 4</cd:constant>
−
     <cd:constant value="subsubsection"></cd:constant>
+
     <cd:constant value="subsubsection">level 5</cd:constant>
−
     <cd:constant value="subsubsubsection"></cd:constant>
+
     <cd:constant value="subsubsubsection">level 6</cd:constant>
−
     <cd:constant value="subsubsubsubsection"></cd:constant>
+
     <cd:constant value="subsubsubsubsection">level 7</cd:constant>
−
     <cd:constant value="title"></cd:constant>
+
     <cd:constant value="title">level 2, unnumbered</cd:constant>
−
     <cd:constant value="subject"></cd:constant>
+
     <cd:constant value="subject">level 3, unnumbered</cd:constant>
−
     <cd:constant value="subsubject"></cd:constant>
+
     <cd:constant value="subsubject">level 4, unnumbered</cd:constant>
−
     <cd:constant value="subsubsubject"></cd:constant>
+
     <cd:constant value="subsubsubject">level 5, unnumbered</cd:constant>
−
     <cd:constant value="subsubsubsubject"></cd:constant>
+
     <cd:constant value="subsubsubsubject">level 6, unnumbered</cd:constant>
−
     <cd:constant value="subsubsubsubsubject"></cd:constant>
+
     <cd:constant value="subsubsubsubsubject">level 7, unnumbered</cd:constant>
 
   </cd:instances>
 
   </cd:instances>
 
<cd:variants>
 
<cd:variants>
Line 29: Line 29:
 
     <cd:keywords list="yes" optional="yes" ordinal="1">
 
     <cd:keywords list="yes" optional="yes" ordinal="1">
 
     <cd:keywordsdoc></cd:keywordsdoc>
 
     <cd:keywordsdoc></cd:keywordsdoc>
−
     <cd:constant type="cd:reference"></cd:constant>
+
     <cd:constant type="cd:reference">Optional reference for referring to this sectioning head from elsewhere in the document</cd:constant>
 
     </cd:keywords>
 
     </cd:keywords>
 
     <cd:keywords delimiters="braces" ordinal="2">
 
     <cd:keywords delimiters="braces" ordinal="2">
 
     <cd:keywordsdoc></cd:keywordsdoc>
 
     <cd:keywordsdoc></cd:keywordsdoc>
−
     <cd:constant type="cd:text"></cd:constant>
+
     <cd:constant type="cd:text">The title to be typeset. Any numbering will be added automatically</cd:constant>
 
     </cd:keywords>
 
     </cd:keywords>
 
   </cd:arguments>
 
   </cd:arguments>
Line 42: Line 42:
 
     <cd:assignmentsdoc></cd:assignmentsdoc>
 
     <cd:assignmentsdoc></cd:assignmentsdoc>
 
     <cd:parameter name="title">
 
     <cd:parameter name="title">
−
       <cd:paramdoc></cd:paramdoc>
+
       <cd:paramdoc>The title to be typeset</cd:paramdoc>
 
       <cd:constant type="cd:text"></cd:constant>
 
       <cd:constant type="cd:text"></cd:constant>
 
     </cd:parameter>
 
     </cd:parameter>
 
     <cd:parameter name="bookmark">
 
     <cd:parameter name="bookmark">
−
       <cd:paramdoc></cd:paramdoc>
+
       <cd:paramdoc>The text for use in the table of contents and PDF bookmarks</cd:paramdoc>
 
       <cd:constant type="cd:text"></cd:constant>
 
       <cd:constant type="cd:text"></cd:constant>
 
     </cd:parameter>
 
     </cd:parameter>
 
     <cd:parameter name="marking">
 
     <cd:parameter name="marking">
−
       <cd:paramdoc></cd:paramdoc>
+
       <cd:paramdoc>The text to use for subsequent use in header or footers</cd:paramdoc>
 
       <cd:constant type="cd:text"></cd:constant>
 
       <cd:constant type="cd:text"></cd:constant>
 
     </cd:parameter>
 
     </cd:parameter>
 
     <cd:parameter name="list">
 
     <cd:parameter name="list">
−
       <cd:paramdoc></cd:paramdoc>
+
       <cd:paramdoc>A list to use instead of the standard list (same name as command itself)</cd:paramdoc>
 
       <cd:constant type="cd:text"></cd:constant>
 
       <cd:constant type="cd:text"></cd:constant>
 
     </cd:parameter>
 
     </cd:parameter>
 
     <cd:parameter name="reference">
 
     <cd:parameter name="reference">
−
       <cd:paramdoc></cd:paramdoc>
+
       <cd:paramdoc>A label to refer back to</cd:paramdoc>
 
       <cd:constant type="cd:reference"></cd:constant>
 
       <cd:constant type="cd:reference"></cd:constant>
 
     </cd:parameter>
 
     </cd:parameter>
 
     <cd:parameter name="ownnumber">
 
     <cd:parameter name="ownnumber">
−
       <cd:paramdoc></cd:paramdoc>
+
       <cd:paramdoc>Force a number</cd:paramdoc>
 
       <cd:constant type="cd:text"></cd:constant>
 
       <cd:constant type="cd:text"></cd:constant>
 
     </cd:parameter>
 
     </cd:parameter>
 
     <cd:parameter name="placeholder">
 
     <cd:parameter name="placeholder">
−
       <cd:paramdoc></cd:paramdoc>
+
       <cd:paramdoc>Note sure what this does</cd:paramdoc>
 
       <cd:constant type="cd:text"></cd:constant>
 
       <cd:constant type="cd:text"></cd:constant>
 
     </cd:parameter>
 
     </cd:parameter>
Line 75: Line 75:
 
   <cd:arguments>
 
   <cd:arguments>
 
     <cd:keywords list="yes" optional="yes" ordinal="1">
 
     <cd:keywords list="yes" optional="yes" ordinal="1">
−
     <cd:keywordsdoc></cd:keywordsdoc>
+
     <cd:keywordsdoc>A label to refer back to</cd:keywordsdoc>
 
     <cd:constant type="cd:reference"></cd:constant>
 
     <cd:constant type="cd:reference"></cd:constant>
 
     </cd:keywords>
 
     </cd:keywords>
 
     <cd:keywords delimiters="braces" ordinal="2">
 
     <cd:keywords delimiters="braces" ordinal="2">
−
     <cd:keywordsdoc></cd:keywordsdoc>
+
     <cd:keywordsdoc>A forced number</cd:keywordsdoc>
 
     <cd:constant type="cd:number"></cd:constant>
 
     <cd:constant type="cd:number"></cd:constant>
 
     </cd:keywords>
 
     </cd:keywords>
 
     <cd:keywords delimiters="braces" ordinal="3">
 
     <cd:keywords delimiters="braces" ordinal="3">
−
     <cd:keywordsdoc></cd:keywordsdoc>
+
     <cd:keywordsdoc>The title to be typeset</cd:keywordsdoc>
 
     <cd:constant type="cd:text"></cd:constant>
 
     <cd:constant type="cd:text"></cd:constant>
 
     </cd:keywords>
 
     </cd:keywords>
Line 90: Line 90:
 
</cd:variants>
 
</cd:variants>
 
<cd:description>
 
<cd:description>
−
<!-- the long description of the command goes here -->
+
Any of the three macro calls above can be used. The [[#Settings instance:assignment]] gives the most control.
 +
 
 +
You can define heads yourself with {{cmd|definehead}}. You can change the appearance with {{cmd|setuphead}}.
 +
 
 +
<i>Note:</i> these instances are superseded by environments with the same basic name, see {{gen|startsection}}.
 
</cd:description>
 
</cd:description>
 
<cd:examples>
 
<cd:examples>
−
<!--  command example(s)
+
<cd:example>
−
<cd:example title="">
+
<context source="yes" text="produces">
 +
 
 +
\setuphead[chapter][page=no]
 +
 
 +
\starttext
 +
 
 +
\chapter{Once Upon A Time}
 +
 
 +
This is the simplest form of using a chapter.
 +
 
 +
\chapter[mykey]{Once Upon A Time 2}
 +
 
 +
But what if you want to refer to this chapter at another time?
 +
Give it a key! Before the chapter put something between brackets.
 +
That's your key. Now you can refer to it. See the next chapter,
 +
\in{chapter}[next].
 +
 
 +
\chapter[next]{After A While}
 +
 
 +
As we said earlier in chapter \in[mykey], we ...
 +
 
 +
As this example shows, use $\backslash$in[...] to refer to a chapter with
 +
that name.
 +
 
 +
\stoptext
 +
 
 +
</context>
 +
</cd:example>
 +
<cd:example title="Parts">
 +
By default {{cmd|part}} generates no title because most of the times these require special attention and a specific design. In the background however the part numbering is active and carries out several initialisations. The other section commands ''are'' set up to typeset a title.
 +
 
 +
<context source="yes">
 +
\setuppapersize[A7]
 +
 
 +
\part{One} % not typeset ...
 +
\chapter{My chapter} % ... but this is Chapter 1 in Part 1
 +
 
 +
\part{Two}
 +
\chapter{My chapter} % ... and this is Chapter 1 in Part 1
 +
 
 +
</context>
 +
</cd:example>
 +
<cd:example title="Unnumbered section heads">
 +
To remove the section number (as might be needed for Introduction) use one of the unnumbered instances (for example, use {{cmd|subject}} instead of {{cmd|section}}, or utilise the fact that no section numbers are used in the front matter:
 +
 
 +
<texcode>
 +
\starttext
 +
 
 +
\startfrontmatter
 +
    \section{Introduction}  % not numbered
 +
 
 +
    ...
 +
\stopfrontmatter
 +
 
 +
\startbodymatter
 +
    \section{Problem Statement}  % numbered
 +
    ...
 +
\stopbodymatter
 +
 
 +
\stoptext
 +
</texcode>
 +
</cd:example>
 +
<cd:example title="Use of ''ownnumber''">
 +
The options <cd:iref variant='instance:assignment' ordinal='1' name='ownnumber'/> and  <cd:iref variant='instance:ownnumber' ordinal='2'/> both allow you to insert a specific number. Behind the scenes, numbering continues as normal:
 +
<context source="yes">
 +
\section[title={My first section}]
 +
\section[title={My section},ownnumber={4}]
 +
\section[title={My third section}]
 +
</context>
 
</cd:example>
 
</cd:example>
−
-->
 
 
</cd:examples>
 
</cd:examples>
 
<cd:notes>
 
<cd:notes>
Line 105: Line 176:
 
</cd:notes>
 
</cd:notes>
 
<cd:seealso>
 
<cd:seealso>
−
<!-- one or more of these:
 
−
<cd:commandref name="xx"></cd:commandref>
 
−
<cd:wikipage  page="xx"></cd:wikipage>
 
−
<cd:url        url="https://xx"></cd:url>
 
−
<cd:manual    pdf="xx"></cd:manual>
 
−
<cd:source    file="xx"></cd:source>
 
−
-->
 
 
<cd:commandref name="_startsection" originator="system"></cd:commandref>
 
<cd:commandref name="_startsection" originator="system"></cd:commandref>
 
<cd:commandref name="definehead" originator="system"></cd:commandref>
 
<cd:commandref name="definehead" originator="system"></cd:commandref>
Line 117: Line 181:
 
<cd:source file="strc-sec.mkiv" originator="system"></cd:source>  
 
<cd:source file="strc-sec.mkiv" originator="system"></cd:source>  
 
<cd:wikipage originator="system" page="Category:Structure"></cd:wikipage>  
 
<cd:wikipage originator="system" page="Category:Structure"></cd:wikipage>  
 +
<cd:wikipage page="Titles"></cd:wikipage>
 
</cd:seealso>
 
</cd:seealso>
 
</cd:commandgroup>
 
</cd:commandgroup>

Latest revision as of 13:53, 20 August 2020


\section

Summary

The instances of \section produce a sectioning title.

Instances

\parthighest level of sectioning
\chapterlevel 2
\sectionlevel 3
\subsectionlevel 4
\subsubsectionlevel 5
\subsubsubsectionlevel 6
\subsubsubsubsectionlevel 7
\titlelevel 2, unnumbered
\subjectlevel 3, unnumbered
\subsubjectlevel 4, unnumbered
\subsubsubjectlevel 5, unnumbered
\subsubsubsubjectlevel 6, unnumbered
\subsubsubsubsubjectlevel 7, unnumbered

Settings instance

\SECTION[...,...]{...}
[...,...]reference
{...}text

OptionExplanation
reference Optional reference for referring to this sectioning head from elsewhere in the document
text The title to be typeset. Any numbering will be added automatically

Settings instance:assignment

\SECTION[...=...,...]
titletext
bookmarktext
markingtext
listtext
referencereference
ownnumbertext
placeholdertext

OptionExplanation
title
The title to be typeset
bookmark
The text for use in the table of contents and PDF bookmarks
marking
The text to use for subsequent use in header or footers
list
A list to use instead of the standard list (same name as command itself)
reference
A label to refer back to
ownnumber
Force a number
placeholder
Note sure what this does

Settings instance:ownnumber

\SECTION[...,...]{...}{...}
[...,...]reference
{...}number
{...}text

OptionExplanation
A label to refer back to
A forced number
The title to be typeset

Description

Any of the three macro calls above can be used. The #Settings instance:assignment gives the most control.

You can define heads yourself with \definehead. You can change the appearance with \setuphead.

Note: these instances are superseded by environments with the same basic name, see startsection.

Examples

Example 1


\setuphead[chapter][page=no]

\starttext

\chapter{Once Upon A Time}

This is the simplest form of using a chapter.

\chapter[mykey]{Once Upon A Time 2}

But what if you want to refer to this chapter at another time?
Give it a key! Before the chapter put something between brackets.
That's your key. Now you can refer to it. See the next chapter,
\in{chapter}[next].

\chapter[next]{After A While}

As we said earlier in chapter \in[mykey], we ...

As this example shows, use $\backslash$in[...] to refer to a chapter with
that name.

\stoptext

produces

Parts

By default \part generates no title because most of the times these require special attention and a specific design. In the background however the part numbering is active and carries out several initialisations. The other section commands are set up to typeset a title. 

\setuppapersize[A7]

\part{One} % not typeset ...
\chapter{My chapter} % ... but this is Chapter 1 in Part 1

\part{Two}
\chapter{My chapter} % ... and this is Chapter 1 in Part 1

Unnumbered section heads

To remove the section number (as might be needed for Introduction) use one of the unnumbered instances (for example, use \subject instead of \section, or utilise the fact that no section numbers are used in the front matter: 

\starttext

\startfrontmatter
    \section{Introduction}  % not numbered

    ...
\stopfrontmatter

\startbodymatter
    \section{Problem Statement}  % numbered
    ...
\stopbodymatter

\stoptext

Use of ownnumber

The options ownnumber in variant instance:assignment and [...] in variant instance:ownnumber both allow you to insert a specific number. Behind the scenes, numbering continues as normal: 

\section[title={My first section}]
\section[title={My section},ownnumber={4}]
\section[title={My third section}]

Notes

See also

Help from ConTeXt-Mailinglist/Forum

All issues with:

Retrieved from "https://wiki.contextgarden.net/index.php?title=Command/_section&oldid=30578"