Use of tt() formatting in yodl doc sources

Use of tt() formatting in yodl doc sources

[Bart Schaefer]

When translating yodl to info, the tt() text style comes out like this:

	`teletype'

That means that if the yodl source looks like:

	with the SUBJECT `tt(subscribe) var(<e-mail-address>)'

then it displays in info as:

	with the SUBJECT ``subscribe' <E-MAIL-ADDRESS>'

which is both misleading and strange-looking.  It gets even worse when you
get to things like:

	`for ((' [EXPR1] `;' [EXPR2] `;' [EXPR3] `)) do' LIST `done'

There's no perfect solution for this; the best would probably be for tt()
text to simply be inserted plain, without styling, for info purposes.  That
in turn probably means fooling with what goes into zsh.texi, using @ifinfo;
I'm not even sure it's possible.

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

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

[Zefram]

Bart Schaefer wrote:
>That means that if the yodl source looks like:
>
>	with the SUBJECT `tt(subscribe) var(<e-mail-address>)'
>
>then it displays in info as:
>
>	with the SUBJECT ``subscribe' <E-MAIL-ADDRESS>'

I consider this to be a bug in makeinfo.  The resulting info files are
ambiguous and misleading.  But since that's how info files are defined
to be, there's nothing we can reasonably do about it.

-zefram

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

[Peter Stephenson]

"Bart Schaefer" wrote:
> When translating yodl to info, the tt() text style comes out like this:
> 
> 	`teletype'

I have to work around this problem in the FAQ.  Actually, what made
me do it was rather that formats with special fonts for tt() make the
quotes look overfussy, but the effect is the same.  What I did is
defined a mytt() macro which expands to `this' for plain text, but
does tt(this) for other modes.  It could be used here, though it's a
lot of rewriting.  It looks like

COMMENT(-- mytt is like tt but adds quotes `like this' for plain text --)\
def(mytt)(1)(\
  whentxt(`ARG1')\
  whenhtml(tt(ARG1))\
  whenlatex(tt(ARG1))\
  whenms(tt(ARG1))\
  whensgml(tt(ARG1)))

-- 
Peter Stephenson <pws@ifh.de>       Tel: +39 50 844536
WWW:  http://www.ifh.de/~pws/
Gruppo Teorico, Dipartimento di Fisica
Piazza Torricelli 2, 56100 Pisa, Italy

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

[Bart Schaefer]

On Jun 5,  9:32am, Peter Stephenson wrote:
} Subject: Re: Use of tt() formatting in yodl doc sources
}
} "Bart Schaefer" wrote:
} > When translating yodl to info, the tt() text style comes out like this:
} > 
} > 	`teletype'
} 
} I have to work around this problem in the FAQ.  [...] What I did is
} defined a mytt() macro which expands to `this' for plain text, but
} does tt(this) for other modes.

In this case it's makeinfo that's adding the quotes; e.g.

          yodl         texinfo        info
	--------     -----------     ------
	tt(text) --> @code{text} --> `text'
	em(text) --> @emph{text} --> *text*

(Never mind that tt(x) ought to be @kbd{x}, the end result for info files
is the same.)

The problem, according to Zefram, is that you can't redefine the notion
of @code{} in the makeinfo pass.  He's right, but I was hoping for a fix
upstream of that.  Unfortunately, the only one that's workable seems to
be to generate two .texi files, one for producing printed documentation
and using @code{}, the other for the producing the info files and leaving
off the @code{}.

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?  Removing the `' in the .yo source would clear up a
lot, though not all, of the confusion.  (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.)

-- 
Bart Schaefer                                 Brass Lantern Enterprises
http://www.well.com/user/barts              http://www.brasslantern.com

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

[Zefram]

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