Difference between revisions of "Description"

From ConTeXt wiki
m (Changed multi-paragraph ConTeXt example to work with MkIV. Use "location=hanging" for MkII)
m (Make example narrower. Reduce them to <context source=yes> instead of <texcode>+<context>.)
Line 2: Line 2:
  
 
{{Todo|descriptions and enumerations in mkiv share the same base, and all "location" values are now set with "alternative". Are there other changes? The present page (as well as the command syntax documentation) needs to be updated.}}
 
{{Todo|descriptions and enumerations in mkiv share the same base, and all "location" values are now set with "alternative". Are there other changes? The present page (as well as the command syntax documentation) needs to be updated.}}
 +
  
 
= Basic Description Lists =
 
= Basic Description Lists =
Line 7: Line 8:
 
== LaTeX ==
 
== LaTeX ==
  
LaTeX provides a <tt>description</tt> environment, which works just like an itemized or enumerated list except that the item labels are specified by an (optional) argument to the <tt>\item</tt> command, rather than being automatically generated.  This is useful for making lists of definitions and other sorts of descriptions that are headed by a keyword.
+
LaTeX provides a <tt>description</tt> environment, which works just like an itemized or enumerated list except that the item labels are specified by an (optional) argument to the {{cmd|item}} command, rather than being automatically generated.  This is useful for making lists of definitions and other sorts of descriptions that are headed by a keyword.
  
 
<texcode>
 
<texcode>
Line 13: Line 14:
 
\begin{document}
 
\begin{document}
 
\begin{description}
 
\begin{description}
\item[Short] This is a shorter item label, and some text that talks about it.
+
    \item[Short] This is a shorter item label, and some text that talks
The text is wrapped into a paragraph, with successive lines indented.
+
        about it. The text is wrapped into a paragraph, with successive
\item[Rather longer label] This is a longer item label.  As you can see, the
+
        lines indented.
text is not started a specified distance in -- unlike with other lists -- but
+
    \item[Rather longer label] This is a longer item label.  As you can
is spaced a fixed distance from the end of the label.
+
        see, the text is not started a specified distance in -- unlike
 +
        with other lists -- but is spaced a fixed distance from the end
 +
        of the label.
 
\end{description}
 
\end{description}
 
\end{document}
 
\end{document}
Line 24: Line 27:
 
== ConTeXt ==
 
== ConTeXt ==
  
ConTeXt provides a similar mechanism.  Unlike the LaTeX version, ConTeXt's description mechanism does not enclose the items in an environment, but instead formats them independently according to formats given in <cmd>setupdescriptions</cmd> or <cmd>definedescription</cmd>.  The <cmd>definedescription</cmd> latter command is used to define a named description class, which can later be called using its name.  This example defines a <tt>latexdesc</tt> description, with parameters that roughly approximate the LaTeX defaults.
+
ConTeXt provides a similar mechanism.  Unlike the LaTeX version, ConTeXt's description mechanism does not enclose the items in an environment, but instead formats them independently according to formats given in {{cmd|setupdescriptions}} or {{cmd|definedescription}}.  The {{cmd|definedescription}} latter command is used to define a named description class, which can later be called using its name.  This example defines a <tt>latexdesc</tt> description, with parameters that roughly approximate the LaTeX defaults.
 
 
<texcode>
 
\definedescription[latexdesc][
 
  headstyle=bold,style=normal,align=left,location=hanging,
 
  width=broad,margin=1cm]
 
 
 
\starttext
 
\latexdesc{Short} This is a shorter item label, and some text that talks about it.
 
The text is wrapped into a paragraph, with successive lines indented.
 
 
 
\latexdesc{Rather longer label} This is a longer item label.  As you can see, the
 
text is not started a specified distance in -- unlike with other lists -- but
 
is spaced a fixed distance from the end of the label.
 
 
 
\stoptext
 
</texcode>
 
  
<context>
+
<context source=yes>
\setuplayout[width=13cm]
+
\setuppapersize[A5]
 
\definedescription[latexdesc][
 
\definedescription[latexdesc][
  headstyle=bold,style=normal,align=left,location=hanging,
+
    headstyle=bold, style=normal, align=left, location=hanging,  
  width=broad,margin=1cm]
+
    width=broad, margin=1cm]
  
 
