Re: an example of minimal example (issue4636082)

[lemniskata . bernoullego]

New patch set uploaded.

I have a problem with the box at the bottom: code examples are
center-aligned, not left-aligned.  I didn't found any example of how
it's done in our manuals; i searched texinfo documentation and found
@flushleft, but it didn't work... How should i do this?


http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi
File Documentation/web/community.itexi (right):

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode283
Documentation/web/community.itexi:283: The simpler the example is, the
quicker potential helpers can
On 2011/07/05 00:14:30, J_lowe wrote:
> The tinier the example, the simpler it is and therefore, the
quicker...

I'm not sure if this is straightforward enough.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode287
Documentation/web/community.itexi:287: A simple example demonstrates
that you have put effort towards
On 2011/07/05 00:14:30, J_lowe wrote:
> A tiny example also demonstrates to others on the email lists that
some kind of
> effort has been taken to...

Too wordy imo.

> [PS Are we talking 'simpler' or 'tinier' here? While I can see that
both work,
> they are two different ideas and you are already moving away from
'tiny'. Can we
> stick to tiny?]

Umm, i didn't touch anything here.  I've only added that example part.
However, i agree that 'tiny' sounds better at the beginning of this
sentence.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode289
Documentation/web/community.itexi:289: input, it looks like they don't
care how if we help them or not.
"don't care how if we help them or not." Should 'how' be there?  Looks
wrong to me...

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode289
Documentation/web/community.itexi:289: input, it looks like they don't
care how if we help them or not.
On 2011/07/05 00:14:30, J_lowe wrote:
> solving the problem yourself. Whereas overly complex, large or
unedited examples
> look like no effort has been made to try to attempt to solve the
problem
> yourself and can discourage others from helping.

I think it's too wordy, and the repetition about solving the problem
yourself is not necessary.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode292
Documentation/web/community.itexi:292: Creating a tiny example forces
you to understand what is
On 2011/07/05 00:14:30, J_lowe wrote:
> A tiny example can also help you to ...

I agree about the 'helping' part, but i wouldn't remove word 'creating'.
It's creating the tiny example that helps in understanding, not merely
having it.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode296
Documentation/web/community.itexi:296: insufficient understanding of
LilyPond, not an actual bug!
On 2011/07/05 00:14:30, J_lowe wrote:
> ...then the problem is usually due to a lack of understanding of how
the
> LilyPond syntax works.

I prefer the original, it's grammatically simpler.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode305
Documentation/web/community.itexi:305: @subheading How do I create them?
On 2011/07/05 00:14:30, J_lowe wrote:
> How to create them.

> [we try to not personalise the text or talk in first/second person]

Good point, i agree.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode311
Documentation/web/community.itexi:311: Include the \version number.
On 2011/07/05 00:14:30, J_lowe wrote:
> Include the LilyPond @code{\version} number you are using.

I changed it so that it should be plain that the version of the actual
binary matters, not what \version statement you are using in your files
(i don't update \version numbers in my files quite often myself).

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode314
Documentation/web/community.itexi:314: Make it small!  Examples about
spacing or page layout might
On 2011/07/05 00:14:30, J_lowe wrote:
> Keep it tiny! Examples about...

I'd leave word 'make' because creating a tiny ex is a process of
removing material.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode320
Documentation/web/community.itexi:320: or @address@hidden @dots{} 
address@hidden)}
sections of your file.  If you can
On 2011/07/05 00:14:30, J_lowe wrote:
> ..or @address@hidden @dots{} address@hidden)} sections of your file first. If 
> you
can...

Done.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode321
Documentation/web/community.itexi:321: comment something while still
demonstrating the main idea, then
On 2011/07/05 00:14:30, J_lowe wrote:
> comment something out while ...

sounds awkward to me.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode322
Documentation/web/community.itexi:322: remove the commented-material!
On 2011/07/05 00:14:30, J_lowe wrote:
> remove the commented material completely from your example.

> [no need for all the exclamations]

Done.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode325
Documentation/web/community.itexi:325: Avoid using complicated notes,
keys, or time signatures, unless
On 2011/07/05 00:14:30, J_lowe wrote:
> ..notes, keys or time signatures, unless...

> [remove comma]

Done.

It's too subtle for me too speak, i'm not a native english speaker.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode330
Documentation/web/community.itexi:330: is about those particular
commands.
On 2011/07/05 00:14:30, J_lowe wrote:
> [I'd use the word 'specific' instead of 'particular' here]

Done.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode334
Documentation/web/community.itexi:334: (how the correct output should
look like).
On 2011/07/05 00:14:30, J_lowe wrote:
> If possible, attach a small image file of what you want the correct
output to
> look like as this will help us clarify exactly what the problem is.

I'm not sure.
I wrote about 'achieving' because tiny examples are not only used for
bug reports, so there isn't always "correct vs wrong" output.

http://codereview.appspot.com/4636082/diff/10001/Documentation/web/community.itexi#newcode375
Documentation/web/community.itexi:375: quite often 4 lines are enough to
demonstrate the problem!
On 2011/07/05 00:14:30, J_lowe wrote:
> [we've already said this above - "Examples about spacing or page
layout might
> require many bars of music, but most issues can be reproduced using
less than a
> single measure" why repeat it (and differently)?]

Sizes of example music-wise and line-count-wise are two different
things. The longer example above is already small in terms of music
(only 1 measure), but the problem with it is that it is long code-wise.

http://codereview.appspot.com/4636082/