Issue 7013043: Doc: CG Clarifying about Examples with overrides (Closed)
|
Created:
11 years, 4 months ago by pkx166h Modified:
11 years, 4 months ago CC:
lilypond-devel_gnu.org Base URL:
http://git.savannah.gnu.org/gitweb/?p=lilypond.git/trunk/ Visibility:
Public. |
DescriptionDoc: CG Clarifying about Examples with overrides
Issue 3051
Paraphrased an email response sent by Trevor Daniels.
Patch Set 1 #
Total comments: 9
Patch Set 2 : With corrections from dev list #
Total comments: 3
Patch Set 3 : Additions from Phil #MessagesTotal messages: 14
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-w... File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-w... 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-w... 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.
Sign in to reply to this message.
Other than my suggestion below, LGTM https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-w... File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-w... 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."
Sign in to reply to this message.
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-w... File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-w... 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 } ?
Sign in to reply to this message.
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-w... File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-w... 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-w... 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-w... 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-w... 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.
Sign in to reply to this message.
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/do... File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/do... 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.
Sign in to reply to this message.
https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-w... File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/1/Documentation/contributor/doc-w... 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 [...].
Sign in to reply to this message.
https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/do... File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/do... 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.
Sign in to reply to this message.
https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/do... File Documentation/contributor/doc-work.itexi (right): https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/do... 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"'.
Sign in to reply to this message.
Hello, On 26 December 2012 12:52, <PhilEHolmes@googlemail.com> wrote: > > https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/do... > File Documentation/contributor/doc-work.itexi (right): > > https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/do... > 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
Sign in to reply to this message.
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.
Sign in to reply to this message.
----- Original Message ----- From: "James" <pkx166h@gmail.com> To: <pkx166h@gmail.com>; <tdanielsmusic@googlemail.com>; <phileholmes@googlemail.com>; <dak@gnu.org>; <lilypond-devel@gnu.org>; <reply@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, <PhilEHolmes@googlemail.com> wrote: >> >> https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/do... >> File Documentation/contributor/doc-work.itexi (right): >> >> https://codereview.appspot.com/7013043/diff/3003/Documentation/contributor/do... >> 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
Sign in to reply to this message.
LGTM
Sign in to reply to this message.
LGTM
Sign in to reply to this message.
author James Lowe <pkx166h@gmail.com> Tue, 25 Dec 2012 06:14:36 +0000 (06:14 +0000) committer James Lowe <pkx166h@gmail.com> Mon, 31 Dec 2012 11:07:00 +0000 (11:07 +0000) commit dce1ebaef6f044236a600bb1dcb9c5d9029ce042
Sign in to reply to this message.
|
