path: root/doc/user/ref_chan

@Section
    @Title { Changing the appearance of citations and the reference list }
    @Tag { changeref }
@Begin
@PP
By default, citations appear like this @Cite { $kingston1995lout.expert },
and the reference list appears like the one at the end of this
document, with the entries numbered, and sorted by their @Code "@Tag"
options.  This section explains how to change all this, by setting
options in the setup file.
@PP
For a general introduction to setup files and their options, see
Section {@NumberOf setup}.  Here we just describe the setup
file options that relate to references.  Here they are, with their
default values:
@ID @OneRow @Code @Verbatim {
@MakeReferences { Yes }
@RefCiteStyle { [cite] }
@RefCiteLabels { @RefNum }
@RefNumbers { Arabic }
@RefListFormat { Labels }
@RefListLabels { [@RefNum] }
@RefListTitle { references }
@ChapRefListTitle { references }
@RefListIndent { 0c }
@RefListRightIndent { 0c }
@RefListGap { 1.00v }
@RefListFont { }
@RefListBreak { }
@RefListLabelWidth { 2.00f }
@RefListSortKey { @Tag }
}
references. @RawIndex { references }
references.makereferences @SubIndex { @Code "@MakeReferences" }
makereferences.references @Index { @Code "@MakeReferences" (references) }
Setting @Code "@MakeReferences" to @Code "No" will cause Lout to ignore
all citation symbols and omit all reference lists.
@PP
@Code "@RefCiteStyle" and @Code "@RefCiteLabels" combine to
references. @RawIndex { references }
references.refcitestyle @SubIndex { @Code "@RefCiteStyle" }
refcitestyle.references @Index { @Code "@RefCiteStyle" (references) }
determine the appearance of citations.  The result of each @Code "@Cite"
symbol is the value of @Code "@RefCiteStyle" with the @Code "cite"
symbol replaced by the object following the @Code "@Cite" symbol.  For
example, the default value shown above encloses each citation in
brackets.  The @Code "cite" symbol must appear exactly once within
{@Code "@RefCiteStyle"}.
@PP
@Code "@RefCiteLabels" determines the appearance of each label within
references. @RawIndex { references }
references.refcitelabels @SubIndex { @Code "@RefCiteLabels" }
refcitelabels.references @Index { @Code "@RefCiteLabels" (references) }
the citation.  Within it, the @Code "@RefNum" symbol will produce the
number of the reference, and you may also use any of the options of the
@Code "@Reference" symbol listed at the beginning of Section
{@NumberOf entries}:
@ID @OneRow @Tab
    @Fmta { @Col @Code A ! @Col B }
{
@Rowa
    A { "@RefCiteLabels { @RefNum }" }
    B { [3] }
@Rowa
    A { "@RefCiteLabels { @Label }" }
    B { [Kin93] }
@Rowa
    A { "@RefCiteLabels { @Author, @Year }" }
    B { [Jeffrey H. Kingston, 1993] }
}
The value of @Code "@RefCiteLabels" may be any object.  The @Code "@Label"
symbol will produce the @Code "label" option of @Code "$" or @Code "@Ref"
if there is one, rather than the @Code "@Label" option of the reference;
this @Code "label" option is explained in Section {@NumberOf labelled}.
@PP
@Code "@RefNumbers" determines the kind of numbering produced by the
references. @RawIndex { references }
references.refnumbers @SubIndex { @Code "@RefNumbers" }
refnumbers.references @Index { @Code "@RefNumbers" (references) }
@Code "@RefNum" symbol used within @Code "@RefCiteLabels" above and
@Code "@RefListLabels" below.  Its value may be {@Code Arabic},
{@Code Roman}, {@Code UCRoman}, {@Code Alpha}, or {@Code UCAlpha}, as
usual for numbering in Lout.  If you don't use {@Code "@RefNum"},
@Code "@RefNumbers" has no effect.
@PP
The remaining eleven setup file options are all concerned with the
appearance of the reference list.  The first, {@Code "@RefListFormat"},
references. @RawIndex { references }
references.reflistformat @SubIndex { @Code "@RefListFormat" }
reflistformat.references @Index { @Code "@RefListFormat" (references) }
determines the overall format of the list.  Here is what its four
@NoCite { $strunk1979style } possible values do:
@ID @Tab
    @Fmta { @Col @Code A ! @Col @OneCol B }
    vmargin { 0.3v }
{
@Rowa
    A { "@RefListFormat { NoLabels }" }
    B {  @RefPrint strunk1979style }
@Rowa
@Rowa
    A { "@RefListFormat { Labels }" }
    B {  2f @Wide {{@NumberOf strunk1979style}.} | @RefPrint strunk1979style }
@Rowa
@Rowa
    A { "@RefListFormat { DropLabels }" }
    B {  {@NumberOf strunk1979style}. //1vx
	 2f @Wide {} | @RefPrint strunk1979style
      }
@Rowa
@Rowa
    A { "@RefListFormat { InLabels }" }
    B {  {@NumberOf strunk1979style}. &2s @RefPrint strunk1979style }
}
@Code "@RefListFormat" is not concerned with the appearance of the
labels and references, only with where they appear.
@PP
@Code "@RefListLabels" determines the appearance of the labels in the
references. @RawIndex { references }
references.reflistlabels @SubIndex { @Code "@RefListLabels" }
reflistlabels.references @Index { @Code "@RefListLabels" (references) }
reference list (and so has no effect if @Code "@RefListFormat" is
{@Code "NoLabels"}).  It is a combination of @Code "@RefCiteStyle"
and {@Code "@RefCiteLabels"}; you can use @Code "@RefNum" and all the
options of @Code "@Reference" within it.  The default value,
@ID @Code "@RefListLabels { @RefNum. }"
produces a numbered reference list in the style of
{@Code "@NumberedList"}.  Another useful value is
@ID @Code "@RefListLabels { [@Label] }"
which produces the @Code "@Label" option of the reference, or the
@Code "label" option of the citation if there is one, enclosed in
brackets.  If you do switch to non-numeric labels you will need to
either use @Code "DropLabels" or else increase the
@Code "@RefListLabelWidth" option described below.
@PP
@Code "@RefListTitle" determines the heading placed just before the
references. @RawIndex { references }
references.reflisttitle @SubIndex { @Code "@RefListTitle" }
reflisttitle.references @Index { @Code "@RefListTitle" (references) }
reference list at the end of the document:
@ID @Code "@RefListTitle { Further Reading }"
Two special values, @Code "references" and {@Code "bibliography"},
produce References and Bibliography in English and their equivalents
in other languages.  @Code "@ChapRefListTitle" is the same as
references. @RawIndex { references }
references.chapreflisttitle @SubIndex { @Code "@ChapRefListTitle" }
chapreflisttitle.references @Index { @Code "@ChapRefListTitle" (references) }
{@Code "@RefListTitle"}, but applied to the reference list at the end
of each chapter of a book when @Code "@ChapCite" is used.
@PP
{@Code "@RefListIndent"}, {@Code "@RefListRightIndent"}, and
references. @RawIndex { references }
references.reflistindent @SubIndex { @Code "@RefListIndent" }
reflistindent.references @Index { @Code "@RefListIndent" (references) }
references. @RawIndex { references }
references.reflistrightindent @SubIndex { @Code "@RefListRightIndent" }
reflistrightindent.references @Index { @Code "@RefListRightIndent" (references) }
{@Code "@RefListGap"} determine the left indent, right indent, and gap
references. @RawIndex { references }
references.reflistgap @SubIndex { @Code "@RefListGap" }
reflistgap.references @Index { @Code "@RefListGap" (references) }
between reference list items, analogously to the {@Code "indent"},
{@Code "rightindent"}, and {@Code "gap"} options of the @Code "@List"
symbol (Section {@NumberOf lists}).  @Code "@RefListFont" and
references. @RawIndex { references }
references.reflistfont @SubIndex { @Code "@RefListFont" }
reflistfont.references @Index { @Code "@RefListFont" (references) }
references. @RawIndex { references }
references.reflistbreak @SubIndex { @Code "@RefListBreak" }
reflistbreak.references @Index { @Code "@RefListBreak" (references) }
@Code "@RefListBreak" determine the font and
paragraph breaking style of the reference list.  For example,
@ID @OneRow @Code @Verbatim {
@RefListFont { -2p }
@RefListBreak { 1.2fx outdent }
}
switches to a smaller size with outdented paragraphs (these work well
with {@Code NoLabels}).  The empty default values produce the same
font and break style as in the document as a whole.
@PP
@Code "@RefListLabelWidth" determines the distance from the left
references. @RawIndex { references }
references.reflistlabelwidth @SubIndex { @Code "@RefListLabelWidth" }
reflistlabelwidth.references @Index { @Code "@RefListLabelWidth" (references) }
edge of the labels to the left edge of the references, when
@Code "@RefListFormat" is @Code Labels or {@Code DropLabels} (it
has no effect when @Code "@RefListFormat" is @Code NoLabels or
{@Code "InLabels"}).  This is different to {@Code "@RefListIndent"},
which determines the distance from the edge of the column to the
left edge of the item.
@PP
Particular care is needed when @Code "@RefListFormat"
is @Code Labels and the labels are non-numeric, for then if the
labels are too wide they will overstrike the references.  The default
value, {@Code 2.00f}, is twice the current font size.  It may be
changed to any length (Section {@NumberOf objects}).  Regrettably,
Lout is not clever enough to choose a good value by itself.
@PP
Finally, @Code "@RefListSortKey" determines the sorting key used when
references. @RawIndex { references }
references.reflistsortkey @SubIndex { @Code "@RefListSortKey" }
reflistsortkey.references @Index { @Code "@RefListSortKey" (references) }
sort.ref @Index { sorting of reference lists }
ordering the reference list.  The default value,
@ID @Code "@RefListSortKey { @Tag }"
sorts by tag.  Another possibility is to sort by the
@Code "@Label" option:
@ID @Code "@RefListSortKey { @Label }"
As usual @Code "@Label" will use the value of a @Code "label" option
to the citation if there is one.  To sort by order of first citation, use
@ID @Code "@RefListSortKey { @CiteOrder }"
@Code "@CiteOrder" is implemented in a quick and dirty way, and there
are a couple of problems to watch out for if you use it.  First,
when you cite references more than once you get some strange
intermediate error messages and results.  All such problems will
be gone by the end of the fifth run.  Second, if you insert
more citations later on, you will need to restart the whole process,
by deleting the cross reference index file {@I lout.li}, since any
late insertions get erroneously stuck on the end instead of inserted
in the correct order.  If things go haywire, delete {@I lout.li} then
do five runs and they should be right again.
@PP
@Code "@RefListSortKey" may be any sequence of words
and options from the @Code "@Reference" symbol, but not @Code "@RefNum"
for obvious reasons.  A possible more elaborate sorting key is
@ID @Code "@RefListSortKey { @Author:@Year:@Tag }"
sorting first by author, then by year within each author, and finally
by tag.  However you
are supposed to choose tags which have this effect, and that is more
reliable since the modern practice is to put the authors' surnames
after their given names.  There seems to be little practical use for
sorting keys other than {@Code "@Tag"}, {@Code "@Label"}, and
{@Code "@CiteOrder"}.
@PP
A colon within the @Code "@RefListSortKey" option is converted by Lout
into a character smaller than any printable character, which ensures that
the sorting is carried out separately on the three fields.  It is essential
that the sort key uniquely identify the reference, because if two sort
keys are equal only one of the references will be printed.  The easiest
way to ensure this is to always include @Code "@Tag" in the sort key.
@End @Section