[racket-dev] documentation dependencies & indirect hyperlinks

From: Matthew Flatt (mflatt at cs.utah.edu)
Date: Sun Jul 14 08:40:39 EDT 2013

Documentation hyperlinks are now covered by the package-dependency
checking of `raco setup'.

Dependencies that take the form of `for-label' imports were found by
normal module-dependency checking, already. The new checks cover cases
where a document refers to another document via `other-doc' or
`@secref[#:doc ...]' and where documentation refers to a module with
`racketmodname'.

Sometimes, you don't want a documentation link to force installation of
another document (and its dependencies). For example, the DrRacket
manual refers to the Algol 60 manual, but I don't want to force the
installation of Algol 60 and its documentation just to get the DrRacket
documentation; the hyperlink to Algol 60 should in the DrRacket manual,
but it should be a remote link if Algol 60 is not installed.

A few Scribble forms can make such "indirect" links:

 * Add `#:indirect' to the end of a `racketmodname' link to make it
   indirect:

      @racketmodname[htdp/image #:indirect]

   This works because `racketmodname' can build a suitable link tag
   without consulting any other modules or documents.

 * To make a section reference indirect, change `secref' to `seclink',
   and include `#:indirect?':

      @secref[#:other-doc '(lib "scribblings/htdp-langs/beginner.scbl)
              "beginner-syntax"]
    =>
      @seclink[#:other-doc '(lib "scribblings/htdp-langs/beginner.scbl)
               #:indirect? #t
               "beginner-syntax"]{the BSL grammar}

    The reason `secref' changes to to `seclink' is that the former
    depends on the target document to extract the section title, while
    the latter uses the link text that you provide without having to
    consult the target document.

 * As a convenience, the `other-doc' function accepts an `#:indirect'
   argument that is content to describe a document. The content is
   combined with "the" and "documentation" to form the link text:

      @other-doc['(lib "scribblings/htdp-langs/beginner.scbl)]
    =>
      @other-doc['(lib "scribblings/htdp-langs/beginner.scbl)
                 #:indirect @elem{BSL}]
      ; which is the same as
      @seclink[#:other-doc '(lib "scribblings/htdp-langs/beginner.scbl)
               #:indirect? #t
               "top"]{the @elem{BSL} documentation}

Use indirect links sparingly, because they are not checked by either
the documentation-build part of `raco setup' or the package-dependency
part. A bad indirect link shows up only as broken link when you try to
follow it in the rendered documentation.

Dependency checking does not cover "dynamic" dependencies from
`scribble/eval' uses in a document. That's an area for future
improvement, but those dependencies are normally paired with checked
`for-label' imports, anyway, to hyperlink examples.


Posted on the dev mailing list.