David Kastrup wrote:
>> Unless you're inside an @example block, you should wrap
>> these @var{} blocks in @code{}:
>>
>> "@co...@var{proc}}", "@co...@var{context}}"
>
> 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{}, @co...@var{}}, 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 @co...@var{argn}} 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 _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel
