Re: Doc fixes for \applyOutput ... ok to push?

[Mark Polesky]

David Kastrup wrote:
> +In the PDF and HTML output, variables should appear in a monospace
> +font (to indicate that they are elements of program code).  So
> +when referring to variables in the text, use
>  @code{@@address@hidden@@address@hidden@address@hidden@}}, unless the
>  @code{@@address@hidden@address@hidden is already within another fixed-width
> +command such as @code{@@address@hidden@address@hidden or @code{@@example}.

> I would not mention monospace.  It might make people
> fiddle with monospace font instructions, defeating
> consistency.

What do you mean by "fiddle with monospace font
instructions"?  I can't imagine what contributors would be
tempted to do wrong, given these instructions.

> When such variables stand for actual code variables
> instead of abstract concepts, you should write
> @code{@@address@hidden@@address@hidden@address@hidden@}} in text passages in
> order to have the formatting in all backends agree with
> the use of those variables in code passages, like
> @code{@@address@hidden@address@hidden or @code{@@example}.

Personally I don't think that having the "formatting in all
backends" is any clearer, nor do I really think that we
should spend too much more time debating this.  If something
is in the doc policy, contributors are supposed to abide by
it, even if they don't want to.  Some rationales are good to
know, but in this case I don't think it's a big deal, and I
think my "monospace" rationale above is easier to understand
anyway.

> I would not spell out the details like "monospace" or
> fixed-width: those may change over time.

I should hope not!  I don't expect that the decades-old
convention of showing code in monospace will ever change; it
is a good convention.

- Mark