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

[Mark Polesky]

David Kastrup wrote:
>> Unless you're inside an @example block, you should wrap
>> these @var{} blocks in @code{}:
>>
>> "@address@hidden", "@address@hidden"
>
> Why?

Well, if nothing else, they're simultaneously metasyntactic
variables *and* examples of program code, so both @var and
@code are appropriate.  And the texinfo manual* goes to the
trouble to state this:
  (Note that @var may appear inside @code, @samp, @file,
  etc.)
* http://www.gnu.org/software/texinfo/manual/texinfo/html_node/var.html

Also see the entry on the @code command:
http://www.gnu.org/software/texinfo/manual/texinfo/html_node/code.html
  Thus, you should use @code for an expression in a program,
  for the name of a variable or function used in a program,
  or for a keyword in a programming language.

Furthermore, in the html output, when @var is not within a
fixed-width block, it looks exactly like an @emph block, and
it's better practice to differentiate the two.  Here's a
relevant example with instances of @emph{}, @address@hidden,
and @code{} all on the same line:

http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=blob;f=Documentation/extending/programming-interface.itely#l68
@tab a scheme @emph{type predicate} for which @address@hidden
must return @code{#t}.

In the html output, the resulting font styles make it
visually clear that:
  1. "type predicate" is not an element of program code,
  2. "argN" is an element of code and a variable,
  3. "#t" is an element of code and *not* a variable.
http://lilypond.org/doc/v2.13/Documentation/extending/music-function-syntax

Had "argN" been entered with @var but not @code, it would
have the same font style as "type predicate", and there
would be no visual semantic differentiation.

In the pdf output, you don't have the exact same problem,
since @emph and @var already get different font styles.
However, you have a different problem: using @var without
@code results in a style that is so different from the code
snippets in @example blocks, that the eye doesn't connect
the two so easily.

For example, if you look at the current pdf output of
Extending 2.3.1 "Context evaluation"*, you can see at a
glance that "\applyContext" is an element of program code
when it appears in the paragraph text.  But the word
"function", even though it's also an element of program
code, doesn't look like one, since it was not entered with
@code.

* p.25 (p.28/40 of the pdf file itself)
  http://lilypond.org/doc/v2.13/Documentation/extending.pdf

The end result of our collective laziness with the @code
command is that the docs are harder to read.  There are
plenty of instances in the docs that can be improved with
this modification, but I haven't gotten around to addressing
this yet.

Does this answer your question?  (:
- Mark