Arnold I think this might be better on dev list than bug so I am ccing dev in case you are not subscribed to that list yet.
On 23 October 2012 12:54, ArnoldTheresius <arnold.we...@siemens.com> wrote: > James wrote >> Hello, >> >> ... >> >> Well I have applied this patch and I am not sure it is appropriate for >> the glossary, perhaps the explanation, but the example is far too >> complex for our documentation - perhaps as a snippet maybe. >> >> Also you have not followed really any of our style guidelines in the >> Contributor's Guide (line lengths, texinfo syntax, @lilypond >> [variables] etc. so there is still a fair amount of work to do here >> before it will even be considered. >> >> So, I can do this for you (shepherd your patch) or you are more than >> welcome to use our git-cl and patch review process yourself until you >> need to push it, when you will need to prepare a properly formatted >> git patch that is easy to apply etc (i notice your $LILYPOND_GIT >> variable is not the standard one, making it slightly more work for >> those that need to apply it - I am no expert but managed to work it >> out). I don't want to discourage you from submitting patches, but we >> do have a well defined (if slightly idiosyncratic work-flow - so I am >> told, I only know LilyPond so cannot comment) >> >> If you do choose to do this yourself you should read our Contributor's >> Guide and follow the style guidelines there, and I suggest that you >> take the huge example out, cut it right back as you can and include it >> as a snippet. >> >> See: >> >> http://lilypond.org/doc/v2.16/Documentation/contributor/documentation-work >> >> and >> >> http://lilypond.org/doc/v2.16/Documentation/contributor/summary-for-experienced-developers >> (the reviews section specifically). >> >> James >> >> _______________________________________________ >> bug-lilypond mailing list > >> bug-lilypond@ > >> https://lists.gnu.org/mailman/listinfo/bug-lilypond > > Well, > > I noticed, the example is quite huge. But I'm not sure, can it be understood > without example? > If so, we can completely remove the snippets. Yes this is best. There is no reason why you cannot include an @seealso section with a snippet, however this should be done as a separate patch. Snippets are a bit more complex than normal doc edits (or rather there are more things to consider). So i would for now forgo the snippet and the @seealso section and just get the text in. Then once you are ok with the process we can add a new snippet and then add the @seealso reference in the glossary to complete the cross reference. > > I think the line length of 80 characters was succeded only in the > 'snippets'. The specified line length is 72 characters (66 preferred). > > What could a 'separate snippet' want to tell? Perhaps "How to build a pitch > usage chart manually". Snippets are designed for more complex examples (for example we don't use \overrides or \tweak-like examples in the core documentation if we can avoid it - these are created as snippets and referred to at the end of the section in the @seealso part, likewise massive amounts of Scheme code have no business being the core documentation for general examples either, again the snippets are the place for this). This is all explained in the Documentation guidelines and policy in the Contributor's Guide. So I suggest that if you want to show your high bass clef that you give as simple as an example as you can (remove any extraneous code) and submit that as a snippet/new for the documentation. You 'chart' might be better added to the Lilypond Snippet Repository directly - see http://lsr.dsi.unimi.it/LSR/html/whatsthis.html Be aware though that this is currently running LilyPond 2.14.x code, it is a bit behind current LilyPond stable, but will get there eventually. > > I did try to use only the syntax I found in the '.tely' file, but I did not > look (deeply) into the documentation contributors guide. Sorry for that. That's ok, as I said, we are quite fastidious about this so as to keep everyone as consistent as possible. Everything about the doc is autobuilt (including the whole website) based on the texinfo code, make doc can take a long time on many machines and if this breaks for any reason it means we cannot get *any* documentation on the lilypond.org site, hence the 'rules' in the Contributor's Guide. There are a few of us who will and can help you, so please don't get frustrated if you find people pointing out that you didn't do X or you must do Y at first. The contributor's guide, while seemingly a lot to read, is actually a very good reference when you cannot remember all the rules. > > To upload contributions by myself: My computer I'm working with lilypond is > not connected to any network. (For that reason I prefer the PDF of the > handbooks to the HTML version) Right, but the documents are all built from one source, so this is why we care about formatting and syntax etc. Everything (HTML and PDF) must build. > So at first I'll need to find some > description how to operate this in a 'package mode', i.e. GIT-access (in a > HTML browser) at one computer, transfer files to and from the working > computer (the most easy step), import and export the file packages in the > working computers lilydev VM. > Do you know where such an description is? I'm not sure exactly what you mean here. If you mean how do you move a LilyDev VM from one machine to another, you can (if you use VirtualBox) clone/copy the *.vhd (or *.vdi) file to another machine and choose it as the hardisk of a new Virtual Machine on the networked computer, but that seems a very crude method (*vdi files can get huge). If you have LilyDev on more than one machine (as I have), I simply make changes and make a git formatted patch and just transfer my changes that way (email or dropbox or usb stick), reapply you patch to your LilyDev on the networked machine, but maybe I have misunderstood what you mean here. James _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel