Difference between revisions of "Command/ startsection"

From Wiki
Jump to navigation Jump to search
(Created page with "Documentation for \start<i>section</i> ... \stop<i>section</i>")
 
(Added note about namedstructureuservariable)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<?xml version='1.0'?>
 
<!-- this file was generated on 2020-08-20T09:05 -->
 
 
<cd:commandgroup generated="yes" name="section" type="environment" xmlns:cd="http://wiki.contextgarden.net/commanddoc/20200807">
 
<cd:commandgroup generated="yes" name="section" type="environment" xmlns:cd="http://wiki.contextgarden.net/commanddoc/20200807">
<cd:shortdesc>
+
<cd:shortdesc><!-- a short command summary goes here -->
<!-- a short command summary goes here -->
+
The instances of  <tt>\start<i>section</i> ... \stop<i>section</i></tt> are used for wrapping a section text in an environment and typesetting its title.
The instances of  <tt>\start<i>section</i> ... \stop<i>section</i></tt> are used for ...
 
 
</cd:shortdesc>
 
</cd:shortdesc>
 
<cd:sequence>
 
<cd:sequence>
Line 10: Line 7:
 
   </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 28: Line 25:
 
   <cd:arguments>
 
   <cd:arguments>
 
     <cd:assignments list="yes" optional="yes" ordinal="1">
 
     <cd:assignments list="yes" optional="yes" ordinal="1">
     <cd:assignmentsdoc></cd:assignmentsdoc>
+
     <cd:assignmentsdoc>The first argument defines the visible and cross-referencing properties of the section. The argument values can be recalled with the {{cmd|namedstructurevariable}} command.</cd:assignmentsdoc>
 
     <cd:parameter name="title">
 
     <cd:parameter name="title">
       <cd:paramdoc></cd:paramdoc>
+
       <cd:paramdoc>is the title that will be used to create the section heading.  Alternative versions of the title may also be specified, as explained below. The main title is used if these are not specified.
 +
 
 +
If you need a line break in a title, you can use <tt>\\</tt>, it will create a line break on location, but a space in list and marking context. Unfortunately it will appear literally in 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="bookmark">
 
     <cd:parameter name="bookmark">
       <cd:paramdoc></cd:paramdoc>
+
       <cd:paramdoc>is used in PDF bookmarks, if enabled (see {{cmd|setupinteraction}} and {{cmd|placebookmarks}}). </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>is used in headers and 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>is used in combined-lists (i.e. the table of contents).</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>specifies the reference-key for use with cross-referencing commands (see {{cmd|at}} and {{cmd|in}}).</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>a sectioning number to use instead of the calculated one.</cd:paramdoc>
 
       <cd:constant type="cd:text"></cd:constant>
 
       <cd:constant type="cd:text"></cd:constant>
 
     </cd:parameter>
 
     </cd:parameter>
Line 59: Line 58:
 
     </cd:assignments>
 
     </cd:assignments>
 
     <cd:assignments list="yes" optional="yes" ordinal="2">
 
     <cd:assignments list="yes" optional="yes" ordinal="2">
     <cd:assignmentsdoc></cd:assignmentsdoc>
+
     <cd:assignmentsdoc>The second, optional, argument allows section-local user-variables to be assigned.  The values of these variables can be recalled with the {{cmd|structureuservariable}} command or the {{cmd|namedstructureuservariable}} command.
 +
</cd:assignmentsdoc>
 
     <cd:parameter name="cd:key">
 
     <cd:parameter name="cd:key">
 
       <cd:paramdoc></cd:paramdoc>
 
       <cd:paramdoc></cd:paramdoc>
Line 68: Line 68:
 
   </cd:command>
 
   </cd:command>
 
</cd:variants>
 
</cd:variants>
<cd:description>
+
<cd:description>This family of commands are only available in ConTeXt MkIV.  They supersede the sectioning commands {{cmd|part}}, {{cmd|chapter}}, {{cmd|section}}, {{cmd|subsection}}, {{cmd|subsubsection}}, {{cmd|title}}, {{cmd|subject}}, {{cmd|subsubject}}, and {{cmd|subsubsubject}}.
<!-- the long description of the command goes here -->
+
 
 +
The new commands, collectively documented here, are {{cmd|startpart}}, {{cmd|startchapter}}, {{cmd|startsection}}, {{cmd|startsubsection}}, {{cmd|startsubsubsection}}, {{cmd|starttitle}}, {{cmd|startsubject}}, {{cmd|startsubsubject}}, and {{cmd|startsubsubsubject}}.  These more verbose commands apply an environment (\start- and \stop-) approach to sectioning, which is more friendly to tagged-PDF, ePUB and XML output.
 +
 
 +
