Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
LGTM https://codereview.appspot.com/7013043/ ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
I'm happy with this with the change below. The formatting of this section (and the CG in general) has never been systematically reviewed, so there's no point in being strict about it here. The text is understandable even though it doesn't fit into the surrounding material in the best possible way. https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/doc-work.itexi File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/doc-work.itexi#newcode149 Documentation/contributor/doc-work.itexi:149: @contributions that contain examples using overrides or tweaks Not sure what you intended here. Does the @ mean there is an omitted texinfo command? Maybe this line should just be deleted. https://codereview.appspot.com/7013043/ ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi#newcode155 Documentation/contributor/doc-work.itexi:155: The correct way to add [changes like this] to the documentation is to On 2012/12/26 07:32:01, J_lowe wrote: On 2012/12/25 09:10:01, bealingsplayfordnews wrote: Why the [] ? This is a standard way to to clarify the antecedent. Also you will see it used to denote missing text [ ... ] or more commonly to denote a mistake or inaccuracy in a quote without it being attributed to the author of the text it is being quoted in (i.e '[sic]'). Anyway, enough of that, I have rewritten the sentence. Actually, the _only_ usage of [...] I know in text passages is an editorial addition, signifying material added by someone different from the original author. In particular, [sic] means as the editor, I am perfectly aware that this is wrong, thank you very much. But since this is a literal quotation, I am not at liberty correcting it. Another frequent use is to make explicit what object a pronoun in a quoted section is referring to if the scope of the quotation does not allow deducing it. Also, when only sentence parts are quoted and the result would be ungrammatical, editorial insertions used for creating a grammatical sentence again will be marked with [...]. https://codereview.appspot.com/7013043/ ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
hello, On 26 December 2012 11:00, d...@gnu.org wrote: https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi#newcode155 Documentation/contributor/doc-work.itexi:155: The correct way to add [changes like this] to the documentation is to On 2012/12/26 07:32:01, J_lowe wrote: On 2012/12/25 09:10:01, bealingsplayfordnews wrote: Why the [] ? This is a standard way to to clarify the antecedent. Also you will see it used to denote missing text [ ... ] or more commonly to denote a mistake or inaccuracy in a quote without it being attributed to the author of the text it is being quoted in (i.e '[sic]'). Anyway, enough of that, I have rewritten the sentence. Actually, the _only_ usage of [...] I know in text passages is an editorial addition, signifying material added by someone different from the original author. In particular, [sic] means as the editor, I am perfectly aware that this is wrong, thank you very much. But since this is a literal quotation, I am not at liberty correcting it. Another frequent use is to make explicit what object a pronoun in a quoted section is referring to if the scope of the quotation does not allow deducing it. That's the 'antecedent' thingy I referred to. Also, when only sentence parts are quoted and the result would be ungrammatical, editorial insertions used for creating a grammatical sentence again will be marked with [...]. I thought I might get responses like this, which is why I rewrote the sentence. Life is too short. Merry Christmas ;) James ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/doc-work.itexi File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/doc-work.itexi#newcode149 Documentation/contributor/doc-work.itexi:149: @contributions that contain examples using overrides or tweaks On 2012/12/26 10:27:39, Trevor Daniels wrote: Not sure what you intended here. Does the @ mean there is an omitted texinfo command? Maybe this line should just be deleted. No that's a typo. :( It should be @subheading contributions that contain... I didn't get a chance to test this patch yet. Thanks for spotting. https://codereview.appspot.com/7013043/ ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
James pkx1...@gmail.com writes: On 26 December 2012 11:00, d...@gnu.org wrote: Documentation/contributor/doc-work.itexi:155: The correct way to add [changes like this] to the documentation is to Why the [] ? This is a standard way to to clarify the antecedent. Another frequent use is to make explicit what object a pronoun in a quoted section is referring to if the scope of the quotation does not allow deducing it. That's the 'antecedent' thingy I referred to. Well, ok, but again I know it only when something is inserted into a quotation, where original author and editor differ. Our manual pretends to be a single text, so one would use () instead of [] for clarifying interjections. I thought I might get responses like this, which is why I rewrote the sentence. Smart move. Life is too short. But at least it is getting longer all the time. Merry Christmas The same to you and many more. -- David Kastrup ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/doc-work.itexi
File Documentation/contributor/doc-work.itexi (right):
https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/doc-work.itexi#newcode158
Documentation/contributor/doc-work.itexi:158: @ref{Introduction to LSR}.
Thanks for the update. I still think it's worth a simple reminder here:
'Dont' forget to tag the snippet with docs'.
https://codereview.appspot.com/7013043/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
Hello,
On 26 December 2012 12:52, philehol...@googlemail.com wrote:
https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/doc-work.itexi
File Documentation/contributor/doc-work.itexi (right):
https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/doc-work.itexi#newcode158
Documentation/contributor/doc-work.itexi:158: @ref{Introduction to LSR}.
Thanks for the update. I still think it's worth a simple reminder here:
'Dont' forget to tag the snippet with docs'.
https://codereview.appspot.com/7013043/
Is there any case where a snippet would not have the docs tag?
James
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
On 2012/12/26 13:15:05, J_lowe wrote: Is there any case where a snippet would not have the docs tag? James Some statistic from the last LSR-update: The 2.12.3-LSR contained 645 snippets. 291 were tagged docs. There are many LSR-snippets showing nice code/features, but not all of them are worth to be integrated in /Documentation/snippets for different reasons. OTOH, some snippets from the docs should also be removed, imho. I think someone should review the tags of each single snippet. Perhaps during the next upgrade. https://codereview.appspot.com/7013043/ ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
- Original Message -
From: James pkx1...@gmail.com
To: pkx1...@gmail.com; tdanielsmu...@googlemail.com;
philehol...@googlemail.com; d...@gnu.org; lilypond-devel@gnu.org;
re...@codereview-hr.appspotmail.com
Sent: Wednesday, December 26, 2012 1:15 PM
Subject: Re: Doc: CG Clarifying about Examples with overrides (issue
7013043)
Hello,
On 26 December 2012 12:52, philehol...@googlemail.com wrote:
https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/doc-work.itexi
File Documentation/contributor/doc-work.itexi (right):
https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/doc-work.itexi#newcode158
Documentation/contributor/doc-work.itexi:158: @ref{Introduction to LSR}.
Thanks for the update. I still think it's worth a simple reminder here:
'Dont' forget to tag the snippet with docs'.
https://codereview.appspot.com/7013043/
Is there any case where a snippet would not have the docs tag?
James
Yes. Probably about 80% of them don't (I could work it out, but CBA at
present). These are for snippets which are viewable/searchable on the LSR,
but not as part of the documentation. Generally, we scrutinise those tagged
with docs more carefully for syntax and formatting. If they're not tagged
with docs, we're more lenient.
If they don't have this tag, they're not exported to the snippets/docs
tarball and won't appear in snippets or be available for doc writers. And
since the process is 1. contributor submits; 2. LSR meister approves; 3.
Tarball is grabbed; 4. Makelsr is run; 5. Git is updated; the time between
1 and 5 can be considerable, and so they effectively get lost.
--
Phil Holmes
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
LGTM https://codereview.appspot.com/7013043/ ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Doc: CG Clarifying about Examples with overrides (issue 7013043)
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi#newcode155 Documentation/contributor/doc-work.itexi:155: The correct way to add [changes like this] to the documentation is to Why the [] ? https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi#newcode157 Documentation/contributor/doc-work.itexi:157: LilyPond Snippet Repository (LSR). It will then appear automatically in Please add a note to say that it must be tagged with docs, and should be tagged with other relevant subject areas. The tags dictate which section(s) of the Snippets list that the snippet appears in. https://codereview.appspot.com/7013043/ ___ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
Other than my suggestion below, LGTM
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi
File Documentation/contributor/doc-work.itexi (right):
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi#newcode161
Documentation/contributor/doc-work.itexi:161: it as a @emph{selected
snippet) in the position you suggest within the
Change to
... as a @emph{selected snippet), if appropriate, to the
documentation.
https://codereview.appspot.com/7013043/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi
File Documentation/contributor/doc-work.itexi (right):
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi#newcode161
Documentation/contributor/doc-work.itexi:161: it as a @emph{selected
snippet) in the position you suggest within the
This is Phil - as was the BealingsPlayford comment earlier. Should the
closing ) be a } ?
https://codereview.appspot.com/7013043/
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Re: Doc: CG Clarifying about Examples with overrides (issue 7013043)
Reviewers: Trevor Daniels, phileholmes_googlemail.com,
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi
File Documentation/contributor/doc-work.itexi (right):
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi#newcode155
Documentation/contributor/doc-work.itexi:155: The correct way to add
[changes like this] to the documentation is to
On 2012/12/25 09:10:01, bealingsplayfordnews wrote:
Why the [] ?
This is a standard way to to clarify the antecedent. Also you will see
it used to denote missing text [ ... ] or more commonly to denote a
mistake or inaccuracy in a quote without it being attributed to the
author of the text it is being quoted in (i.e '[sic]').
Anyway, enough of that, I have rewritten the sentence.
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi#newcode157
Documentation/contributor/doc-work.itexi:157: LilyPond Snippet
Repository (LSR). It will then appear automatically in
On 2012/12/25 09:10:01, bealingsplayfordnews wrote:
Please add a note to say that it must be tagged with docs, and should
be tagged
with other relevant subject areas. The tags dictate which section(s)
of the
Snippets list that the snippet appears in.
This is already explained in the section that is referred to at the end
of the paragraph and which users should be reading anyway (section 7.0 -
specifically in 7.3). This paragraph is not a replacement for that.
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi#newcode161
Documentation/contributor/doc-work.itexi:161: it as a @emph{selected
snippet) in the position you suggest within the
On 2012/12/25 10:16:02, Trevor Daniels wrote:
Change to
... as a @emph{selected snippet), if appropriate, to the
documentation.
Done.
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-work.itexi#newcode161
Documentation/contributor/doc-work.itexi:161: it as a @emph{selected
snippet) in the position you suggest within the
On 2012/12/25 11:01:33, PhilEHolmes wrote:
This is Phil - as was the BealingsPlayford comment earlier. Should
the closing
) be a } ?
Done.
Description:
Doc: CG Clarifying about Examples with overrides
Issue 3051
Paraphrased an email response sent by Trevor Daniels.
Please review this at https://codereview.appspot.com/7013043/
Affected files:
M Documentation/contributor/doc-work.itexi
Index: Documentation/contributor/doc-work.itexi
diff --git a/Documentation/contributor/doc-work.itexi
b/Documentation/contributor/doc-work.itexi
index
ff6e0f07216048a90c71e31019fe01f0e79370a4..4d860e3cd3e61f947c3ed2bc23c89a4d114c2714
100644
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -146,6 +146,21 @@ Please prepare a formal git patch.
@end enumerate
+@contributions that contain examples using overrides or tweaks
+
+Examples that use overrides, tweaks, customer Scheme functions etc. are
+(with very few exceptions) not included in the main text of the manuals;
+as there would be far too many, equally useful, candidates.
+
+The correct way to add [changes like this] to the documentation is to
+submit your example, with appropriate explanatory text and tags, to the
+LilyPond Snippet Repository (LSR). It will then appear automatically in
+the Snippets lists. See @ref{Introduction to LSR}.
+
+Once added as a snippet, documentation writers can then also easily add
+it as a @emph{selected snippet) in the position you suggest within the
+Notation Reference manual.
+
Once you have followed these guidelines, please send a message to
lilypond-devel with your documentation submissions. Unfortunately
there is a strict “no top-posting” check on the mailing list; to avoid
___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel
