Comment #9 on issue 2171 by m...@apollinemike.com: 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.
_______________________________________________
bug-lilypond mailing list
bug-lilypond@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-lilypond
