Re: GDP: renaming Program {usage, reference}
I hope this contribution isn't too late, but here goes. I'm commenting here before I have a look closely at the PDFs and possibly get bogged down in detail. Isn't the purpose of the Internals Reference to show Lilypond users how to customize/interpreter the compiler to produce source code which will represent and produce music notation in a way that is convenient and comprehensible to them? Don't they then have the option of doing this by programming at either one of two levels, i.e. using the Lilypond language (variables, accessing Lilypond 'objects', 'attributes ' or 'methods'), or if needed, dropping into Lilypond's internal macro language, Scheme. If I understand correctly your Internals Reference needs to cover both these levels of usage, and maybe a good title may be Customization and Internals Reference Manual (CIR)? Or have I missed several points in taking my helicopter view of the GPD green fields site :-)? Cheers, Ian Hulin (Now off to have a look at the PDFs). Graham Percival-2 wrote: The strong editorial decision from a few months ago is this: Notation Reference: defines the lilypond input syntax. Application Usage: how to compile the syntax, how to convert to/from the syntax (including old versions), including the syntax in other programs, etc. Internals Reference: defines the under the hood lilypond stuff. Learning Manual: prepares users for those other manuals. (this is explained at the top of policy.txt -- if it's not clear, please suggest a rewrite) For people who like to print out PDFs, I expect them to print out the LM, NR, and AU. If they want to save paper, by all means pick and choose -- for example, I wouldn't print out any of NR chapter 2, since I've never used any of the notation in it. But there is certainly no the NR is the only manual you should print out thing. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user -- View this message in context: http://www.nabble.com/GDP%3A-renaming-Program-%7Busage%2C-reference%7D-tf4742154.html#a13665226 Sent from the Gnu - Lilypond - User mailing list archive at Nabble.com. ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: renaming Program {usage, reference}
Graham Percival wrote: The strong editorial decision from a few months ago is this: Notation Reference: defines the lilypond input syntax. I think it describes a lot more than just the syntax. Application Usage: how to compile the syntax, how to convert to/from the syntax (including old versions), including the syntax in other programs, etc. Internals Reference: defines the under the hood lilypond stuff. Which doesn't really make sense, since you have to look under the hood every time you want to make a property setting. Note: I'm not saying that I disagree on the currently proposed division into separate manuals, just about your description of them. /Mats ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: renaming Program {usage, reference}
Mats Bengtsson wrote: Graham Percival wrote: The strong editorial decision from a few months ago is this: Notation Reference: defines the lilypond input syntax. I think it describes a lot more than just the syntax. Sorry, I was misusing a word again -- I didn't mean syntax. I should have said the lilypond input format. Or even better, How to write the text files that lilypond interprets. Does not include complete details about properties, contexts, etc. Internals Reference: defines the under the hood lilypond stuff. Which doesn't really make sense, since you have to look under the hood every time you want to make a property setting. Err, remember that the Program Reference is now the IR. The NR will describe how to construct tweaks in a compact manner, the LM will describe how to construct tweaks in a legible manner, but finding out what the Voice #'padding property does (and what the default value is!) is only done in the IR. (in this case, #'padding is used as examples in the LM and NR, so of course people will know about it -- but the actual place to find this info is the IR) Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
GDP: LM Specification (was RE: GDP: renaming Program {usage, reference})
Mats Bengtsson wrote Graham Percival wrote: The strong editorial decision from a few months ago is this: Notation Reference: defines the lilypond input syntax. I think it describes a lot more than just the syntax. /Mats I do too. I wonder if it might be useful to discuss and find a consensus on what the purpose of the NR is in rather more detail? Here's a strawman specification to knock about if people think a specification might be useful to guide documentation writers in the future. The Notation Reference aims to provides accurate and complete information (in several presentational formats) to enable users to reproduce anything in a score found on their bookshelves. It assumes the user has mastered the concepts introduced in the Learning Manual, particularly the way in which a LilyPond score is structured, but does not rely on the Learning Manual for any informational content. The primary purpose is to enable users to understand and modify the statements in the templates to meet their needs, or to construct their own scores from scratch. As a reference manual, the material is grouped logically into thematical sections; unlike the Learning Manual it is not intended to be read sequentially. The purpose of every LilyPond command is explained and demonstrated in a brief example to show its syntax and effect. Cross-references are provided to more substantial examples which show the use of the commands in a more realistic context, and to the technical descriptions of the various cammands in the Internals Reference. The manual is indexed with both LilyPond and musical terms. Trevor D ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: renaming Program {usage, reference}
Graham Percival wrote: Internals Reference: defines the under the hood lilypond stuff. Which doesn't really make sense, since you have to look under the hood every time you want to make a property setting. Err, remember that the Program Reference is now the IR. The NR will describe how to construct tweaks in a compact manner, the LM will describe how to construct tweaks in a legible manner, but finding out what the Voice #'padding property does (and what the default value is!) is only done in the IR. (in this case, #'padding is used as examples in the LM and NR, so of course people will know about it -- but the actual place to find this info is the IR) I agree completely on what you write here! Funny, up to version 1.6 or so, it used to be called LilyPond Internals, then it changed to Program Reference. Now we are almost back again. I'm not convinced that Internals Reference is the best title, but let's not spend too much effort on that discussion now and work on the contents instead. /Mats ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: renaming Program {usage, reference}
Eyolf Østrem wrote: In other words: if it is a strong editorial decision that there should be one document which contains only the details about notational syntax and nothing else, then my suggestion of course falls flat. The document I'm talking about is broader: Everything You Need To Know To Produce A Score With Lilypond (Once It's Installed And Provided You Don't Need To Change Too Many Scheme Lists). I see. Well, as you mentioned, you could well make arguments in favor of including most of the AU in a everything you need to know. Conversely, somebody could well argue that nobody needs to know about Bagpipe music. :) The strong editorial decision from a few months ago is this: Notation Reference: defines the lilypond input syntax. Application Usage: how to compile the syntax, how to convert to/from the syntax (including old versions), including the syntax in other programs, etc. Internals Reference: defines the under the hood lilypond stuff. Learning Manual: prepares users for those other manuals. (this is explained at the top of policy.txt -- if it's not clear, please suggest a rewrite) For people who like to print out PDFs, I expect them to print out the LM, NR, and AU. If they want to save paper, by all means pick and choose -- for example, I wouldn't print out any of NR chapter 2, since I've never used any of the notation in it. But there is certainly no the NR is the only manual you should print out thing. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: renaming Program {usage, reference}
On 04.11.2007 (01:23), Graham Percival wrote: Eyolf Østrem wrote: Sorry - my fault, I was thinking of the Program Usage, which to a large extent has to do with how to write code to produce a certain output (the LP-book part) leaving bits and pieces which not necessarily belongs together with the notation reference thematically, but which on the other hand is so few pages, dealing with the fundamentals of how to run the program, that it seems logical to have it in one place. I don't follow -- especially the to a large extent. In the current version of lilypond-program.pdf, 12 out of 31 pages (not counting the licence and the index) are about lilypond-book -- that's what I meant with to a large extent. The rest is Installation and setup (8pp), command-line usage etc (7 pp), and the conversion utilities (3p). In the newly-renamed Application Usage, is there anything other than chapter 4 which you believe should be in NR? I really can't see anything of the sort. No, only ch. 4 belongs in a Notation Ref., strictly speaking (even this is debatable, depending on HOW strictly one is speaking). I'm thinking more of the NR as the document that one would want to save to the harddisk, or even print out as a handy reference to cover all the things that one would need to know in the day-to-day dealings with LP. Given the character of LP, as a compiler of external text files, and not a gui or a wysiwyg environment, text input and compilation will always go hand in hand. This is the reason why I'd like to have ch. 3 in the same book (on my imaginary shelf, together with the vim manual and the LaTeX companion). This would leave the three pages about conversion, which don't necessarily belong in the same book, but which doesn't do any harm either. 2.2. Text editor support could well defend its place in a notational referece: how to edit LP code, which leaves 1 Install, which is more README or man page-like, and setup, which is mainly about mac problems... In other words: if it is a strong editorial decision that there should be one document which contains only the details about notational syntax and nothing else, then my suggestion of course falls flat. The document I'm talking about is broader: Everything You Need To Know To Produce A Score With Lilypond (Once It's Installed And Provided You Don't Need To Change Too Many Scheme Lists). Eyolf -- All hope abandon, ye who enter here! -- Dante Alighieri ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: renaming Program {usage, reference}
Eyolf Østrem wrote: Sorry - my fault, I was thinking of the Program Usage, which to a large extent has to do with how to write code to produce a certain output (the LP-book part) leaving bits and pieces which not necessarily belongs together with the notation reference thematically, but which on the other hand is so few pages, dealing with the fundamentals of how to run the program, that it seems logical to have it in one place. I don't follow -- especially the to a large extent. In the newly-renamed Application Usage, is there anything other than chapter 4 which you believe should be in NR? I really can't see anything of the sort. Now, chapter 4 is debatable. But with the exception of 4.6.3, this chapter is dealing with including lilypond input inside lilypond-book -- the NR remains the source of information about lilypond input. As such, I decided it made more sense in AU than in NR. I'll grant that it might be nice to include info like 4.6.3 in a later chapter of the NR; sorting out this kind of thing *is* on my list. My mind could be changed on this issue, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
GDP: renaming Program {usage, reference}
There are four manuals about LilyPond: the @emph{Learning Manual},
the @emph{Notation Reference}, the @emph{Program Usage}, and the
@emph{Program Reference}.
This is somewhat confusing, since there are two very different manuals
whose name both begins with Program.
Does anybody object if I rename Program Reference to Internals
Reference? or maybe Tweak Reference? or... ? (renaming Program Usage
is also an option)
Cheers,
- Graham
___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: renaming Program {usage, reference}
2007/11/3, [EMAIL PROTECTED] [EMAIL PROTECTED]:
Quoting Graham Percival [EMAIL PROTECTED]:
Does anybody object if I rename Program Reference to Internals
Reference? or maybe Tweak Reference? or... ? (renaming Program Usage
is also an option)
... or merging it with Notation Reference, where it belongs :-)
Not at all! The notation Reference is here to help users produce
scores using predefined commands and interface, whereas the Internals
Reference describes the way LilyPond *internally* works, to possibly
allow them to change the interface itself.
I vote for Internals Reference (by the way, I'm not sure if we have
to say Internals or Internal Reference -- as a French guy, I'd
prefer the adjective). Besides, this is already how we used to call it
in the Documentation sources, with @internalsref{} links.
Valentin
___
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: renaming Program {usage, reference}
Valentin Villenave wrote: 2007/11/3, [EMAIL PROTECTED] [EMAIL PROTECTED]: Quoting Graham Percival [EMAIL PROTECTED]: Does anybody object if I rename Program Reference to Internals Reference? or maybe Tweak Reference? or... ? (renaming Program Usage is also an option) ... or merging it with Notation Reference, where it belongs :-) Not at all! The notation Reference is here to help users produce scores using predefined commands and interface, whereas the Internals Reference describes the way LilyPond *internally* works, to possibly allow them to change the interface itself. Well, some of the NR -- as well as LM -- discusses the way lilypond works internally, in order to facilitate using the PR. A much better reason (and one which closes the merge discussion, IMO) is that the Program Reference is generated automagically from the source code. It lies totally outside the scope of GDP, or any doc work that I've ever done in lilypond. Cheers, - Graham ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: renaming Program {usage, reference}
Hi Graham (et al.), (renaming Program Usage is also an option) How about Application Usage? Best regards, Kieren. ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
Re: GDP: renaming Program {usage, reference}
On 03.11.2007 (12:43), Valentin Villenave wrote: 2007/11/3, [EMAIL PROTECTED] [EMAIL PROTECTED]: Quoting Graham Percival [EMAIL PROTECTED]: Does anybody object if I rename Program Reference to Internals Reference? or maybe Tweak Reference? or... ? (renaming Program Usage is also an option) ... or merging it with Notation Reference, where it belongs :-) Not at all! The notation Reference is here to help users produce scores using predefined commands and interface, whereas the Internals Reference describes the way LilyPond *internally* works, to possibly allow them to change the interface itself. Sorry - my fault, I was thinking of the Program Usage, which to a large extent has to do with how to write code to produce a certain output (the LP-book part) leaving bits and pieces which not necessarily belongs together with the notation reference thematically, but which on the other hand is so few pages, dealing with the fundamentals of how to run the program, that it seems logical to have it in one place. e -- user-friendly adj. Programmer-hostile. Generally used by hackers in a critical tone, to describe systems that hold the user's hand so obsessively that they make it painful for the more experienced and knowledgeable to get any work done. See menuitis, drool-proof paper, user-obsequious. ___ lilypond-user mailing list lilypond-user@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-user