Sectioning is hierarchical.  Numbered ''parts'' are divided into numbered ''chapters'', themselves divided into numbered ''sections'', ''subsections'', and ''subsubsections'' etc.  Chapters and sections etc. have unnumbered counterparts called ''titles'', ''subjects'', ''subsubjects'', and ''subsubsubjects'' etc., respectively.  (There are actually a couple more sub-levels than listed here.)  ''Chapters'' start a new page (by default—this is easily configurable).  ''Parts'' are unusual in two respects: firstly, there is no unnumbered counterpart to parts; and secondly, the title of a part is not typeset automatically, as it will generally require special attention and design.
 +
 
 +
Additional section types can be defined (based on one of the existing sections) with the {{cmd|definehead}} command.  A user-defined section type will have its own \start- and \stop<i>section</i> commands, in addition to a traditional \<i>section</i> command.  These new commands will behave as documented here
 +
 
 +
The typesetting of section types (both built-in and user-defined) can be controlled with the {{cmd|setupheads}} and {{cmd|setuphead}} commands.
 +
 
 +
 
 
</cd:description>
 
</cd:description>
<cd:examples>
+
<cd:examples><cd:example title=""><context source="yes" text="produces">
<!--  command example(s)
+
\setuppapersize[A6,landscape]
<cd:example title="">
+
\starttext
</cd:example>
+
 
-->
+
\startsection[
</cd:examples>
+
    reference=sec:One,
<cd:notes>
+
    title={Section One},
<!--  this is for special remarks that do not fit elsewhere, like discovered bugs in specific context versions
+
]
<cd:note author="..." date="...">
+
 
</cd:note>
+
For a subsection, see \in{subsection}[sec:Two:Sec].
-->
+
 
</cd:notes>
+
\stopsection
 +
 
 +
\startsection[
 +
    reference=sec:Two,
 +
    title={Section Two},
 +
]
 +
[a_variable={some value}]
 +
 
 +
a_variable=\quote{\structureuservariable{a_variable}};
 +
the_title = \quote{\namedstructurevariable{section}{title}}.
 +
 
 +
\startsubsection[
 +
    reference=sec:Two:Sec,
 +
    title={Here’s a subsection},
 +
]
 +
 
 +
In this subsection there’s some text\ldots
 +
 
 +
\stopsubsection
 +
\stopsection
 +
\stoptext
 +
</context>
 +
</cd:example><cd:example title=""><context source="yes" text="produces">
 +
\setuppapersize[A6,landscape]
 +
\setuphead[chapter][page=no]
 +
\starttext
 +
 
 +
\startpart[title={Part}]
 +
\startchapter[title={Chapter}]
 +
\startsection[title={Section}]
 +
\startsubsection[title={Subsection}]
 +
\startsubsubsection[title={Subsubsection}]
 +
\startsubsubsubsection[title={Subsubsubsection}]
 +
\startsubsubsubsubsection[title={Subsubsubsubsection}]
 +
 
 +
\stopsubsubsubsubsection
 +
\stopsubsubsubsection
 +
\stopsubsubsection
 +
\stopsubsection
 +
\stopsection
 +
\stopchapter
 +
\stoppart
 +
\stoptext
 +
</context>
 +
</cd:example></cd:examples>
 +
<cd:notes></cd:notes>
 
<cd:seealso>
 
<cd:seealso>
<!-- one or more of these:
+
<cd:commandref name="_section" originator="system">for the superceded commands</cd:commandref>
<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="_section" originator="system"></cd:commandref>
 
 
<cd:commandref name="definehead" originator="system"></cd:commandref>
 
<cd:commandref name="definehead" originator="system"></cd:commandref>
 
<cd:commandref name="setuphead" originator="system"></cd:commandref>
 
<cd:commandref name="setuphead" originator="system"></cd:commandref>
<cd:source file="strc-sec.mkiv" originator="system"></cd:source>  
+
<cd:commandref name="setupheads"></cd:commandref>
<cd:wikipage originator="system" page="Category:Structure"></cd:wikipage>  
+
<cd:source file="strc-sec.mkiv" originator="system"></cd:source>
</cd:seealso>
+
<cd:wikipage originator="system" page="Category:Structure"></cd:wikipage>
 +
<cd:wikipage page="Titles"></cd:wikipage></cd:seealso>
 
</cd:commandgroup>
 
</cd:commandgroup>

Latest revision as of 08:38, 14 January 2022


\startsection ... \stopsection

Summary

The instances of \startsection ... \stopsection are used for wrapping a section text in an environment and typesetting its title.

Instances

