PATCH: pws-20: info formatting

PATCH: pws-20: info formatting

[Peter Stephenson]

In an aside in a message which hasn't got back to me yet, I queried the
excess use of quoting in zsh.info*: it's not too surprising you get this
sort of clash in a documentation system written in half a dozen
incompatible languages at once.  I've had a look at this.  The t(...) are
getting translated into @samp{...} for texinfo; this just changes the font
in tex, but in info it also sticks `quotes' around the text.  The result is
that some entries are surrounded by a single set of quotes, some by two,
and often even had quotes in the middle, for example `${'NAME`}', which
came from tt(${)var(NAME)tt(}).

In our case, we've already thought about when we want quotes (in principle
:-) see Util/zsh-development-guide), so it seems to me sensible to make
t(...) just use the corresponding texinfo font control command @t{}.  The
TeX version is unaltered, unless it was doing something extra too subtle
for me to see.

So I think it looks a lot better after the change -- unless anyone wants to
try something more sophisticated, in which case they run the risk of having
to rewrite the entire documentation.

--- Doc/ztexi.yo.t	Tue Jan 26 14:39:44 1999
+++ Doc/ztexi.yo	Tue Jun  1 16:43:47 1999
@@ -33,7 +33,7 @@
 
 def(em)(1)(NOTRANS(@emph{)ARG1NOTRANS(}))
 def(bf)(1)(NOTRANS(@cite{)ARG1NOTRANS(}))
-def(tt)(1)(NOTRANS(@code{)ARG1NOTRANS(}))
+def(tt)(1)(NOTRANS(@t{)ARG1NOTRANS(}))
 def(var)(1)(NOTRANS(@var{)ARG1NOTRANS(}))
 
 COMMENT(--- man page headers ---)

-- 
Peter Stephenson <pws@ibmth.df.unipi.it>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy

Re: PATCH: pws-20: info formatting

[Bart Schaefer]

On Jun 1,  5:03pm, Peter Stephenson wrote:
} Subject: PATCH: pws-20: info formatting
}
} In an aside in a message which hasn't got back to me yet, I queried the
} excess use of quoting in zsh.info*: it's not too surprising you get this
} sort of clash in a documentation system written in half a dozen
} incompatible languages at once.

See zsh-workers/4053 and associated thread for more on this, particularly
Zefram's remarks on the matter.

Personally, I prefer the appearance after Peter's patch, but ...

(Aside:  Are there some LPAR() and RPAR() needed in the new text from
6416?  And correspondingly different placements of tt()?  I'm never
sure what ought to be happening with LPAR() and RPAR().)

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

Re: PATCH: pws-20: info formatting

[Peter Stephenson]

"Bart Schaefer" wrote:
> On Jun 1,  5:03pm, Peter Stephenson wrote:
> } Subject: PATCH: pws-20: info formatting
> }
> } In an aside in a message which hasn't got back to me yet, I queried the
> } excess use of quoting in zsh.info*: it's not too surprising you get this
> } sort of clash in a documentation system written in half a dozen
> } incompatible languages at once.
> 
> See zsh-workers/4053 and associated thread for more on this, particularly
> Zefram's remarks on the matter.
> 
> Personally, I prefer the appearance after Peter's patch, but ...

Actually, I think my patch is consistent with Zefram's remarks.  He's
saying tt() is for the font, `...' is for quotation --- that's exactly how
it is after my change.  Before, tt() was *also* introducing quotes (but
only in info, so perhaps it didn't get noticed); after, the quotes are just
the way we put them.

However, I've been negligent about putting quotes around some of my stuff,
including rewrites for parameter expansion, so I'll have a look at this
again now it's more obvious in info.  I never bothered reading
Util/zsh-development-guide until now.

> (Aside:  Are there some LPAR() and RPAR() needed in the new text from
> 6416?  And correspondingly different placements of tt()?  I'm never
> sure what ought to be happening with LPAR() and RPAR().)

Thinks like `tt((f))' work OK as long as the parentheses are balanced.  If
you have unbalanced parentheses you have to resort to
e.g. `tt(LPAR())var(flags)tt(RPAR())'.

-- 
Peter Stephenson <pws@ibmth.df.unipi.it>       Tel: +39 050 844536
WWW:  http://www.ifh.de/~pws/
Dipartimento di Fisica, Via Buonarroti 2, 56127 Pisa, Italy