\starttext
 
\starttext
\latexdesc{Short} This is a shorter item label, and some text that talks about it.
+
\latexdesc{Short} This is a shorter item label, and some text that  
The text is wrapped into a paragraph, with successive lines indented.
+
    talks about it. The text is wrapped into a paragraph, with  
 
+
    successive lines indented.
\latexdesc{Rather longer label} This is a longer item label.  As you can see, the
 
text is not started a specified distance in -- unlike with other lists -- but
 
is spaced a fixed distance from the end of the label.
 
  
 +
\latexdesc{Rather longer label} This is a longer item label. As you
 +
    can see, the text is not started a specified distance in -- unlike
 +
    with other lists -- but is spaced a fixed distance from the end of
 +
    the label.
 
\stoptext
 
\stoptext
 
</context>
 
</context>
  
The empty lines (or <cmd>par</cmd>) after each description (here, <tt>\latexdesc</tt>) line are required.
+
The empty lines (or {{cmd|par}}) after each description (here, <tt>\latexdesc</tt>) line are required.
  
 
The <tt>margin=<i>dimension</i></tt> key specifies the hanging indentation for lines after the first line.  In addition, the separation between the label and the text can be specified using a <tt>distance=<i>dimension</i></tt> key.
 
The <tt>margin=<i>dimension</i></tt> key specifies the hanging indentation for lines after the first line.  In addition, the separation between the label and the text can be specified using a <tt>distance=<i>dimension</i></tt> key.
 +
  
 
= Multi-Paragraph Descriptions =
 
= Multi-Paragraph Descriptions =
Line 95: Line 84:
 
Multiple paragraphs (without first line indenting) can be created as follows:
 
Multiple paragraphs (without first line indenting) can be created as follows:
  
<texcode>
+
<context source=yes>
 +
\setuppapersize[A5]
 
\definedescription[descr][
 
\definedescription[descr][
  headstyle=bold]
+
   headstyle=bold, style=normal, align=left, location=hanging,  
 
+
   width=broad, margin=1cm]
\setupdescriptions[descr][
 
   headstyle=bold,style=normal,alternative=hanging,
 
   width=fit,margin=1cm]
 
  
 
\starttext
 
\starttext
Line 110: Line 97:
 
   This is another paragraph under the "Para" item.
 
   This is another paragraph under the "Para" item.
 
   \startdescr{Sub Item}   
 
   \startdescr{Sub Item}   
     This is a description of an item which is within the
+
     This is a description of an item which is within the "Para" item.
    "Para" item.
 
 
   \stopdescr
 
   \stopdescr
 
   \startdescr{Sub Item}  
 
   \startdescr{Sub Item}  
Line 122: Line 108:
  
 
\stoptext
 
\stoptext
</texcode>
+
</context>
 
 
<context>
 
\setuplayout[width=13cm]
 
\definedescription[descr][
 
  headstyle=bold,style=normal,align=left,location=hanging,
 
  width=broad,margin=1cm]
 
 
 
\starttext
 
\startdescr{Para}
 
  This is a shorter item label, and some text that talks about it.
 
  The text is wrapped into a paragraph, with successive lines indented.
 
  
  This is another paragraph under the "Para" item.
 
  \startdescr{Sub Item} 
 
    This is a description of an item which is within the
 
    "Para" item.
 
  \stopdescr
 
  \startdescr{Sub Item}
 
    Another Sub Item
 
  \stopdescr
 
\stopdescr
 
\startdescr{Short}
 
  A short item that's not part of that really long "Para" item.
 
\stopdescr
 
 
\stoptext
 
</context>
 
  
 
= Descriptions with Fixed Label Width =
 
= Descriptions with Fixed Label Width =
Line 163: Line 123:
 
\begin{basedescript}{\desclabelstyle{\pushlabel}\desclabelwidth{6em}}
 
\begin{basedescript}{\desclabelstyle{\pushlabel}\desclabelwidth{6em}}
 
\item[Short]  This is a shorter item label, and some text that talks about it.
 
\item[Short]  This is a shorter item label, and some text that talks about it.
  The text is wrapped into a paragraph, with successive lines indented.
+
    The text is wrapped into a paragraph, with successive lines indented.
 
\item[Rather longer label] This is a longer item label.  As you can see, the
 
