References such as see ... for more information are very common in documents. The Yodl package supports three mechanisms to accomplish such references:

Labels and references:
Labels can be defined in a document as a placeholder for the last number that was used in a sectioning command. At other points in the document, references to those labels are used. The reference expands to the number, as in see section 1.3. This mechanism is available in all but the most primitive output formats (e.g, the ASCII converter will ignore the requests). Furthermore, the numeric reference (1.3 in the example of the previous paragraph) is in HTML a clickable reference that leads to the mentioned section.

Labels and links:
This mechanism can be used to set links in a document without using the number of a sectioning command, as in see the introduction for more information, with the introduction being a clickable link to some label. This mechanism of course only leads to a clickable link in HTML: in other formats the text see the etc. is just typeset as is.

URLs:
Universal Resource Locators (URLs) are used to create links to other HTML documents or services, à la the HTML <a href=..> method. The URLs of course only lead to clickable links in HTML output; in other output formats only some descriptive text appears.
The following macros implement the above mechanisms:
  • The macro label(name) defines a label named name. The name of the label can be used in a ref or link macro.
  • The macro ref(name) sets a reference to the label named name. The text of the reference is the number of the last sectioning command that was active during the creation of the label. When using references it is therefore important to define the corresponding labels right after a sectioning command, as in
    section(How to install my program) label(howtoinstall)
    This section describes...
    .
    .
    See section ref(howtoinstall) for installation instructions.
    

    The macro ref(howtoinstall) would then expand to the number of the section named How to install my program.

  • The macro link(description)(name) always expands to the description. In HTML output, a clickable link is created pointing to a label called name. For example:

    label(megahard)
    COMMENT(zucht...)
    The Jodel package isn't shareware, it isn't
    beggarware, it isn't freeware, it's
    bf(megahard-ware).
    .
    .
    Who wants a link(picosoft)(megahard)?
    

    This code fragment would always set the text picosoft, but under HTML a clickable link would appear pointing to the text.

  • The macro url(description)(location) always expands to the description, but creates a hyperlink pointing to location in HTML. For example,

    If you have W3 access, take a look
    at my url(homepage)
    (http://www.icce.rug.nl/we/karel/karel.html).
    

    The text homepage always appears, but only in HTML it is a link. (Note that the double quotes, which are necessary in HTML around the location, are not needed in Yodl.) To use a different font in the description part, surrond it inside the url paramater list, as in:

    The Yodl package can be obtained at
    the site tt(ftp.lilypond.org) in the directory
    url(tt(/pub/yodl))
       (ftp://ftp.lilypond.org/pub/yodl/development).
    

  • The macro email(address) is a special case of url: under HTML, the address appears as a clickable link in slanted font to mail address. For example:

    I can be reached as
    email(karel@icce.rug.nl).
    

    I can be reached as karel@icce.rug.nl.

  • Always keep in mind that the name of a label must be exactly identical in both the label macro and in the ref or link macro. Other than that, the name is irrelevant.

    Note also the macro package also implements a macro includefile, that includes a file and automatically creates a label. That means that a Yodl file like:

    chapter(Introduction)
        sect(Welcome)
        includefile(welcome)
    
    chapter(Technical information)
    includefile(techinfo)
    

    implicitly creates two labels, named welcome and techinfo.

    Below are some randoms dont's about labels and references:

  • Don't put `weird' characters in label names. Generally, don't use spaces and tabs; though punctuation characters should work.

  • The name of the label is always only an internal symbol; it does not appear in the output. Therefore, constructions such as the following are not correct:

    ref(em(labelname))
    

    The reason for the incorrectness is, what internal name should em(labelname) generate? Here probably an attempt is made to set a reference in italics. The right construction is of course to set whatever ref() returns in italics, as in:

    em(ref(labelname))
    

  • The label macro should not appear nested inside another macro. There is no strict reason for this as far as Yodl is concerned; however, the processors of Yodl's output might go haywire. E.g., beware of the construction

    section(Introduction label(intro))
    

    The right stanza is of course

    section(Introduction) label(intro)
    

  • undef(x)


    Go back to index of Yodl.

    Please send Yodl questions and comments to yodl@icce.rug.nl.

    Please send comments on these web pages to (address unknown)

    Copyright (c) 1997, 1998, 1999 Karel Kubat and Jan Nieuwenhuizen.

    Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.


    This page was built from Yodl-1.31.18 by

    <(address unknown)>, Sat May 7 03:56:57 2011 UTC.