\startpart ... \stopparthighest level of sectioning
\startchapter ... \stopchapterlevel 2
\startsection ... \stopsectionlevel 3
\startsubsection ... \stopsubsectionlevel 4
\startsubsubsection ... \stopsubsubsectionlevel 5
\startsubsubsubsection ... \stopsubsubsubsectionlevel 6
\startsubsubsubsubsection ... \stopsubsubsubsubsectionlevel 7
\starttitle ... \stoptitlelevel 2, unnumbered
\startsubject ... \stopsubjectlevel 3, unnumbered
\startsubsubject ... \stopsubsubjectlevel 4, unnumbered
\startsubsubsubject ... \stopsubsubsubjectlevel 5, unnumbered
\startsubsubsubsubject ... \stopsubsubsubsubjectlevel 6, unnumbered
\startsubsubsubsubsubject ... \stopsubsubsubsubsubjectlevel 7, unnumbered

Settings instance

\startSECTION[...=...,...][...=...,...] ... \stopSECTION
titletext
bookmarktext
markingtext
listtext
referencereference
ownnumbertext
placeholdertext
keyvalue

OptionExplanation
The first argument defines the visible and cross-referencing properties of the section. The argument values can be recalled with the \namedstructurevariable command.
title
is the title that will be used to create the section heading. Alternative versions of the title may also be specified, as explained below. The main title is used if these are not specified. If you need a line break in a title, you can use \\, it will create a line break on location, but a space in list and marking context. Unfortunately it will appear literally in PDF bookmarks.
bookmark
is used in PDF bookmarks, if enabled (see \setupinteraction and \placebookmarks).
marking
is used in headers and footers.
list
is used in combined-lists (i.e. the table of contents).
reference
specifies the reference-key for use with cross-referencing commands (see \at and \in).
ownnumber
a sectioning number to use instead of the calculated one.
The second, optional, argument allows section-local user-variables to be assigned. The values of these variables can be recalled with the \structureuservariable command or the \namedstructureuservariable command.

Description

This family of commands are only available in ConTeXt MkIV. They supersede the sectioning commands \part, \chapter, \section, \subsection, \subsubsection, \title, \subject, \subsubject, and \subsubsubject.

The new commands, collectively documented here, are \startpart, \startchapter, \startsection, \startsubsection, \startsubsubsection, \starttitle, \startsubject, \startsubsubject, and \startsubsubsubject. These more verbose commands apply an environment (\start- and \stop-) approach to sectioning, which is more friendly to tagged-PDF, ePUB and XML output.

Sectioning is hierarchical. Numbered parts are divided into numbered chapters, themselves divided into numbered sections, subsections, and subsubsections etc. Chapters and sections etc. have unnumbered counterparts called titles, subjects, subsubjects, and subsubsubjects etc., respectively. (There are actually a couple more sub-levels than listed here.) Chapters start a new page (by default—this is easily configurable). Parts are unusual in two respects: firstly, there is no unnumbered counterpart to parts; and secondly, the title of a part is not typeset automatically, as it will generally require special attention and design.

Additional section types can be defined (based on one of the existing sections) with the \definehead command. A user-defined section type will have its own \start- and \stopsection commands, in addition to a traditional \section command. These new commands will behave as documented here

The typesetting of section types (both built-in and user-defined) can be controlled with the \setupheads and \setuphead commands.


Examples

Example 1

\setuppapersize[A6,landscape]
\starttext

\startsection[
    reference=sec:One,
    title={Section One},
]

For a subsection, see \in{subsection}[sec:Two:Sec].

\stopsection

\startsection[
    reference=sec:Two,
    title={Section Two},
]
[a_variable={some value}]

a_variable=\quote{\structureuservariable{a_variable}};
the_title = \quote{\namedstructurevariable{section}{title}}.

\startsubsection[
    reference=sec:Two:Sec,
    title={Here’s a subsection},
]

In this subsection there’s some text\ldots

\stopsubsection
\stopsection
\stoptext

produces

Example 2

\setuppapersize[A6,landscape]
\setuphead[chapter][page=no]
\starttext

\startpart[title={Part}]
\startchapter[title={Chapter}]
\startsection[title={Section}]
\startsubsection[title={Subsection}]
\startsubsubsection[title={Subsubsection}]
\startsubsubsubsection[title={Subsubsubsection}]
\startsubsubsubsubsection[title={Subsubsubsubsection}]

\stopsubsubsubsubsection
\stopsubsubsubsection
\stopsubsubsection
\stopsubsection
\stopsection
\stopchapter
\stoppart
\stoptext

produces

Notes

See also

Help from ConTeXt-Mailinglist/Forum

All issues with: