Re: Issue 2171 in lilypond: Patch: Implements DOM-id property for grobs.

[lilypond]

Comment #9 on issue 2171 by address@hidden: Patch: Implements DOM-id  
property for grobs.
http://code.google.com/p/lilypond/issues/detail?id=2171

> If people would not consider it totally fine to just ignore every  
> standard we set up, I would not be appalled to a degree where I act in  
> that manner.

I do not feel that I act this way.

> There are new stencil commands "start-enclosing-DOM-mode",  
> and "end-enclosing-DOM-node".  Those are entirely undocumented.

Do a git grep on:

resetcolor
setcolor
no-origin
url-link

Aside from additions to the change-log attesting that these functions were  
added, there is no documentation for them.  That is because they are  
internal stencil functions that users will never see but are used to pass  
around information.

If you want to bring up the issue that all stencils should be documented  
and/or user accessible that is fine.  But when you say "those are entirely  
undocumented", I get the impression that you feel that documenting this  
sort of stencil falls into the "every standard se set up" category, which  
is not the case.

As for usability, I agree that undocumented features are bad.  As James can  
attest, I often contact him after I've added a feature to start working on  
documentation.  However, as it stands, the documentation of this feature is  
no less or more than other documentation for similar features.  And if you  
have a problem with the doc string, then that is an easy separate commit I  
can make later down the line rather than going through the time drain fo a  
revert.

I agree with you that it is bad for LilyPond to become more  
underdocumented, but I disagree that it is an undocumented mess.  I think  
that the documentation in LilyPond is some of the best (if not the best) of  
any project of its kind, and I think that as long as people make an honest  
effort to work with James to improve the documentation around new features,  
it will continue to achieve that comparatively hight standard.

What I'm asking is for you to please be aware that the way you communicate  
has a real impact on how people spend their time, be it in e-mail exchanges  
or in the reverting of patches.  It has this impact because you're very  
good at what you do, so I take it seriously.  This is not unlike a long  
conversation we had a few weeks ago where you made several assertions about  
a patch I wrote that proved be false, causing me to do a great deal of  
research because I trusted that they were assertions and not questions,  
only to read at the end of the exchange "Well, it is good we had this  
little talk then.  Be sure to keep this reasonably discoverable in the  
program documentation, and you'll be pretty safe from future  
keyword-triggered watchdog attacks."  I very much appreciate the rigor with  
which you police LilyPond and think it is necessary for the program.  If  
you could formulate that policing in the form of questions instead of  
assertions and not let it result in reverting patches, it would save me  
lots of time and allow me get better at making LilyPond better.