Re: Use of tt() formatting in yodl doc sources

[Zefram <zefram@xxxxxxxxx>]

Bart Schaefer wrote:
>On the other hand, it does seem silly to -both- quote things -and- set
>them in a special typeface.  Why do the .yo files do stuff like `tt(&)'
>in the first place?

The quote marks indicate that the enclosed text is not a part of the
text of the documentation (i.e., that it is being quoted).  The special
typefaces (tt(), var()) indicate the precise nature of the text.
Completely distinct purposes.  Observe the places where tt() is used
without quotes -- there is text of the form

	Type `tt(xyzzy)' to let zsh know you have played tt(advent).
	Saying `plugh' aloud doesn't have much effect, however.

In this case, "zsh" is normal text (a name), "advent" is a command name
ocurring in the main text, "plugh" is a normal word that is being quoted
(it's the user that says `plugh', not the documentation), and "xyzzy"
is some text to be typed literally that is being quoted.

We probably don't follow these conventions everywhere, but in the
conversion to yodl I fixed a lot of bad markup, and I've been watching
the documentation ever since, so it's pretty consistent.  This stuff
should probably go into the zsh-development-guide.

>                                        (The remaining sillyness is with
>stuff like tt(`) and tt(') which become ``' and `'', but at the moment
>they often become ```'' and ``''' which is totally weird.)

Weird it is.  ``' isn't too bad, however, even without the special
typefaces.

-zefram