LinkLookOption

Michalis Kamburelis edited this page Jan 7, 2017 · 8 revisions
Clone this wiki locally

--link-look CommandLine option determines how links generated by pasdoc look like. This affects links generated by @link tag, links to exception names at the beginning of @raises tag, and links created by @inherited tag. This affects only multipart links, e.g. links of the form

  • @link(ClassName.Identifier)

  • @link(UnitName.Identifier)

  • @link(UnitName.ClassName.Identifier)

Examples below will use the second case, @link(UnitName.Identifier).

--link-look=default

This is the default setting, this is simple: when you write link like @link(UnitName.Identifier), pasdoc will display it as a text "UnitName.Identifier" that links to UnitName.Identifier. Pretty obvious, huh?

--link-look=full

This tells pasdoc to display link like @link(UnitName.Identifier) as

  • Text "UnitName" that links to UnitName

  • Then period

  • Then text "Identifier" that links to UnitName.Identifier

    The effect is that pasdoc also shows the text "UnitName.Identifier" but each part of this text is a different link.

    While this makes links powerful, this is quite confusing for human reading the documentation (since reader may not see at the first glance that each part of the text "UnitName.Identifier" links to something else).

--link-look=full

is equivalent to --full-link command-line option.

--link-look=stripped

This tells pasdoc to display link like @link(UnitName.Identifier) as only the word "Identifier". The link still links to UnitName.Identifier, but UnitName is not shown. This was the old behavior of pasdoc (before 2005-05-11) and is kept here for compatibility. It is useful to do some dirty tricks with the way documentation is displayed, see e.g. Richard B Winston’s mail in pasdoc-main archives where he describes how he utilizes this.

Now these dirty tricks should be rather done by specifying explicit display name for a link, like:

@link(UnitName.Identifier Some human description of UnitName.Identifier)

See @link tag. This has the big advantage over using --link-look=stripped : you are able to freely decide for what link you want to "cheat" (and display different name than the actual link target), and where you don’t need this. So you don’t have to ever write some cludgy things like

UnitName.@link(UnitName.Identifier)