COMMENT(
  urg makeinfo (3.12):
    * can't handle examples inside lists
    * tries to resolve references inside @ignore @end ignore block

whentexinfo(texinfocommand(@ignore))
)

DEFINEMACRO(x)(1)(ARG1)
whentexinfo(redef(x)(1)())

x(

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

startdit()

    dit(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 em(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. 
    
    dit(Labels and links:) This mechanism can be used to set links in a 
    document without using the number of a sectioning command, as in em(see 
    the introduction for more information), with the em(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 em(see the) etc. is just typeset as is.
    
    dit(URLs:) Universal Resource Locators (URLs) are used to create links to 
    other HTML documents or services, \`a la the HTML tt(<a href=..>) method. 
    The URLs of course only lead to clickable links in HTML output; in other 
    output formats only some descriptive text appears.

enddit()

The following macros implement the above mechanisms:

startit()

    it() The macro tt(label(name)) defines a label named tt(name). The name of 
    the label can be used in a tt(ref) or tt(link) macro.
    
    it() The macro tt(ref(name)) sets a reference to the label named tt(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
    
verb(\
section(How to install my program) label(howtoinstall)
This section describes...
.
.
See section ref(howtoinstall) for installation instructions.)

    The macro tt(ref(howtoinstall)) would then expand to the number of the 
    section named em(How to install my program).
                   
    it() The macro tt(link(description)(name)) always expands to the 
    tt(description). In HTML output, a clickable link is created 
    pointing to a label called tt(name). For example:
                   
verb(\
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 em(picosoft), but under HTML
    a clickable link would appear pointing to link(the text)(megahard).
    
    it() The macro tt(url(description)(location)) always expands to the 
    tt(description), but creates a hyperlink pointing to tt(location) in HTML. 
    For example,
    
verb(If you have W3 access, take a look
at my url(homepage)
(http://www.icce.rug.nl/we/karel/karel.html).)

    The text url(em(homepage))(http://www.icce.rug.nl/we/karel/karel.html)
    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 tt(description) part, surrond it 
    bf(inside the url paramater list), as in:
    
verb(The Yodl package can be obtained at
the site tt(pcnov095.win.tue.nl) in the directory
url(tt(/pub/yodl))
   (ftp://pcnov095.win.tue.nl/pub/yodl).)

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

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

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

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

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

verb(\
chapter(Introduction)
    sect(Welcome)
    includefile(welcome)

chapter(Technical information)
includefile(techinfo))

implicitly creates two labels, named tt(welcome) and tt(techinfo).

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

startit()

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

    it() 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:

verb(ref(em(labelname)))

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

verb(em(ref(labelname)))

    it() The tt(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

verb(section(Introduction label(intro)))

    The right stanza is of course

verb(section(Introduction) label(intro))


endit()

whentexinfo(texinfocommand(@end ignore))
)
undef(x)