\item[Rather longer label] This is a longer item label.  As you can see, the
  text is not started a specified distance in -- unlike with other lists -- but
+
    paragraph simply starts 6em in.
  is spaced a fixed distance from the end of the label.
 
 
\end{basedescript}
 
\end{basedescript}
 
\end{document}
 
\end{document}
 
</texcode>
 
</texcode>
 
  
 
== ConTeXt ==
 
== ConTeXt ==
Line 177: Line 135:
 
sets the label to 5em:
 
sets the label to 5em:
  
<texcode>
+
<context source=yes>
\definedescription[notation][
+
\setuppapersize[A5]
  headstyle=bold,style=normal,align=left,location=hanging,
 
  width=5em]
 
</texcode>
 
  
<context>
 
 
\definedescription[notation][
 
\definedescription[notation][
   headstyle=bold,style=normal,align=left,location=hanging,
+
   headstyle=bold, style=normal, align=left, location=hanging,  
 
   width=5em]
 
   width=5em]
  
 
\starttext
 
\starttext
\notation{Short} This is a shorter item label, and some text that talks about it.
+
\notation{Short} This is a shorter item label, and some text that talks
The text is wrapped into a paragraph, with successive lines indented.
+
    about it. The text is wrapped into a paragraph, with successive
 +
    lines indented.
  
\notation{Rather longer label} This is a longer item label.  As you can see, the
+
\notation{Rather longer label} This is a longer item label.  As you can
text is not started a specified distance in -- unlike with other lists -- but
+
    see, the paragraph simply pretends the label is 5em wide.
is spaced a fixed distance from the end of the label.
 
  
 
\stoptext
 
\stoptext
Line 200: Line 154:
  
 
Another example:
 
Another example:
<texcode>
 
\definedescription
 
[Desc]
 
[location=top,hang=20,
 
headstyle={\bf\color[blue]},
 
command=\hskip-1cm,margin=1cm]
 
</texcode>
 
 
Gives the result:
 
  
<context>
+
<context source=yes>
 +
\setuppapersize[A5]
 
\setupcolors[state=start]
 
\setupcolors[state=start]
\definedescription[Desc][location=top,hang=20,
+
\definedescription[Desc][location=top, hang=20,
headstyle={\bf\color[blue]},
+
    headstyle={\bf\color[blue]},
command=\hskip-1cm,margin=1cm]
+
    command=\hskip-1cm, margin=1cm]
  
 
\starttext
 
\starttext
\Desc{Short} This is a shorter item label, and some text that talks about it.
+
\Desc{Short} This item's short label is set above the paragraph. The
The text is wrapped into a paragraph, with successive lines indented.
+
    paragraph starts 1cm in.
  
\Desc{Rather longer label} This is a longer item label.  As you can see, the
+
\Desc{Rather longer label} This item's rather longer label is also set
text is not started a specified distance in -- unlike with other lists -- but
+
    above the paragraph. The paragraph starts 1cm in.
is spaced a fixed distance from the end of the label.
 
  
 
\stoptext
 
\stoptext
Line 228: Line 173:
  
 
== See also ==
 
== See also ==
{{cmd|definedescription}}, {{cmd|startdescription}}
+
* {{cmd|definedescription}}
 +
* {{cmd|startdescription}}

Revision as of 11:39, 11 June 2012

< From LaTeX to ConTeXt | Structurals >


TODO: descriptions and enumerations in mkiv share the same base, and all "location" values are now set with "alternative". Are there other changes? The present page (as well as the command syntax documentation) needs to be updated. (See: To-Do List)



Basic Description Lists

LaTeX

LaTeX provides a description environment, which works just like an itemized or enumerated list except that the item labels are specified by an (optional) argument to the \item command, rather than being automatically generated. This is useful for making lists of definitions and other sorts of descriptions that are headed by a keyword.

\documentclass{article}
\begin{document}
\begin{description}
    \item[Short] This is a shorter item label, and some text that talks
        about it. The text is wrapped into a paragraph, with successive
        lines indented.
    \item[Rather longer label] This is a longer item label.  As you can
        see, the text is not started a specified distance in -- unlike
        with other lists -- but is spaced a fixed distance from the end
        of the label.
\end{description}
\end{document}

ConTeXt

