On Sat, 28 Jun 2008 19:43:44 +0200 "Valentin Villenave" <[EMAIL PROTECTED]> wrote:
> 2008/6/28 Neil Puttock <[EMAIL PROTECTED]>: > > > I wish that were the case; got any tips on working faster (without > > causing massive breakage)? :) Focus. Let's say that you're working on \underline: - does this command take 1 argument or more? It's one. So copy the previous one-argument example: \markup { one \\bold two } and change the \\bold to \\underline. Boom, example done. Next command. Assuming that you keep that previous example in your copy buffer, the entire command can be done in 30 seconds. - go through the entire list, just taking care of simple stuff. Don't play with examples. For example, you noticed that the \box command looks ugly if you don't \override the padding. Don't fix that stuff yet. Just go through the list making the examples. - if there's a command with multiple arguments, dump a FIXME there. And then move on. Don't think about it. - once you've gone through the list, start compiling the docs and go get coffee. When you come back, hopefully they'll be done. skim through the html pages; if you see something ugly (like \box), *then* go back and fiddle with the example. This is how you can cover 90% of the docs in an hour. It's dull, it's repetitive, but it gets stuff done. Then you do the same thing for multi-argument commands. Now the .scm file is a mixture of finished and unfinished commands, but you don't need to search for commands to fill in -- you just search for FIXME. Here's your basic example: \markup { \command { one two } } If you can shove a markup command into the above format, do it and stop thinking about it. If you can't, leave the FIXME alone and move on to the next one. Again, DON'T THINK ABOUT IT. - compile docs, get coffee, fix remaining. At this point there's probably about 10 commands left. They'll require special attention, though, reading source code, asking on -devel, whatever. But that's fine... it's a short list. The end is in sight. You might be able to farm out one or two of these to other people if it's too hard (this is a general tip, I don't think it'll apply to you). Also, I'm much happier, because the docs look pretty complete; I can see that there's only a few things left. If you fell off the edge of the Earth, I know that I can finish the remaining commands myself. > Similarly, I'm looking for tips on how to write sensible docs on hairy > stuff such as 1.8 Text :) Here, the big question is figuring out what you don't need to discuss. At the moment, you're thinking about explaining all the different text alignment commands, because they aren't in the appendix. Once Neil has added all those examples -- and these definitely do fall into the "trivial multi-arg commands" category, and therefore only take an hour -- I suspect that we'll find that you don't need to discuss them. Basically, stop thinking about "explaining everything there is to do about text". Instead, think about "explain enough abotu text so that users can understand the \markup command reference in the appendix". Again, this is much easier if you can actually *see* what the command reference looks like... but if you can't, you just need to imagine it. That's what I have to do all the time, with the possibility of snippets, new texi2html output, deciding what to cover in the LM vs. the NR, etc. > (I've just seen Nicolas has made my font-size docs nearly obsolete > less than an hour ago; I'm both thrilled and desperate.) If your font-size docs were written properly, it should only take a few minutes to update them. Cheers, - Graham _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org http://lists.gnu.org/mailman/listinfo/lilypond-devel