|
|
Created:
14 years, 5 months ago by nicolas.sceaux Modified:
13 years ago CC:
lilypond-devel_gnu.org Visibility:
Public. |
DescriptionDoc: improve doc on markup command writing
Patch Set 1 #
Total comments: 42
Patch Set 2 : Take into accout remarks from review #
MessagesTotal messages: 7
Hi, This patch improves (as I hope) the documentation on markup command definition, by using more complete examples. It also tries to address an issue that was raised on -devel, concerning the different syntax between built-in and user-defined markup command definition. As I'm not (obviously) a native English speaker, comments on style are most welcome. Nicolas
Sign in to reply to this message.
On Sun, Nov 22, 2009 at 3:37 PM, <nicolas.sceaux@gmail.com> wrote: > As I'm not (obviously) a native English speaker, comments on style are > most welcome. Whenever I try to publish my comments, I get a 500 server error. :( I'll summarize them below: - use @var{foo} for variable names. This applies to both the .itely file, and also the .scm file (instead of `props') - examples (including @lisp) should have a blank line above and below them - please add a blank line after the @unnumbered... line - there were a few extra commas in a few sentences, but don't worry about them. Then English is quite understandable, and it would be good to have another person proofread+fix these issues anyway, as part of a general cleanup up the Extending manual. Cheers, - Graham
Sign in to reply to this message.
Nicolas, These are mainly stylistic changes. Please double-check to ensure I haven't changed the meaning of what you intended. Cheers, Ian http://codereview.appspot.com/157133/diff/1/2 File Documentation/extending/programming-interface.itely (right): http://codereview.appspot.com/157133/diff/1/2#newcode1045 Documentation/extending/programming-interface.itely:1045: The @code{layout} and @code{props} arguments of markup commands bring a The @code{layout} and @code{props} arguments to markup commands provide a http://codereview.appspot.com/157133/diff/1/2#newcode1046 Documentation/extending/programming-interface.itely:1046: context to the markup interpretation: font size, line width, etc. context for interpretation by the markup: e.g. font size line width etc. http://codereview.appspot.com/157133/diff/1/2#newcode1048 Documentation/extending/programming-interface.itely:1048: Properties defined in @code{paper} blocks are accessible through the The @code{layout} argument allows access to properties defined in http://codereview.appspot.com/157133/diff/1/2#newcode1049 Documentation/extending/programming-interface.itely:1049: @code{layout} argument, using the @code{ly:output-def-lookup} function. @code{paper} blocks, using the @code{ly:output-def-lookup} function. http://codereview.appspot.com/157133/diff/1/2#newcode1060 Documentation/extending/programming-interface.itely:1060: title, composer, etc. It is also a way to configure a markup command title, composer, etc. It is also the way to configure the behaviour http://codereview.appspot.com/157133/diff/1/2#newcode1061 Documentation/extending/programming-interface.itely:1061: behavior: when a command uses e.g. the font size in its processings, of a markup command: for example, when a command uses font size during processing, http://codereview.appspot.com/157133/diff/1/2#newcode1062 Documentation/extending/programming-interface.itely:1062: instead of having a @code{font-size} argument, the font size is read the font size is read from @code{props} rather than having a @code{font-size} http://codereview.appspot.com/157133/diff/1/2#newcode1063 Documentation/extending/programming-interface.itely:1063: from @code{props}, and the caller of a markup command may change the argument. The caller of a markup command may change the value http://codereview.appspot.com/157133/diff/1/2#newcode1064 Documentation/extending/programming-interface.itely:1064: value of the font size property to change the behavior. Property values of the font size property in order to change the behaviour. Use the http://codereview.appspot.com/157133/diff/1/2#newcode1065 Documentation/extending/programming-interface.itely:1065: are read from the @code{props} argument using the @code{chain-assoc-get} @code{chain-assoc-get} function to read property values from the @code{props} . http://codereview.appspot.com/157133/diff/1/2#newcode1066 Documentation/extending/programming-interface.itely:1066: function. argument. http://codereview.appspot.com/157133/diff/1/2#newcode1074 Documentation/extending/programming-interface.itely:1074: As an example, a markup command which draws a double box around a piece The following example defines a markup command to draw a double box http://codereview.appspot.com/157133/diff/1/2#newcode1075 Documentation/extending/programming-interface.itely:1075: of text will be defined. around a piece of text. http://codereview.appspot.com/157133/diff/1/2#newcode1077 Documentation/extending/programming-interface.itely:1077: First, one should try to build an approximative result using markups. Firstly, we need to build an approximate result using markups. http://codereview.appspot.com/157133/diff/1/2#newcode1078 Documentation/extending/programming-interface.itely:1078: By consulting the builtin @ruser{Text markup commands}, we find that the Consulting the @ruser{Text markup commands} shows us the http://codereview.appspot.com/157133/diff/1/2#newcode1103 Documentation/extending/programming-interface.itely:1103: taking one argument (the text), and draws the two boxes, with some taking one argument (the text). This draws the two boxes, with some http://codereview.appspot.com/157133/diff/1/2#newcode1129 Documentation/extending/programming-interface.itely:1129: changed by the user. Moreover, it would be better to distinguish changed by the user. Also, it would be better to distinguish http://codereview.appspot.com/157133/diff/1/2#newcode1130 Documentation/extending/programming-interface.itely:1130: between the padding between the two boxes, from the padding between the the padding between the two boxes, from the padding between the http://codereview.appspot.com/157133/diff/1/2#newcode1131 Documentation/extending/programming-interface.itely:1131: inner box and the text. We introduce a new property, inner box and the text. So we will introduce a new property, http://codereview.appspot.com/157133/diff/1/2#newcode1134 Documentation/extending/programming-interface.itely:1134: as follow: now as follows: http://codereview.appspot.com/157133/diff/1/2#newcode1152 Documentation/extending/programming-interface.itely:1152: the comma in the @code{\override} argument: they allow to introduce a the comma in the @code{\override} argument: they allow you to introduce a
Sign in to reply to this message.
Thank you Ian for the careful review. Nicolas http://codereview.appspot.com/157133/diff/1/2 File Documentation/extending/programming-interface.itely (right): http://codereview.appspot.com/157133/diff/1/2#newcode1045 Documentation/extending/programming-interface.itely:1045: The @code{layout} and @code{props} arguments of markup commands bring a On 2009/11/22 16:59:50, Ian Hulin wrote: > The @code{layout} and @code{props} arguments to markup commands provide a Done. http://codereview.appspot.com/157133/diff/1/2#newcode1046 Documentation/extending/programming-interface.itely:1046: context to the markup interpretation: font size, line width, etc. On 2009/11/22 16:59:50, Ian Hulin wrote: > context for interpretation by the markup: e.g. font size line width etc. context for the markup interpretation (it is the markup that is interpreted, to build a stencil). http://codereview.appspot.com/157133/diff/1/2#newcode1048 Documentation/extending/programming-interface.itely:1048: Properties defined in @code{paper} blocks are accessible through the On 2009/11/22 16:59:50, Ian Hulin wrote: > The @code{layout} argument allows access to properties defined in Done. http://codereview.appspot.com/157133/diff/1/2#newcode1049 Documentation/extending/programming-interface.itely:1049: @code{layout} argument, using the @code{ly:output-def-lookup} function. On 2009/11/22 16:59:50, Ian Hulin wrote: > @code{paper} blocks, using the @code{ly:output-def-lookup} function. Done. http://codereview.appspot.com/157133/diff/1/2#newcode1060 Documentation/extending/programming-interface.itely:1060: title, composer, etc. It is also a way to configure a markup command On 2009/11/22 16:59:50, Ian Hulin wrote: > title, composer, etc. It is also the way to configure the behaviour Done. http://codereview.appspot.com/157133/diff/1/2#newcode1061 Documentation/extending/programming-interface.itely:1061: behavior: when a command uses e.g. the font size in its processings, On 2009/11/22 16:59:50, Ian Hulin wrote: > of a markup command: for example, when a command uses font size during > processing, Done. http://codereview.appspot.com/157133/diff/1/2#newcode1062 Documentation/extending/programming-interface.itely:1062: instead of having a @code{font-size} argument, the font size is read On 2009/11/22 16:59:50, Ian Hulin wrote: > the font size is read from @code{props} rather than having a @code{font-size} Done. http://codereview.appspot.com/157133/diff/1/2#newcode1063 Documentation/extending/programming-interface.itely:1063: from @code{props}, and the caller of a markup command may change the On 2009/11/22 16:59:50, Ian Hulin wrote: > argument. The caller of a markup command may change the value Done. http://codereview.appspot.com/157133/diff/1/2#newcode1064 Documentation/extending/programming-interface.itely:1064: value of the font size property to change the behavior. Property values On 2009/11/22 16:59:50, Ian Hulin wrote: > of the font size property in order to change the behaviour. Use the Done. http://codereview.appspot.com/157133/diff/1/2#newcode1065 Documentation/extending/programming-interface.itely:1065: are read from the @code{props} argument using the @code{chain-assoc-get} On 2009/11/22 16:59:50, Ian Hulin wrote: > @code{chain-assoc-get} function to read property values from the @code{props} . Done. http://codereview.appspot.com/157133/diff/1/2#newcode1066 Documentation/extending/programming-interface.itely:1066: function. On 2009/11/22 16:59:50, Ian Hulin wrote: > argument. Done. http://codereview.appspot.com/157133/diff/1/2#newcode1074 Documentation/extending/programming-interface.itely:1074: As an example, a markup command which draws a double box around a piece On 2009/11/22 16:59:50, Ian Hulin wrote: > The following example defines a markup command to draw a double box Done. http://codereview.appspot.com/157133/diff/1/2#newcode1075 Documentation/extending/programming-interface.itely:1075: of text will be defined. On 2009/11/22 16:59:50, Ian Hulin wrote: > around a piece of text. Done. http://codereview.appspot.com/157133/diff/1/2#newcode1077 Documentation/extending/programming-interface.itely:1077: First, one should try to build an approximative result using markups. On 2009/11/22 16:59:50, Ian Hulin wrote: > Firstly, we need to build an approximate result using markups. Done. http://codereview.appspot.com/157133/diff/1/2#newcode1078 Documentation/extending/programming-interface.itely:1078: By consulting the builtin @ruser{Text markup commands}, we find that the On 2009/11/22 16:59:50, Ian Hulin wrote: > Consulting the @ruser{Text markup commands} shows us the Done. http://codereview.appspot.com/157133/diff/1/2#newcode1103 Documentation/extending/programming-interface.itely:1103: taking one argument (the text), and draws the two boxes, with some On 2009/11/22 16:59:50, Ian Hulin wrote: > taking one argument (the text). This draws the two boxes, with some Done. http://codereview.appspot.com/157133/diff/1/2#newcode1129 Documentation/extending/programming-interface.itely:1129: changed by the user. Moreover, it would be better to distinguish On 2009/11/22 16:59:50, Ian Hulin wrote: > changed by the user. Also, it would be better to distinguish Done. http://codereview.appspot.com/157133/diff/1/2#newcode1130 Documentation/extending/programming-interface.itely:1130: between the padding between the two boxes, from the padding between the On 2009/11/22 16:59:50, Ian Hulin wrote: > the padding between the two boxes, from the padding between the Done. http://codereview.appspot.com/157133/diff/1/2#newcode1131 Documentation/extending/programming-interface.itely:1131: inner box and the text. We introduce a new property, On 2009/11/22 16:59:50, Ian Hulin wrote: > inner box and the text. So we will introduce a new property, Done. http://codereview.appspot.com/157133/diff/1/2#newcode1134 Documentation/extending/programming-interface.itely:1134: as follow: On 2009/11/22 16:59:50, Ian Hulin wrote: > now as follows: Done. http://codereview.appspot.com/157133/diff/1/2#newcode1152 Documentation/extending/programming-interface.itely:1152: the comma in the @code{\override} argument: they allow to introduce a On 2009/11/22 16:59:50, Ian Hulin wrote: > the comma in the @code{\override} argument: they allow you to introduce a Done.
Sign in to reply to this message.
Le 22 nov. 2009 à 17:10, Graham Percival a écrit : > On Sun, Nov 22, 2009 at 3:37 PM, <nicolas.sceaux@gmail.com> wrote: >> As I'm not (obviously) a native English speaker, comments on style are >> most welcome. > > Whenever I try to publish my comments, I get a 500 server error. :( > I'll summarize them below: > - use @var{foo} for variable names. This applies to both the .itely > file, and also the .scm file (instead of `props') Actually, this variable (where properties are accumulated) is named `props' everywhere in scm/define-markup-command.scm. I change other meaningless argument names to foo. > - examples (including @lisp) should have a blank line above and below them > - please add a blank line after the @unnumbered... line OK. Thank you. Nicolas
Sign in to reply to this message.
On 11/22/09 10:50 AM, "Nicolas Sceaux" <nicolas.sceaux@gmail.com> wrote: > Le 22 nov. 2009 à 17:10, Graham Percival a écrit : > >> On Sun, Nov 22, 2009 at 3:37 PM, <nicolas.sceaux@gmail.com> wrote: >>> As I'm not (obviously) a native English speaker, comments on style are >>> most welcome. >> >> Whenever I try to publish my comments, I get a 500 server error. :( >> I'll summarize them below: >> - use @var{foo} for variable names. This applies to both the .itely >> file, and also the .scm file (instead of `props') > > Actually, this variable (where properties are accumulated) is named > `props' everywhere in scm/define-markup-command.scm. I change other > meaningless argument names to foo. > I think that what Graham meant was you should use @var{props} instead of `props'. The way we indicate a variable name in the documentation is not with CAPS or with 'single quotes' but with @var{macro}. Thanks, Carl
Sign in to reply to this message.
It would make sense to apply <URL:http://codereview.appspot.com/160048> first and make this patch work on top of that. There may be cases where a separate property-bind like this is useful in called routines, and the markup commands from the mentioned patch might make use of it for implementing #:properties. However, a separate property-bind function can't do the job of entering the properties and their defaults into the command reference. For this reason, it is probably not a good idea to encourage users to use a macro like this in markups defined with define-markup-command. They would need to be rewritten in order to get the properties mentioned in the command reference. Since the above-mentioned patch does not provide user-level documentation, it would make sense to adapt your patch here for documenting the functionality provided by the above-mentioned patch of mine.
Sign in to reply to this message.
|