ConTeXt provides a similar mechanism. Unlike the LaTeX version, ConTeXt's description mechanism does not enclose the items in an environment, but instead formats them independently according to formats given in \setupdescriptions or \definedescription. The \definedescription latter command is used to define a named description class, which can later be called using its name. This example defines a latexdesc description, with parameters that roughly approximate the LaTeX defaults.

\setuppapersize[A5]
\definedescription[latexdesc][
    headstyle=bold, style=normal, align=left, location=hanging, 
    width=broad, margin=1cm]

\starttext
\latexdesc{Short} This is a shorter item label, and some text that 
    talks about it. The text is wrapped into a paragraph, with 
    successive lines indented.

\latexdesc{Rather longer label} This is a longer item label. As you 
    can see, the text is not started a specified distance in -- unlike 
    with other lists -- but is spaced a fixed distance from the end of 
    the label.
\stoptext

The empty lines (or \par) after each description (here, \latexdesc) line are required.

The margin=dimension key specifies the hanging indentation for lines after the first line. In addition, the separation between the label and the text can be specified using a distance=dimension key.


Multi-Paragraph Descriptions

LaTeX

Because the LaTeX description mechanism is an environment, it is simple to include multiple paragraphs in a description environment, or even to embed sub-lists. For instance, consider the following example:

\documentclass{article}
\begin{document}
\begin{description}
\item[Para] This is a shorter item label, and some text that talks about it.
   The text is wrapped into a paragraph, with successive lines indented.

   This is another paragraph under the "Para" item.

   \begin{description}
   \item[Sub-Item] This is a description of an item which is within the
      "Para" item.

   \item[Sub-Item] Another sub-item.
   \end{description}
\item[Short] A short item that's not part of that really long "Para" item.
\end{description}
\end{document}

In this example, the code indentation has been used to illustrate the alignment of the typeset output. Everything between \item[Para] and \item[Short] is part of the "Para" item, and is indented by the same amount. The embedded description then embeds any following lines on the "Sub-Item"s by an additional indentation, as one would expect.

ConTeXt

Multiple paragraphs (without first line indenting) can be created as follows:

\setuppapersize[A5]
\definedescription[descr][
  headstyle=bold, style=normal, align=left, location=hanging, 
  width=broad, margin=1cm]

\starttext
\startdescr{Para}
  This is a shorter item label, and some text that talks about it.
  The text is wrapped into a paragraph, with successive lines indented.

  This is another paragraph under the "Para" item.
  \startdescr{Sub Item}  
    This is a description of an item which is within the "Para" item.
  \stopdescr
  \startdescr{Sub Item} 
    Another Sub Item 
  \stopdescr
\stopdescr
\startdescr{Short}
  A short item that's not part of that really long "Para" item.
\stopdescr

\stoptext


Descriptions with Fixed Label Width

LaTeX

In LaTeX, the mdwlist package can be used to set a fixed label width.

\documentclass{article}
\usepackage{mdwlist}
\begin{document}
\begin{basedescript}{\desclabelstyle{\pushlabel}\desclabelwidth{6em}}
\item[Short]  This is a shorter item label, and some text that talks about it.
    The text is wrapped into a paragraph, with successive lines indented.
\item[Rather longer label] This is a longer item label.  As you can see, the
    paragraph simply starts 6em in.
\end{basedescript}
\end{document}

ConTeXt

Using an explicit dimension as argument for the 'width' parameter sets the label to 5em:

\setuppapersize[A5]

\definedescription[notation][
  headstyle=bold, style=normal, align=left, location=hanging, 
  width=5em]

\starttext
\notation{Short} This is a shorter item label, and some text that talks
    about it. The text is wrapped into a paragraph, with successive
    lines indented.

\notation{Rather longer label} This is a longer item label.  As you can
    see, the paragraph simply pretends the label is 5em wide.

\stoptext

Another example:

\setuppapersize[A5]
\setupcolors[state=start]
\definedescription[Desc][location=top, hang=20,
    headstyle={\bf\color[blue]},
    command=\hskip-1cm, margin=1cm]

\starttext
\Desc{Short} This item's short label is set above the paragraph. The
    paragraph starts 1cm in.

\Desc{Rather longer label} This item's rather longer label is also set
    above the paragraph. The paragraph starts 1cm in.

\stoptext

See also