Doc: NR 1: Use @code{@var{...}} for variables.

Doc: NR 1: Use @code{@var{...}} for variables.

[Mark Polesky, 2010-09-26 07:03:21]

Anyone want to double-check this doc patch?
Just trying to clean up the NR a little bit
in light of recent discussions on -devel.

Thanks
- Mark

[Graham Percival (old account), 2010-09-26 17:24:07]

LGTM, although I didn't check that it still compiles.

http://codereview.appspot.com/2217046/diff/1/Documentation/notation/pitches.i...
File Documentation/notation/pitches.itely (right):

http://codereview.appspot.com/2217046/diff/1/Documentation/notation/pitches.i...
Documentation/notation/pitches.itely:142: 
Why the extra newline ?  I mean, it doesn't hurt anything, but all the other
@item's [sic] don't have any extra lines between the @item and the text, and
that's what the doc policy says to do.

http://codereview.appspot.com/2217046/diff/1/Documentation/notation/repeats.i...
File Documentation/notation/repeats.itely (right):

http://codereview.appspot.com/2217046/diff/1/Documentation/notation/repeats.i...
Documentation/notation/repeats.itely:682: The same output can be obtained by
adding @samp{:@var{number}}
Why is this @samp instead of @code?
(I totally agree that the previous @q{} was wrong)

[Mark Polesky, 2010-09-28 06:33:49]

On 2010/09/26 17:24:07, Graham Percival wrote:
> Documentation/notation/pitches.itely:142: 
> Why the extra newline ?

Fixed.

> Documentation/notation/repeats.itely:682:
> Why is this @samp instead of @code?

Rewritten.  Should be fine, but feel free to
double-check it.

- Mark

[Graham Percival (old account), 2010-09-28 17:09:42]

LGTM, go ahead an push.

Technically, the doc policy (or at least custom) is to have a blank newline
before the @end itemize / @end enumerate, but I don't know if that has any
effect on anything.  I just always do it that way because previous material did
it that way, and I was never curious enough to test it out and check all output
formats.

But I'm fine with this patch as it is; there's a stage where style nitpicking
just gets ridiculous.  :)

[markpolesky_yahoo.com, 2010-09-29 01:30:14]

Graham Percival wrote:
> Technically, the doc policy (or at least custom) is to
> have a blank newline before the @end itemize / @end
> enumerate, but I don't know if that has any effect on
> anything.  I just always do it that way because previous
> material did it that way, and I was never curious enough
> to test it out and check all output formats.

The texinfo manual doesn't put a blank line there:
http://www.gnu.org/software/texinfo/manual/texinfo/html_node/itemize.html

- Mark


      

[markpolesky_yahoo.com, 2010-09-29 01:30:14]

Graham Percival wrote:
> Technically, the doc policy (or at least custom) is to
> have a blank newline before the @end itemize / @end
> enumerate, but I don't know if that has any effect on
> anything.  I just always do it that way because previous
> material did it that way, and I was never curious enough
> to test it out and check all output formats.

The texinfo manual doesn't put a blank line there:
http://www.gnu.org/software/texinfo/manual/texinfo/html_node/itemize.html

- Mark