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

[David Kastrup]

Mark Polesky <address@hidden> writes:

> 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.

@address@hidden

is easier to write than @address@hidden and is perfectly
compatible with your instructions.  It is also a bad idea.

>> 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.

@address@hidden abides by your instructions.

>> 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.

It is nothing that the documentation writer should hardwire into his
prose.

-- 
David Kastrup