Re: [frogs] my contribution: barCheckNumber to endSpanners |
[ Thread Index |
Date Index
| More lilynet.net/frogs Archives
]
- To: "Carl D. Sorensen" <c_sorensen@xxxxxxx>
- Subject: Re: [frogs] my contribution: barCheckNumber to endSpanners
- From: John Mandereau <john.mandereau@xxxxxxxxx>
- Date: Sat, 10 Jan 2009 16:28:52 +0100
- Cc: "frogs@xxxxxxxxxxx" <frogs@xxxxxxxxxxx>, "lilypond-devel@xxxxxxx" <lilypond-devel@xxxxxxx>
- Dkim-signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:message-id:date:from :user-agent:mime-version:to:cc:subject:references:in-reply-to :content-type:content-transfer-encoding; bh=ed2mRJsHteZDZd6q1JxVAW12j/oTUs8Ru9y//YBQwi0=; b=MGvmHHb5+Yh8KGaar6u1OJ+ZUdrdZ9p0uQJo8rEXfL5EM1IyiHGlFEPIhJi2jBRJ/3 CV491cg99UrgnDZ4nNsT7jKLW7bNDjQer+Azb+Dq1rSwi9Bf76HFwVzGI/sNwsqnm4ly NaaP5hAiY8YddiB72GXVWjrg+qeW1TMcvZ7Dc=
- Domainkey-signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=message-id:date:from:user-agent:mime-version:to:cc:subject :references:in-reply-to:content-type:content-transfer-encoding; b=RSgeWFe258H3B1HmrQ8CSE4eVLoZgmbGFOa+K6gfmZRJl9xd0ONe9nlaBAssOlFUjT OIosrUR45wCGwjNQImKmzsGq9R9u52r44ugeg37goWD/RVNBkHtD6jSiAgUhy1lm4+I/ l2AgU70u5NQIkfRsVvt7Bbjyl8H1l4xBBCXsA=
Carl D. Sorensen a écrit :
I propose something different. I think the current NR documentation is
right, with a usage description in the section of the NR, and a short
description from the docstring in the appendix that lists all music
functions. The reason I use the Identifiers page is that it's a quick read
of available functions -- if it gets longer because we have usage
instructions it won't be as useful to scan quickly.
Good point, but this is not incompatible with what I proposed: I think the
short documentation string is useful even throughout the NR, it documents
the function prototype in a concise way, which allows to concentrate on
usage details in the explanation.
If we want to move to having this documentation all in the music functions
(which may be a good idea, but will require some substantial rewriting of
the documentation building system, IMO), we should have *two* documentation
strings in the music function: 1) a description string, which is like the
current docstrings, and 2) a usage string, which is like the current text
from the NR.
I think the effort vs. gain of maintanibility ratio is not worth doing this.
Cheers,
John
---
----
Join the Frogs!