Re: glossary - add 'high bass clef'

[James]

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 <address@hidden> 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